顧客セントラル API
顧客セントラル API は、顧客情報と構成詳細にアクセスするためのエンドポイントを提供します。
この API を使用して、以前に顧客セントラルのインターフェイスで生成された情報レコード (カード) を取得します。
この API にアクセスするには、admin または sn_esm_agent ロールが必要です。また、この API をインスタンスで使用できるようにするには、com.sn_csm_customer_central プラグインを有効にする必要があります。
詳細については、「 顧客セントラル」を参照してください。
顧客セントラル - GET /cust_central/custinfo/{context}/{context_instance}/{target}
特定の顧客コンテキストの顧客情報と構成詳細を返します。
顧客コンテキストは、指定した顧客コンテンツテーブル (コンシューマー [csm_consumer] または連絡先 [customer_contact] テーブル)、およびその関連ターゲットテーブルによって決定されます。この情報は、顧客情報コンテキスト [sn_customercentral_cust_info_config] テーブルにあります。
- リスト構成 [sn_customercentral_list_config]
- レコード構成 [sn_customercentral_record_config]
- レポート構成 [sn_customercentral_report_config]
- レポートグループ構成 [sn_customercentral_report_group_config]
必要な追加の設定レコードは、顧客セントラルのインターフェイスで定義する必要があります。詳細については、「 顧客セントラルの構成」を参照してください。
URL 形式
バージョニングされた URL:/api/sn_customercentral/{api_version}/cust_central/custinfo/{context}/{context_instance}/{target}
デフォルトの URL:/api/sn_customercentral/cust_central/custinfo/{context}/{context_instance}/{target}
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ:文字列 |
| context | 使用する顧客コンテキストテーブルの名前。 有効な値:
データタイプ:文字列 |
| context_instance | context パラメーターで指定されたテーブル内の、返されるレコードの sys_id。 データタイプ:文字列 |
| target | context パラメーターで指定された顧客コンテキストテーブルに関連付けられたターゲットテーブル。context パラメーターと target パラメーターの組み合わせで、一意の顧客情報コンテキストを定義します。 データタイプ:文字列 テーブル:顧客情報コンテキスト [sn_customercentral_cust_info_config] |
| 名前 | 説明 |
|---|---|
| before | 指定された日時より前に作成されたすべての設定レコードを返します。 日付タイプ:文字列 形式:YYYY-MM-DD または glide.sys.date_format システムプロパティで定義された形式 デフォルト:現在のセッション時間の前に作成されたすべての設定レコードを返します。 |
| end | 返される最後のレコード。この値を使用してレコード取得をページネーションするか、start パラメーターとともに使用して、返される特定のレコードセットを選択します。 データタイプ:数値 デフォルト:ファイル内の最後のレコード |
| start | レコード取得を開始する開始レコードインデックス。この値を使用して、レコード取得をページネーションします。この機能により、レコード数に関係なく、管理しやすい小さなチャンクに分割してすべてのレコードを取得できます。 負の数を渡さないでください。 データタイプ:数値 デフォルト:0 |
| 名前 | 説明 |
|---|---|
| なし |
ヘッダー
次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。サポートされるタイプ:application/json または application/xml。 デフォルト: application/json |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 400 | 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。パスパラメーターに有効な値が含まれていることを確認します。 |
| 401 | 権限がありません。ユーザー資格情報が間違っているか、渡されていません。 |
| 500 | 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。 |
応答本文のパラメーター (JSON または XML)
| 名前 | 説明 |
|---|---|
| cards_info | 指定された顧客に関連付けられている連絡先カードのリスト。 データタイプ:アレイ (コンテンツは選択した顧客によって異なります) |
| cards_info.data_configurations | 構成情報。 データタイプ:オブジェクト |
| cards_info.data_configurations.aggregate_field | 集計する列名。 データタイプ:文字列 |
| cards_info.data_configurations.aggregate_function | 指定されたテーブル列を集計するために使用する関数。 可能な値:
データタイプ:文字列 |
| cards_info.data_configurations.decimal_precision | 返される小数点以下の桁数。 データタイプ:数値 |
| cards_info.data_configurations.filter_query | レポートで使用されるデータを調整するために使用するクエリ文字列。 データタイプ:文字列 |
| cards_info.data_configurations.group_by | レポートデータをグループ化するために使用する列の名前。 データタイプ:文字列 |
| cards_info.data_configurations.number_of_groups | レポートに表示するグループの最大数。 可能な値:
データタイプ:文字列 |
| cards_info.data_configurations.show_other | グループ「その他」がレポート内に表示されるかどうかを示すフラグ。number_of_groups パラメーターで定義されているとおりにすべてのグループが表示されない場合は、非表示グループの値が結合され、「その他」という 1 つの見出しの下に表示されます。 可能な値:
データタイプ:ブーリアン |
| cards_info.data_configurations.source_id | レポートのソース情報のテーブル名または sys_id。これは cards_info.reportGroupConfigurations.data_configurations.source_type パラメーターの情報に関連付けられています。 データタイプ:文字列 |
| cards_info.data_configurations.source_type | ソーステーブルを識別するために使用される cards_info.reportGroupConfigurations.data_configurations.source_id パラメーター内の情報のタイプ。 可能な値:
データタイプ:文字列 |
| cards_info.data_configurations.stack_by_field | レポートに「積み重ね基準」を実装するときに使用するテーブル列の名前。 データタイプ:文字列 |
| cards_info.data_configurations.sys_id | レポート構成で使用されるレポートの sys_id。 データタイプ:文字列 |
| cards_info.data_configurations.trend_field | 傾向分析で使用するテーブル列の名前。 データタイプ:文字列 |
| cards_info.data_configurations.trend_interval | 傾向情報の時間間隔。たとえば、週、月、年などです。 データタイプ:文字列 |
| cards_info.data_configurations.type | レポートのタイプ (単一スコア、ドーナツ、垂直、線グラフ、積み重ね棒グラフなど) データタイプ:文字列 |
| cards_info.encodedQuery | レポートに表示されるデータを調整するために使用するエンコードされたクエリ文字列。 データタイプ:文字列 |
| cards_info.fields | 関連レコード内のフィールドを定義する名前と値のペアのリスト。 データタイプ:オブジェクトのアレイ |
| cards_info.fields.label | フィールドラベル。 データタイプ:文字列 |
| cards_info.fields.value | フィールド値。 データタイプ:文字列 |
| cards_info.listLimit | ページネーション制限。リストカードに表示するレコードの数。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations | レポートグループを定義するオブジェクトのリスト。 データタイプ:オブジェクトのアレイ |
| cards_info.reportGroupConfigurations.data_configurations | 構成情報。 データタイプ:オブジェクト |
| cards_info.reportGroupConfigurations.data_configurations.aggregate_field | 集計する列名。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.aggregate_function | 指定されたテーブル列を集計するために使用する関数。 可能な値:
データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.decimal_precision | 返される小数点以下の桁数。 データタイプ:数値 |
| cards_info.reportGroupConfigurations.data_configurations.filter_query | レポートで使用されるデータを調整するために使用するクエリ文字列。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.group_by | レポートデータをグループ化するために使用する列の名前。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.number_of_groups | レポートに表示するグループの最大数。 可能な値:
データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.show_other | グループ「その他」がレポート内に表示されるかどうかを示すフラグ。number_of_groups パラメーターで定義されているとおりにすべてのグループが表示されない場合は、非表示グループの値が結合され、「その他」という 1 つの見出しの下に表示されます。 可能な値:
データタイプ:ブーリアン |
| cards_info.reportGroupConfigurations.data_configurations.source_id | レポートのソース情報のテーブル名または sys_id。これは cards_info.reportGroupConfigurations.data_configurations.source_type パラメーターの情報に関連付けられています。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.source_type | ソーステーブルを識別するために使用される cards_info.reportGroupConfigurations.data_configurations.source_id パラメーター内の情報のタイプ。 可能な値:
データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.stack_by_field | レポートに「積み重ね基準」を実装するときに使用するテーブル列の名前。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.sys_id | レポート構成で使用されるレポートの sys_id。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.trend_field | 傾向分析で使用するテーブル列の名前。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.trend_interval | 傾向情報の時間間隔。たとえば、週、月、年などです。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.data_configurations.type | レポートグループに関連付けられたレポートのタイプ (donut や single_core など)。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.style_configurations | 関連するレポートグループ内で使用するスタイル。 データタイプ:オブジェクト |
| cards_info.reportGroupConfigurations.style_configurations.colorPalette | レポートで使用される色。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.style_configurations.scoreColor | レポート内のスコア値の色。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.style_configurations.show_zero | 0 に等しいデータポイントをレポートに表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.reportGroupConfigurations.title | レポートグループのタイトル。 データタイプ:文字列 |
| cards_info.reportGroupConfigurations.type | 情報が返されるファイルタイプ。 常に sn_customercentral_report_config です。 データタイプ:文字列 |
| cards_info.sourceTableName | 関連するリストカードに使用されるテーブルの名前。 データタイプ:文字列 |
| cards_info.style_configurations | 関連するレポート内で使用するスタイル。 データタイプ:オブジェクト |
| cards_info.style_configurations.colorPalette | レポートで使用される色。 データタイプ:文字列 |
| cards_info.style_configurations.dataLabelConfig | レポートでのデータラベルの表示方法を制御する設定パラメーター。 データタイプ:オブジェクト |
| cards_info.style_configurations.dataLabelConfig.showTotal | レポートに合計を表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.height | 関連するレポートの高さ。 データタイプ:文字列 単位:ピクセルまたは「auto」 |
| cards_info.style_configurations.hideRegister | カードにレジスターを表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.registerConfig | レポートでのレジスターの表示方法を制御する構成値。 データタイプ:オブジェクト |
| cards_info.style_configurations.registerConfig.hideBorder | レジスターの周囲の境界線を非表示にするかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.registerConfig.showPercentages | レジスターのパーセンテージを表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.registerPosition | カード内のレジスターの位置。 データタイプ:文字列 |
| cards_info.style_configurations.scoreColor | レポート内のスコア値の色。 データタイプ:文字列 |
| cards_info.style_configurations.showDataLabels | レポート内にデータラベルを表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.showTooltip | レポート内にツールヒントを表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.show_zero | 0 に等しいデータポイントをレポートに表示するかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| cards_info.style_configurations.width | 関連するレポートの幅。 データタイプ:文字列 単位:ピクセルまたは「auto」 |
| cards_info.subheader_fields | 関連するカードのサブヘッダーに表示する詳細。 データタイプ: オブジェクト |
| cards_info.subheader_fields.avatar | 指定された context_instance に関連付けられたアバターのファイル名 (連絡先のアバターなど)。 データタイプ:文字列 |
| cards_info.subheader_fields.subheader_tags | レコードサブヘッダーに関連付けられたタグのリスト (エスカレーションタグなど)。 データタイプ:アレイ (内容はさまざまです) |
| cards_info.subheader_fields.sys_id | 関連付けられた顧客の sys_id。 データタイプ:文字列 テーブル:ユーザー [sys_user] |
| cards_info.subheader_fields.title | サブヘッダーに表示するタイトル。 データタイプ:文字列 |
| cards_info.title | カード (レコード) のタイトル。 データタイプ:文字列 |
| cards_info.type | 情報が返されるファイルタイプ。 可能な値:
データタイプ:文字列 |
| cards_info.viewName | cards_info.sourceTableName で指定されたテーブルに構成されたビューの名前。 データタイプ:文字列 |
| has_more_records | さらに取得するレコードがあるかどうかを示すフラグ。 可能な値:
データタイプ:ブーリアン |
| レイアウト | 行あたりの列数。カンマ区切りの各値は、レポート表示の列の幅を定義します。たとえば「6,6」は、それぞれが 6 ユニット幅で、行あたり合計で 12 ユニット (最大) の 2 つの列があることを示します。値「3,6,3」は、3 列の行を示します。 データタイプ:文字列 |
| status | 要求の HTTP ステータス。 データタイプ:文字列 |
cURL 要求
curl "https://instance.servicenow/api/sn_customercentral/cust_central/custinfo/csm_consumer/a0488cfbdb1b1200b6075200cf9619db/interaction" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"layout": "6,6",
"cards_info": [
{
"title": "Consumer",
"type": "sn_customercentral_record_config",
"subheader_fields": {
"title": "Sam Collins",
"subheader_tags": [],
"avatar": "",
"sys_id": "64488cfbdb1b1200b6075200cf9619db"
},
"fields": [
{
"label": "Mobile phone",
"value": ""
},
{
"label": "Business phone",
"value": ""
},
{
"label": "Email",
"value": "sam.collins@mailinator.com"
},
{
"label": "Street",
"value": "144 2nd St"
},
{
"label": "City",
"value": "San Francisco"
},
{
"label": "State / Province",
"value": "CA"
}
]
},
{
"title": "High priority cases",
"type": "sn_customercentral_report_group_config",
"reportGroupConfigurations": [
{
"title": "Escalated",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "active=true^active_escalationISNOTEMPTY^EQ^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "c169a0f50f3b0010e6d4fd820b767e2e"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
},
{
"title": "P1",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "active=true^priority=1^EQ^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "cce86cb50f3b0010e6d4fd820b767eba"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
},
{
"title": "SLA breached",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "task_sla",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "task.active=true^task.sys_class_name=sn_customerservice_case^stage!=cancelled^task.closed_atISEMPTY^sla.type=SLA^has_breached=true^EQ^taskIN59b65dc4db952200d75270f5bf96193eccc8cf82db912200d75270f5bf9619de^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "e739a0f50f3b0010e6d4fd820b767e22"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
}
]
},
{
"title": "Case overview",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "donut",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "state",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "d169216c0f770010e6d4fd820b767ea8"
},
"style_configurations": {
"width": "auto",
"height": "auto",
"colorPalette": [
"#278ecf",
"#4bd762",
"#ffca1f",
"#ff9416",
"#d42ae8"
],
"hideRegister": false,
"registerConfig": {
"hideBorder": true,
"showPercentages": false
},
"registerPosition": "right",
"showDataLabels": false,
"dataLabelConfig": {
"showTotal": false
},
"showTooltip": true
}
},
{
"title": "Recent cases",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "sn_customerservice_case"
},
{
"title": "Recent chat interactions",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=false^type=chat^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "interaction"
},
{
"title": "Recent phone calls",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=false^type=phone^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "interaction"
},
{
"title": "Recent viewed articles",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "user=64488cfbdb1b1200b6075200cf9619db^viewed=true^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "kb_use"
},
{
"title": "Contracts",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^state=Active^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "ast_contract"
},
{
"title": "Entitlements",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^end_date=NULL^ORend_date>=2020-05-07 07:00:00^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "service_entitlement"
}
],
"has_more_records": false,
"status": "200"
}
}