タイトル: 会社チームレコードのAPI
この記事では、Gainsight Company TeamsのREST APIとその機能について説明します。
はじめに
管理者は、Company Teams REST外部APIを使用して、Company Teamsレコードの削除、一括削除、アップサート、取得を行うことができます。
前提条件: これらのAPIを使用するには、会社チームがテナントに関して有効になっていることを確認してください。これを行わないと、例外/エラーが発生することがあります。
認証
これらのユーザー管理APIを使用するためには、アクセストークンを生成しなければなりません。
API認証: APIアクセスは、一意のアクセスキーを使用して制御されます。REST APIリクエストの送信さきであるGainsightテナントのアクセスキーを取得するには、Gainsight管理者にお問い合わせください。アクセスキーを生成または共有する方法の詳細については、「API アクセスキーを生成」の記事を参照してください。
アクセスキーを取得した後は、すべてのAPIリクエストのリクエストヘッダーアクセスキーの一部として、アクセスキーをGainsightに渡さなければなりません。アクセスキーの有効期限はありません。
ヘッダー
|
キー |
値 |
|---|---|
|
コンテンツタイプ |
アプリケーション/json |
|
受け入れる |
アプリケーション/json、テキスト/プレーン、*/* |
|
受け入れるー言語 |
en-GB,en-US;q=0.9,en;q=0.8 |
|
<認証> |
<アクセスキー> |
スロットリング制限
以下は、Gainsightで推奨される全体的なAPI制限です (正確な制限はパッケージによって異なる可能性があります)。
- 同期 API コール: 1分あたり100 APIコール/1日あたり50,000 APIコール
|
API |
レートリミット |
|---|---|
|
外部Company Teams API |
1時間あたり100リクエスト/1日あたり1000リクエスト |
メモ：上記のAPI制限はすべて*固定ウィンドウ速度制限です。
* 固定ウィンドウのレート制限により、特定時間におけるAPIリクエスト数を制限します。たとえば、サーバーには、1分あたり100件のリクエストしか受け付けない固定ウィンドウアルゴリズムを実装するレート制限コンポーネントを含めることができます。時間枠は固定されており、特定の時間に始まります。たとえば、サーバーは午前10:00から午前10:01の間に100リクエストのみを処理します。
Company Teamsレコード
Company TeamsレコードのDelete REST APIにより、Gainsight内のCompany Teamsレコードを削除できます。Gainsightの顧客の多くは、Microsoft Dynamicsなどの外部アプリケーションを使用して、アカウントチームを管理し、この情報をGainsightの会社チームオブジェクトと同期します。Delete APIにより、Microsoft Dynamicsなどのソースシステムにおいて対応するレコードが削除されるたびに、Gainsight内の会社チームレコードを自動的に削除することができます。
メソッド
削除
エンドポイントURL
v1/teams/services/companyTeam/{gsid}
パラメータ
|
パラメータ (*必須) |
データタイプ |
値 |
説明 |
|---|---|---|---|
|
GSID* |
文字列 |
- |
会社チームレコードのGSIDを含む文字列値。
|
成功応答の例
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
"data": "Record with GSID: 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ successfully deleted.",
}
失敗応答のサンプル
{
"result": false,
"errorCode": "GSOBJ_1XXX",
"errorDesc": "No data found for given criteria",
"requestId": "58222b97-eaf0-402e-854d-1914987c4b49",
"data": null,
}
Bulk Delete Company Teamsレコード
Company TeamsレコードのDelete REST APIにより、Gainsight内の会社チームレコードを一括で削除することができます。Gainsightの顧客の多くは、Microsoft Dynamicsなどの外部アプリケーションを使用して、アカウントチームを管理し、この情報をGainsightの会社チームオブジェクトと同期します。Bulk Delete APIにより、Microsoft Dynamicsなどのソースシステムにおいて対応するレコードが削除されるたびに、Gainsight内の会社チームレコードを自動的に削除することができます。
メソッド
ポスト
エンドポイントURL
v1/teams/services/companyTeam/delete
リクエスト本文の例
[ "1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9", "1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A", "1P01936XHTA4SF76ZUW5J2RVEZZ8H33C8MAM"]
パラメーター
|
パラメータ (*必須) |
データタイプ |
値 |
説明 |
|---|---|---|---|
|
会社チームGSID*のリスト |
文字列のリスト |
- |
一括削除される会社チームレコードのGSIDのリストを含む文字列値のリスト。
|
成功応答の例
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
"data": {
"success": {
"gsid": [
"1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
"1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A"
]
},
"errors": [
{
"gsid": [
"1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
"1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A"
],
"errorCode": "GSOBJ_1XXX",
"errorDesc": "No data found for given criteria"
}
]
}
}
失敗応答のサンプル
{
"result": false,
"errorCode": "GU_1129",
"errorDesc": "Invalid GSID value.",
"localizedErrorDesc": "Invalid GSID value.",
"requestId": "a0f958fb-fee7-4a15-8029-e334350ce1b7",
"data": null,
"message": null,
"localizedMessage": null}
Company Teamsレコードをアップサート
Upsert APIには二重の目的があります。これにより、新しい会社のチームレコードを挿入し、Gainsightの既存のチームレコードを更新することができます。
メソッド
入力
エンドポイントURL
v1/teams/services/companyTeam?key=CompanyGsid,UserGsid
または
v1/teams/services/companyTeam?key=Gsid
重要:
- キーオプション:
- キーパラメータには、GSID (key=GSID) またはCompanyGsidとUserGsidの組み合わせ (key=CompanyGsid, UserGsid) のいずれかがあります。
- 必須フィールド:
- GSIDが識別子 (key=GSID) として指定されている場合は、リクエスト本文にGSIDフィールドを含めることが必須となります。
- CompanyGsidとUserGsidが識別子 (key=CompanyGsid, UserGsid) として指定されている場合は、リクエスト本文にCompanyGsidとUserGsidを含めることが必須となります。
- デフォルトの識別子:
- エンドポイントURLにキーパラメータが指定されていない場合は、デフォルトの識別子としてCompanyGsidとUserGsidが使用されます。したがって、エンドポイントURLにキーが渡されていない場合は、リクエスト本文にCompanyGsidフィールドとUserGsidフィールドを指定することが必須となります。
リクエスト本文の例
以下は、CompanyNameとusernameが含まれるリクエスト本文の例です。
{
"records": [
{
"UserRole" : "Account Manager",
"CompanyName": "IBM",
"UserName": "Sandeep Kumar",
"TeamAdmin" : "true",
"Custom_String1__gc" : "hello",
"Custom_Picklist__gc" : "Account Manager",
},
{
"UserRole" : "Account Manager",
"CompanyName": "Youtube",
"UserName": "Sandeep Kumar",
"TeamAdmin" : "true",
"Custom_String__gc" : "hello",
"Custom_Picklist__gc" : "Account Manager"
}
],
"lookups": {
"CompanyGsid": {
"fields": {
"CompanyName": "Name"
},
"lookupField": "Gsid",
"objectName": "Company",
"multiMatchOption": "FIRSTMATCH"
},
"UserGsid": {
"fields": {
"UserName": "Name"
},
"lookupField": "Gsid",
"objectName": "GsUser"
}
}
}
以下は、CompanyGsidとUserGsidが含まれるリクエスト本文の例です。
{
"records": [
{
"UserRole" : "Account Manager",
"CompanyName": "IBM",
"UserName": "Sandeep Kumar",
"TeamAdmin" : "true",
"Custom_String1__gc" : "hello",
"Custom_Picklist__gc" : "Account Manager",
},
{
"UserRole" : "Account Manager",
"CompanyName": "Youtube",
"UserName": "Sandeep Kumar",
"TeamAdmin" : "true",
"Custom_String__gc" : "hello",
"Custom_Picklist__gc" : "Account Manager"
}
],
"lookups": {
"CompanyGsid": {
"fields": {
"CompanyGsid": "Gsid"
},
"lookupField": "Gsid",
"objectName": "Company",
"multiMatchOption": "FIRSTMATCH"
},
"UserGsid": {
"fields": {
"UserGsid": "Gsid"
},
"lookupField": "Gsid",
"objectName": "GsUser"
}
}
}
パラメータ
以下はkey = CompanyGsid, UserGsidの場合のパラメータのリストです。
|
パラメータ (*必須) |
データタイプ |
説明 |
|---|---|---|
|
CompanyGsid* またはCompanyName * |
文字列 |
|
|
UserGsid* またはUserName* |
文字列 |
|
|
UserRole |
文字列 |
会社チームレコードにユーザーの役割を含む文字列値。 |
|
TeamAdmin |
ブーリアン |
ユーザーが会社チームの管理者であるかどうかを示すブーリアン値。 |
|
ObjectName |
文字列
|
ルックアップオブジェクト名を含む文字列値。 |
|
multiMatchOption
|
文字列 |
|
|
onNoMatch
|
文字列 |
|
以下は、key = Gsidの場合のパラメータのリストです。
|
パラメータ (*必須) |
データタイプ |
説明 |
|---|---|---|
|
Gsid* |
文字列 |
会社チームレコードのGSIDを含む文字列値。 |
|
UserRole |
文字列 |
会社チームレコードにユーザーの役割を含む文字列値。 |
|
TeamAdmin |
ブーリアン |
ユーザーが会社チームの管理者であるかどうかを示すブーリアン値。 |
成功応答の例
{
"result": true,
"errorCode": null,
"errorDesc": null,
"localizedErrorDesc": null,
"requestId": "6672f3fd-f049-4434-8a4b-46a1b7b09308",
"data": {
"success": {
"records": [
{
"UserGsid": "1P01A7JNOWRLONI81IADNSU9OSAE8VW22OGV",
"Custom_Picklist__gc": "Account Manager",
"CompanyGsid": "1P02EWJH7V1ARTU135948UTCK78QC96QL78G",
"CreatedBy": "123",
"UserRole": "Account Manager",
"TeamAdmin": "true",
"Custom_String1__gc": "hello",
"ModifiedBy": "Sandeep Kumar"
},
{
{
"UserRole" : "Account Manager",
"CompanyGsid": "1P02EWJH7V1ARTU135948UTCK78QC96ABCWE",
"UserGsid": "1P01A7JNOWRLONI81IADNSU9OSAE8VW22OGV",
"TeamAdmin" : "true",
"Custom_String__gc" : "hello",
"Custom_Picklist__gc" : "Account Manager"
}
]
},
"errors": null
},
"message": null,
"localizedMessage": null
}
失敗応答のサンプル
{
"result": false,
"errorCode": "GU_2403",
"errorDesc": "Lookup objects [Company1] are not valid",
"requestId": "0bf61426-63ad-4774-ad95-4bd2f6c43c25",
"data": null,
"message": null
}
Company Teamsレコードを取得
Fetch APIにより、Gainsightに保存されている会社チームの特定の詳細を取得することができます。
メソッド
ポスト
エンドポイントURL
v1/teams/services/companyTeam/list
リクエスト本文の例
{
"limit": 25,
"page": 0,
"orderBy": {
"ModifiedDate": "desc"
},
"select": [
"Gsid",
"CompanyName",
"UserName",
"UserRole",
"ModifiedDate"
],
"where": {
"conditions": [
{
"name": "CompanyName",
"alias": "companyNotIn",
"value": [
"Youtube"
],
"operator": "NOT_IN"
},
{
"alias": "companyIn",
"name": "CompanyName",
"operator": "IN",
"value": [
"IBM"
]
}
],
"expression": "companyNotIn AND (companyIn)"
}}
パラメーター
|
パラメーター (*必須) |
データタイプ |
説明 |
|---|---|---|
|
limit |
数 |
1回のAPIコールで送信されるレコードの最大数を含む数値。 |
|
page |
数 |
制限に基づいた次のレコードセットを含む数値。 |
|
orderBy |
マップ |
昇順または降順のフィールド名順序を含むマップ値。 |
|
select*
|
フィールド一覧 |
オブジェクトからフィールドを取得するためのリスト。 |
|
where |
マップ |
レコードをフィルタリングし、指定した条件を満たすレコードのみを抽出するために使用されるマップ値。 |
|
Conditions |
リスト |
会社チームレコードを除去するために使用される条件のリスト。 |
|
expression |
文字列 |
AND/OR演算を含む文字列値。 |
応答成功のサンプル
{
"result": true,
"errorCode": null,
"errorDesc": null,
"localizedErrorDesc": null,
"requestId": "b518fb98-336d-404f-83ab-40fb01730867",
"data": {
"page": 0,
"size": 1,
"limit": 25,
"records": [
{
"Gsid": "1P071TST1Z6DTGBG44KDYJG9KBNTDQMQ3QHO",
"UserRole": "Pre-Sales Consultant",
"ModifiedDate": "2023-10-03T10:03:32Z",
"Name": "Admin User",
"CompanyName": "IBM"
}
]
},
"message": null,
"localizedMessage": null}
失敗応答のサンプル
{
"result": false,
"errorCode": "GU_1707",
"errorDesc": "Failed to fetch records.",
"localizedErrorDesc": "Failed to fetch records.",
"requestId": "667951ba-b04f-4407-b326-1347645efdc6",
"data": null,
"message": null,
"localizedMessage": null
}
エラーコード
|
エラーコード |
エラーメッセージ |
理由 |
HTTPステータス コード |
|---|---|---|---|
|
GU_8002 |
少なくとも1つのGSIDを指定する必要があります |
GSIDが一括削除で渡されない場合。 |
400 |
|
GU_8003 |
指定された条件のデータが見つかりません |
一括削除で指定されたGSIDがすでに削除されているか、または会社レコードに存在しないかのいずれかの場合。
|
400 |
|
GU_8004 |
リクエストは、レコードをアップサートする最大制限数: 50レコードを超えています |
一括削除で指定されたリクエストに50レコードを超えて含まれている場合。 |
416 |
|
GU_8005 |
会社チームは現在有効になっていません |
削除または一括削除で会社チーム機能の切り替えが有効になっていない場合。 |
400 |
|
GU_2400 |
リクエストが多すぎて、リクエスト制限に達しました |
削除または一括削除でレート制限を超過した場合。 |
429 |
|
GU_1129 |
GSID値が無効です |
削除または一括削除でGSIDが無効な場合。 |
400 |
|
GU_3014 |
CompanyGsid/CompanyNameまたはUserGsid/usernameがリクエスト本文に渡される場合、ルックアップはNULLまたは空白にできません |
CompanyGsid/CompanyName/UserGsid/usernameフィールドがリクエスト本文に含まれていて、必要なルックアップ情報が渡されていない場合。 |
400 |
|
GU_3017
|
GSIDが無効です
|
GSIDが有効でない場合。 |
NA |
|
GU_3018
|
識別子 {} はNULLまたは空白にできません
|
識別子が有効でない場合。 |
NA |
|
GU_3019
|
渡されたキー: {} は許可されていません。許可されているキーは、GSIDまたはCompanyGsid、UserGsidです。
|
識別子が認識できない場合。 |
400 |
|
GU_3006
|
{} はNULLまたは空白にできません。
|
リクエストペイロードが空白の場合。 |
400 |
|
GU_3016
|
会社チームのアップサート操作に失敗しました
|
会社チームのアップサートリクエストが失敗した場合。 |
NA |
|
GU_3014
|
CompanyGsid/CompanyNameまたはUserGsid/UserNameがリクエスト本文に渡される場合、ルックアップはNULLまたは空白にできません
|
リクエストルックアップが空白の場合。 |
NA |
|
GU_8006
|
リクエストは、レコードをアップサートする最大制限数: {} レコードを超えています
|
会社チームのアップサートレコード制限を超えた場合。 |
416 |