GainsightバルクREST API
重要 - 画像/情報は四半期ごとのリリースで更新されます!
四半期ごとのリリースにて、最新の機能・情報を反映し、画像を含めた情報は更新されます。
この記事では、Gainsightカスタムオブジェクトから大量のデータを取得し、ジョブステータスを確認するために使用できるREST APIについて解説します。
重要：GainsightバルクAPIの制限は、1時間当たり10の呼び出し/1日当たり100の呼び出しです
前提条件
このドキュメントでAPIを使うには、必要なサブドメイン又はカスタムドメインが作成されていることを確認してください。
例えば: https://customobjectapi.gainsightcloud.com 又は https://customobjectapi.yourcompany.com
注意：Gainsightに接続するために、エンドポイントURLにあなたのドメインを追加することができます。
ドメインの作成方法の詳細については、Gainsightドメインのセットアップ記事を参照してください。
API認証
API アクセスは、固有のアクセスキーを使用して制御されます。REST API要求を送信するGainsightテナントのアクセスキーを取得するにはGainsight 管理者に連絡してください。アクセス キーを生成または共有する方法に関する詳細情報については、Gainsight管理者はAPI アクセス キーを生成の記事を参照できます。
アクセスキーを取得した後は、GainsightへのすべてのAPIリクエストのリクエストヘッダー「accesskey」の一部として、アクセスキーを渡す必要があります。AccessKeyに有効期限はありません。
一括ジョブリクエストの送信
このAPIを使って、一括ジョブリクエストを送信し、Gainsightカスタムオブジェクトからデータをダウンロードすることができます。
方法の詳細
|
APIの詳細 |
説明 |
|---|---|
|
リクエスト方法 |
ポスト |
|
リクエストエンドポイント |
https://<customer domain>/v3/exports/data/bulk/{objectName} 注意：<customer domain>と{objectName}を会社のドメインとオブジェクト名に置き換えて、ジョブリクエストを送信します。 |
|
ヘッダー |
|
リクエストのサンプル
{
"select": [
"Name",
"Csm",
"Csm__gr.name",
"Billing_State__gc",
"Industry",
"Segment__gc",
"Unique_ID__gc"
],
"where": {
"conditions": [
{
"name": "Name",
"alias": "A",
"value": [
"Gainsight"
],
"operator": "CONTAINS"
},
{
"name": "Csm__gr.name",
"alias": "B",
"value": [
"J"
],
"operator": "CONTAINS"
}
],
"expression": "A OR B"
},
"orderBy": {
"Name": "asc",
"Csm__gr.name": "desc"
},
"limit": 100000,
"offset": 0
}
リクエスト本文:
- 読み取りAPIのリクエスト本文には、次の要素を指定することができます。
- 返されるフィールド
- どこ：特定の条件に一致するレコードのみを返す条件
- オペレーター：各フィールドの値の例：EQ：等しい、含む、より大きいなど。各データ型でサポートされている演算子のリストについては、サポートされている演算子セクションを参照してください。
- 式: 返されるフィールド間の演算子。例：A又はB、AとBなど。
- オーダー元：レコードが返される順序を昇順 (asc) 又は降順 (desc) で指定する句。
- 制限：返されるレコードの最大数
- デフォルトで制限を超えない場合は、制限は100万に設定されます。例：“限界”:1000000
- オフセット：残りのレコード (昇順又は降順) を取得するレコード番号を入力することができます。例：条件に一致するレコード数が60の場合、オフセットに10を入力すると、10から60までのレコードが取得されます。
- オフセットが渡されない場合、デフォルトでオフセットは0に設定されます。
サポートされている演算子
データタイプの各フィールドでサポートされている演算子は次の通りです:
|
データタイプ |
サポートされている演算子： |
|---|---|
|
文字列 |
等しい、等しくない、以上、超、以下、未満、で始まる、含む、含まない、nullである、nullではない、で終わる |
|
ブール |
等しい、等しくない |
|
日付 |
等しい、等しくない、より大きいか等しい、より大きい、より小さいか等しい、より小さい、間、nullである、nullではない |
|
日時 |
等しい、等しくない、より大きいか等しい、より大きい、より小さいか等しい、より小さい、間、nullである、nullではない |
|
数字 |
等しい、等しくない、以上、超、以下、未満、イン、インでない 、nullである、nullではない、 |
|
GSID |
等しい、等しくない、以上、超、以下、未満、で始まる、含む、含まない、nullである、nullではない、で終わる |
|
Eメール |
等しい、等しくない、以上、超、以下、未満、で始まる、含む、含まない、nullである、nullではない、で終わる |
|
ドロップダウンリスト |
等しい、等しくない、含む、除外する、で始まる、含む、含まない、nullである、nullではない |
|
複数選択ドロップダウンリスト |
含む、除外する、null である、null でない |
|
通貨 |
等しい、等しくない、以上、より大きい、以下、未満、nullである、nullではない、 |
|
パーセンテージ |
等しい、等しくない、以上、より大きい、以下、未満、nullである、nullではない、 |
次の表は読み取りAPIでサポートされている各演算子の列挙型演算子を示しています:
|
オペレーター |
列挙演算子 |
|---|---|
|
EQ |
等しい |
|
NE |
等しくない |
|
LT |
未満 |
|
GT |
より大きい |
|
LTE |
以下 |
|
GTE |
より大きい、または等しい |
|
BTW. |
～の間 |
|
IS_NULL |
nullである |
|
IS_NOT_NULL |
NULLでない |
|
含む |
含む |
|
DOES_NOT_CONTAINS |
含まない |
|
STARTS_WITH |
から始まる |
|
ENDS_WITH |
で終わる |
|
INCLUDES / IN |
含まれる |
|
EXCLUDES / NOT_IN |
除外する |
失敗レスポンスのサンプル
- 選択フィールドが渡されない場合。
{
"result": false,
"errorCode": "GSOBJ_ESS_9104",
"errorDesc": "Atleast one select field should be included in the payload.",
"requestId": "c16b2fc9-09e7-4bec-b2bb-b611ff2972c3",
"data": null,
"message": null
}
- 無効な選択フィールド又は無効な制限など。
{
"result": false,
"errorCode": "GSOBJ_ESS_9150",
"errorDesc": "Malformed Query Exception.",
"requestId": "a3e168fa-4fcc-4475-9938-83a1c553b0b8",
"data": null,
"message": null
}
一括APIジョブのステータス
このAPIを使って、一括APIのジョブステータスを確認することができます。ジョブの応答には、ジョブのステータス (進行中、完了、又は失敗) が含まれます。
方法の詳細
|
APIの詳細 |
説明 |
|---|---|
|
リクエスト方法 |
ゲット |
|
リクエストエンドポイント |
https://<customer domain>/{statusURL} 注意：<customer domain>と{statusURL}を会社のドメインと実際のステータスURLに置き換えて、ジョブのステータスを確認します。statusURLは、ジョブに対するジョブ送信応答で返されます。 |
|
ヘッダー |
|
進行中応答のサンプル
ジョブがまだ進行中の場合、応答にはIN_PROGRESSとしてjobStatusが含まれています。
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "62988764-9e59-4a68-bfdc-069b9bbe783c",
"data": {
"jobId": "15f435bf-fb69-4901-a265-ba6e206f38f8",
"jobStatus": "IN_PROGRESS"
},
"message": null
}
成功レスポンスのサンプル
ジョブが完了すると、応答データにはjobStatusが完了として含まれます。
応答にはchunkDetailsが含まれます。エクスポートされたデータのサイズに基づいて、チャンクの数が生成されます。各チャンクにはその特定のチャンクデータを取得するために必要な、対応するchunkURLがあります。対応するチャンクURLと共に、そのチャンクの制限とオフセットが返されます。
エクスポートされたレコードの合計は、応答データのtotalRecordsに表示されます。
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "9486dd24-ec9d-4ef9-b6af-862a978b2155",
"data": {
"jobId": "c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a",
"jobStatus": "COMPLETED",
"totalRecords": 28954,
"chunkDetails": [
{
"chunkURL": "v3/exports/data/job/c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a/chunk/1/results",
"offset": 0,
"limit": 20000
},
{
"chunkURL": "v3/exports/data/job/c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a/chunk/2/results",
"offset": 20000,
"limit": 8954
}
]
},
"message": null
}
失敗レスポンスのサンプル
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "95e0a38b-181e-475a-bbff-1e6ae269a568",
"data": {
"jobId": "15f435bf-fb69-4901-a265-ba6e206f38f8",
"jobStatus": "FAILED",
"errorDesc": "Malformed Query Exception.",
"errorCode": "GSOBJ_ESS_9150",
"internalRequestId": "85f84db8-0672-4005-a160-7796c9bb9188"
},
"message": null
}
チャンクデータを取得
このAPIを使うと、大量のデータをチャンク (複数のファイル) でダウンロードすることができます。ジョブステータスの応答で見つかったチャンクURLを使って、データをダウンロードすることができます。
方法の詳細
|
APIの詳細 |
説明 |
|---|---|
|
リクエスト方法 |
ゲット |
|
リクエストエンドポイント |
https://<customer domain>/{chunkURL} 注意：<customer domain>と{chunkURL}を会社のドメインと実際のチャンクURLに置き換えて、チャンクデータを取得します。完了したジョブのジョブステータスには、chunkURLが返されます。 |
|
ヘッダー |
|
応答のサンプル
"Name","Csm","Csm__gr.name","Billing_State__gc","Industry","Segment__gc","Unique_ID__gc" "Acme","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Latisha Jones","Kansas","Government","Mid-Market","JB000056" "Foo","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Latisha Jones","Virginia","Technology","Mid-Market","JB000021" "Gainsight","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Mathew","Texas","Non-profit","Mid-Market","JB000111"