外部 ID マッピング API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：12分

    • 外部の Contact Center as a Service (CCaaS) プラットフォームが ServiceNow レコードのルーティング識別子を保存および取得できるようにします。

    この API は、コンタクトセンター統合コア (sn_ct_ctr_it_core) ストアアプリケーションの一部として、CCaaS プロバイダーが CCaaS 外部 ID マッピング [sn_ct_ctr_it_core_ccaas_external_id_mapping] テーブルで外部 ID を取得または設定できるようにします。この API は sn_ct_ctr_it_core 名前空間にあり、sn_ct_ctr_it_core.admin ロールが必要です。

    この API はマルチプロバイダー環境をサポートしているため、組織はプロバイダーごとに個別のルーティング ID 名前空間を維持しながら、複数の CCaaS プラットフォームと同時に統合できます。

    CCaaS プラットフォーム (Genesys Cloud、Five9、Amazon Connect など) がケース、タスク、またはインタラクションを外部エージェントにルーティングすると、一意のルーティング ID が生成されます。この API は、これらの外部ルーティング ID をレコードにマッピングする一元化されたメカニズムを提供し、CCaaS プラットフォームと ServiceNow 間の双方向の追跡と相関を可能にします。

    ユースケース
    外部ルーティング相関
    CCaaS プラットフォームは、ケースを外部エージェントにルーティングするときにルーティング ID を生成します。CCaaS プラットフォームからの将来のイベント、コールバック、またはステータス更新を関連付けるために、この ID を保存する必要があります。
    この API は、外部ルーティング ID をマッピングテーブルに格納し、レコードとそれを生成したプロバイダーに関連付けます。
    双方向トラッキング
    レポート、分析、およびトラブルシューティングのために、どの外部ルーティングセッションがどのケースに対応しているかを追跡する必要がある場合があります。
    この API を使用して任意のレコードの外部ルーティング ID を取得し、ダッシュボードとレポートに完全なルーティング履歴を表示できます。
    統合の柔軟性
    CCaaS プラットフォームが異なれば、ケース、タスク、インタラクション、カスタムテーブルなど、さまざまなテーブルのルーティング ID を保存する必要がある場合があります。
    この API は有効なテーブル名を受け入れるため、将来のユースケースのために拡張できます。エンドポイントは、ワークフローに応じて個別に呼び出すことができます。

    CCaaS システムとの統合の詳細については、「 Integrating with contact centers」を参照してください。

    外部 ID マッピング:GET /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    特定のレコードの外部ルーティング ID マッピングを取得します。

    このエンドポイントは、マッピングテーブルにクエリを実行して、指定されたレコードとプロバイダーに保存されている外部ルーティング ID を検索します。このエンドポイントを使用して、CCaaS プラットフォームによってレコードにアサインされた外部ルーティング ID を取得します。

    URL 形式

    デフォルト URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    tableName 必須です。レコードを含む ServiceNow テーブル名。任意の有効なテーブル名を指定できます。たとえば、sn_customerservice_case、sn_customerservice_task、インタラクション、カスタムテーブルなどです。

    データタイプ：文字列
    documentId 必須です。外部 ID マッピングを取得する ServiceNow レコードのsys_id。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (JSON)
    名前 説明
    なし

    ヘッダー

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

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

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

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

    名前 説明
    result 要求に関する情報を含む結果オブジェクト。

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

    "result": { 
   "data": "String",
   "message": "String"
}
    result.data マッピングのデータ。

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

    "data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "String"
}
    result.data.document_id 外部 ID マッピングを取得する ServiceNow AI Platform レコードのsys_id。

    データタイプ：文字列
    result.data.document_table レコードを含む ServiceNow AI Platform テーブル名。

    データタイプ：文字列
    result.data.external_id CCaaS プラットフォームからの外部ルーティング ID。

    最大文字数:200

    データタイプ：文字列
    result.data.external_provider 外部プロバイダー [awa_external_provider] テーブルからのプロバイダーのsys_id。

    データタイプ：文字列
    result.error.message 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.error 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.error.message 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.message API 要求の結果を説明するメッセージ。

    データタイプ：文字列
    result.status 要求の成功または失敗のステータス。
    有効な値：
    • 成功
    • 失敗

    データタイプ：文字列

    この例では、 f584a7b23b3d3e10c524c59a04e45a6f がsys_idケースのマッピングを照会して、CCaaS プラットフォームによって割り当てられている外部ルーティング ID を見つけます。

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'

    応答本文：

    {
  "result": {
    "data": {
      "document_table": "sn_customerservice_case",
      "document_id": "f584a7b23b3d3e10c524c59a04e45a6f",
      "external_id": "200",
      "external_provider": "8b592fb64f140210c0338ef0b1ce0b18"
    }
  }
}

    外部 ID マッピング:PUT /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    ServiceNowレコードの外部ルーティング ID マッピングを作成または更新します。

    このエンドポイントはべき等であるため、同じパラメーターで複数回呼び出すと、重複するマッピングを作成するのではなく、既存のマッピングが更新されます。エンドポイントは、テーブル名、ドキュメント ID、および外部プロバイダーの組み合わせに基づいて、新しいマッピングを挿入するか既存のマッピングを更新するかを自動的に決定します。

    URL 形式

    デフォルト URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    サポートされている要求パラメーター

    表 : 7. パスパラメーター
    名前 説明
    tableName 必須です。レコードを含む ServiceNow テーブル名。任意の有効なテーブル名を指定できます。たとえば、sn_customerservice_case、sn_customerservice_task、インタラクション、カスタムテーブルなどです。

    データタイプ：文字列
    documentId 必須です。外部 ID マッピングを取得する ServiceNow レコードのsys_id。

    データタイプ：文字列
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (JSON)
    名前 説明
    external_id 必須です。CCaaS システムからの外部エージェント ID。

    データタイプ：文字列

    最大長:200 文字
    external_provider 外部プロバイダー [awa_external_provider] テーブルからのプロバイダーレコードのsys_id。これにより、どの CCaaS プラットフォームが外部 ID を生成したかが識別されます。

    データタイプ：文字列

    ヘッダー

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

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    201 作成されました。外部 ID マッピングが正常に作成されました。つまり、新しいマッピングが挿入されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー認証情報が正しくないか、渡されていません。
    403 禁止されました。
    考えられる理由:
    • ユーザーにawa_integration_userロールがありません。
    • glide.awa.enabled プロパティの値が true ではありません。高度なワークアサインメント (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    404 見つかりません。要求されたアイテムが見つかりませんでした。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

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

    名前 説明
    result 要求に関する情報を含む結果オブジェクト。

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

    "result": { 
   "data": "String",
   "message": "String"
}
    result.error.message 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.error 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.error.message 要求が失敗した場合、要求が失敗した理由を説明するメッセージ。

    データタイプ：文字列
    result.message API 要求の結果を説明するメッセージ。

    データタイプ：文字列
    result.status 要求の成功または失敗のステータス。
    有効な値：
    • 成功
    • 失敗

    データタイプ：文字列

    cURL 要求

    この例では、CCaaS プラットフォームからの外部 ID (プロバイダーによって識別 sys_id 8b592fb64f140210c0338ef0b1ce0b18) を格納する方法を示します。

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"external_id\": \"200\",
    \"external_provider\": \"8b592fb64f140210c0338ef0b1ce0b18\"
}" \
--user 'admin':'admin'

    応答本文：

    {
  "result": {
    "message": "External ID mapping record updated for sn_customerservice_case [f584a7b23b3d3e10c524c59a04e45a6f]",
    "status": "success"
  }
}