メインコンテンツまでスキップ
Gainsight Japanese Localization

タイトル: 会社チームレコードの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 *

文字列

  • 会社レコードのGSIDを含む文字列値。
  • 会社の名前を含む文字列値。

UserGsid* またはUserName*

文字列

  • ユーザーのGSIDを含む文字列値。
  • ユーザーの名前を含む文字列値。

UserRole

文字列

会社チームレコードにユーザーの役割を含む文字列値。
注意: 新しいレコードを挿入する際、リクエスト本文にUserRoleフィールドが指定されていない場合、デフォルト値はアカウントマネージャーに設定されます。

TeamAdmin

ブーリアン

ユーザーが会社チームの管理者であるかどうかを示すブーリアン値。
注意: 新しいレコードを挿入する際、リクエスト本文にTeamAdminフィールドが指定されていない場合、デフォルト値はに設定されます。

ObjectName

文字列

 

ルックアップオブジェクト名を含む文字列値。

multiMatchOption

  • FIRSTMATCH
  • MARKASERROR

 

文字列

  • ルックアップJSONとルックアップオブジェクト間の最初の一致のGSIDを含む文字列値。
  • 複数のレコードがJSONとルックアップオブジェクト間の条件に一致する場合に、エラーを含む文字列値。

onNoMatch

  • NULLABLE
  • DEFAULTVALUE
  • エラー

 

文字列

  • (デフォルト) 一致するフィールドが見つからない場合に、ターゲットフィールドにNULL値を挿入する文字列値。
  • ターゲットフィールドにデフォルト値を挿入する文字列値。
  • JSONとルックアップオブジェクト間の条件に一致するレコードがない場合に、エラーを含む文字列値。

以下は、key = Gsidの場合のパラメータのリストです。

パラメータ

(*必須)

 

データタイプ

説明

Gsid*

文字列

会社チームレコードのGSIDを含む文字列値。

UserRole

文字列

会社チームレコードにユーザーの役割を含む文字列値。
注意: 新しいレコードを挿入する際、リクエスト本文にUserRoleフィールドが指定されていない場合、デフォルト値はアカウントマネージャーに設定されます。

TeamAdmin

ブーリアン

ユーザーが会社チームの管理者であるかどうかを示すブーリアン値。
注意: 新しいレコードを挿入する際、リクエスト本文に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

  • この記事は役に立ちましたか?