CCCIF メディアリソース API

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：5分

    • カスタムチャットのチャットボット相互運用性フレームワーク (CCCIF) メディアリソース API は、プライマリボットが関連付けられた ServiceNow インスタンスに添付ファイルをアップロードできるようにするエンドポイントを提供します。

    仮想エージェント (VA) を介して会話しているユーザーからのプライベート添付ファイルをアップロードするには、プライマリボットでこの API を呼び出します。その後、この API によって返される mediaUrl パラメーターを VA API に送信する必要があります。

    添付ファイルが公開されている場合は、仮想エージェントボット統合呼び出しの要求本文で添付ファイル URL を送信するだけです。

    この API にアクセスするには、Conversational Custom Chat Integration (com.glide.cs.custom.adapter) プラグインがアクティブになっている必要があります。さらに、添付ファイルのシステムプロパティを設定する必要があります。

    仮想エージェント API の機能の詳細については、「仮想エージェント API」を参照してください。

    CCCIF - POST /cccif/media/upload

    呼び出された ServiceNow インスタンスにプライベート添付ファイルをアップロードします。このインスタンスにより、添付ファイルが添付ファイル [sys_attachment] テーブルに保存されます。

    仮想エージェント (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 path <file_path> など)
    provider_application_id VA ボットとやり取りする sys_cs_provider_application の sys_id。

    デフォルト：VA ボット間プロバイダーアプリケーションの sys_id
    user_id 必須です。VA ボットとやり取りするユーザーの一意のユーザー識別子。これは、ユーザーごとに一意の文字列にすることができます。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    Accept 応答本文のデータフォーマット。サポートされるタイプ：multipart/form-data
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    Content-Type 応答本文のデータフォーマット。application/json のみをサポートします。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    201 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    404 見つかりません。要求アイテムが見つかりませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON)

    名前 説明
    attachmentId 保存された添付ファイルの sys_id。

    データタイプ：文字列
    error 要求の処理中に検出されたエラーの説明。

    データタイプ：オブジェクト

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail 発生したエラーに関する詳細。

    データタイプ：文字列
    error.message スローされたエラーを説明するメッセージ。

    データタイプ：文字列
    mediaUrl 添付ファイルにアクセスするためにプライマリボットに送信する添付ファイル URL。プライマリボットは、この URL を POST /sn_va_as_service/bot/integration エンドポイントの要求本文の message.attachment.url パラメーターで送信する必要があります。

    データタイプ：文字列
    name 添付ファイルのファイル名。

    データタイプ：文字列
    state 添付ファイルテーブル内の添付ファイルのステータス。
    可能な値：
    • available
    • conditionally available
    • not available
    • pending

    データタイプ：文字列

    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"
  }