CCCIF 미디어 자원 API

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기4분

    • 사용자 지정 채팅 챗봇 상호 운용성 프레임워크(CCCIF) 미디어 자원 API는 기본 봇이 연결된 ServiceNow 인스턴스에 첨부 파일을 업로드할 수 있는 엔드포인트를 제공합니다.

    기본 봇에서 이 API를 호출하여 (VA)를 통해 가상 에이전트 대화를 중인 사용자의 프라이빗 첨부 파일을 업로드합니다. 그런 다음 이 API에서 반환하는 mediaUrl 매개 변수를 VA API로 보내야 합니다.

    첨부 파일이 공개인 경우 가상 에이전트 봇 통합 호출의 요청 본문에 첨부 파일 URL을 보내면 됩니다.

    이 API에 접근하려면 대화형 사용자 지정 채팅 통합(com.glide.cs.custom.adapter) 플러그인이 활성화되어 있어야 합니다. 또한 첨부 파일 시스템 속성을 구성해야 합니다.

    API의 기능에 대한 자세한 내용은 가상 에이전트 API를 가상 에이전트 참조하십시오.

    CCCIF - POST /cccif/media/upload

    첨부 파일 [sys_attachment] 테이블에 첨부 파일을 저장하는 호출 ServiceNow 된 인스턴스에 비공개 첨부 파일을 업로드합니다.

    기본 봇에서 이 메서드를 호출하여 VA(를 통해 가상 에이전트 대화)를 하는 사용자의 프라이빗 첨부 파일을 업로드합니다. 그런 다음 를 사용하여 가상 에이전트 봇 통합 API이 메서드에서 반환되는 mediaUrl 매개 변수를 VA API로 보내야 합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/cccif/media/upload

    기본 URL: /api/now/cccif/media/upload

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수
    이름 설명
    파일 필수 업로드할 파일의 경로입니다.

    데이터 형식: 문자열(예: @File 경로 <file_path>)
    provider_application_id VA 봇과 상호 작용하는 sys_cs_provider_application Sys_id입니다.

    기본값: VA 봇-봇 제공자 애플리케이션의 Sys_id
    user_id 필수 VA 봇과 상호 작용하는 사용자의 고유 사용자 식별자입니다. 각 사용자에 대해 고유한 문자열이 될 수 있습니다.

    데이터 유형: 문자열

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에서 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형: multipart/form-data.
    표 5. 응답 헤더
    헤더 설명
    컨텐츠-형식 응답 본문의 데이터 형식입니다. application/json만 지원합니다.

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    201 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON)

    이름 설명
    attachmentId 저장된 첨부 파일의 Sys_id입니다.

    데이터 유형: 문자열
    오류 요청을 처리하는 동안 탐지된 오류에 대한 설명입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보 발생한 오류에 대한 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지 발생한 오류를 설명하는 메시지입니다.

    데이터 유형: 문자열
    mediaUrl 첨부 파일에 접근하기 위해 기본 봇에 보낼 첨부 파일 URL입니다. 기본 봇은 POST /sn_va_as_service/bot/integration 엔드포인트의 요청 본문 매개변수에서 message.attachment.url 이 URL을 보내야 합니다.

    데이터 유형: 문자열
    이름 첨부 파일의 이름입니다.

    데이터 유형: 문자열
    상태 첨부 파일 테이블의 첨부 파일 상태입니다.
    가능한 값:
    • 사용 가능
    • 조건부로 사용 가능
    • 사용할 수 없음
    • 보류 중

    데이터 유형: 문자열

    cURL 요청

    이 예는 .png 첨부 파일을 업로드하는 방법을 보여줍니다.

    curl --location --request POST 'https://instance.servicenow.com/api/now/v1/cccif/media/upload' \
--header 'Authorization: Basic xxxxxxxxxxxxx' \
--header 'Content-Type:multipart/form-data' \
--form 'user_id="lincoln"' \
--form 'file=@"/Users/Desktop/Screenshot 2021-10-25 at 5.08.14 PM.png"'

    응답:

    Response :{
  "result": {
    "mediaUrl": "https://instance.servicenow.com/api/now/v1/cs/media/vGfewkfAv0VBo2RxmlTM448L789Pp6rqLFLUNYQxZsUUFrsgMA8aW9W0zWx1a5fG",
    "name": "Screenshot 2021-10-25 at 5.08.14 PM.png",
    "state": "pending",
    "attachmentId": "299c648887b73c1022b6a6cd0ebb3534"
  }