メソッド

ポスト

エンドポイント URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}

エンドポイント URL では:

• customobjectapi.gainsightcloud.comは、Gainsightに接続するためのドメインです。あくまで参考です。
• オブジェクト名はGainsightのカスタムオブジェクト名です。実際のエンドポイントURL は、...gainsightcloud.com/v1/data/objects/thisObject__gcの様になります。

上記で使われているオブジェクト名は参考用です。要件とユースケースに対応した名前でオブジェクトを作成することができます。データ管理ページから、エンドポイントURLを介して渡される正しいオブジェクト名を確認することができます。

リクエスト本文のサンプル

オブジェクトに挿入を希望するレコードをリクエスト本文で渡します。オブジェクト内のフィールドとそれに関連付けられた値は、以下に示す様にキーと値のペアとして渡されます。挿入する必要がある各レコードを配列項目として渡します。API呼び出しを通して、最大50レコードを挿入することができます。

サポートされている形式のいずれかで、APIに日付値と日時値を渡すことができます。サポートされている形式の詳細については、Gainsightデータ管理 記事を参照してください。

{
  "records": [
    {
      "CSMLastName": "Johnson",
      "CSMFirstName": "Paul",
      "Name": "Gainsight, Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 23,
      "Employees": 12
    },
    {
      "CSMLastName": "Sharma",
      "CSMFirstName": "Rohan",
      "Name": "Verizon",
      "Stage": "New Customer",
      "LifecycleInWeeks": 13,
      "Employees": 22
    },
    {
      "CSMLastName": "Mendis",
      "CSMFirstName": "Jeevan",
      "Name": "ABC Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 31,
      "Employees": 889
    },
    {
      "CSMLastName": "Srivastava",
      "CSMFirstName": "Avneesh",
      "LifecycleInWeeks": 9,
      "Employees": 290,
      "Name": "ACME Corp."
    },
    {
      "CSMLastName": "Singh",
      "CSMFirstName": "Sandeep",
      "LifecycleInWeeks": 19,
      "Employees": 89,
      "Name": "XYZ Inc."
    }
  ],
"lookups": {
        "CSM__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }
}

パラメーター

"lookups": {
        "CSM__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }

応答成功のサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。レスポンスのフォーマットは以下の通りです。成功応答には、正常に挿入された全てのレコードの一覧が含まれています。

• 各レコードの応答には、レコード用に作成された一意のGSIDと、挿入されたレコード内のフィールドの実際の値が含まれます。
• 以下の応答は各レコードのCSMフィールドに、GSユーザーオブジェクトからのGSIDが正常に入力されたことも示しています。この値はJSONリクエスト本文のインポートルックアップ構成によって設定されます。
• 日付と日時の値はエポック形式で表示されます。
• ステージやステータスなどのドロップダウンリストアイテムには、アイテムの一意のGSIDが入力されます。

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
  "data": {
    "records": [
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "Gainsight, Inc.",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1562691459623,
        "Gsid": "1P02MRXML1GRDV44YOYPEBMABN5JYVTAATP8",
        "LifecycleInWeeks": 23,
        "Employees": 12
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "Verizon",
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO6NO2DQXRNTQYQXDLGF",
        "LifecycleInWeeks": 13,
        "Employees": 22
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "ABC Inc.",
        "Status": "8K2274U9FAKXZ0H26HO92M3F1G5SPWVQXYS8",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YOL2PI8HX2NJRH5NQTEE",
        "LifecycleInWeeks": 31,
        "Employees": 889
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "CreatedDate": 1521691459693,
        "Name": "ACME Corp.",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "LifecycleInWeeks": 9,
        "Employees": 290
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "CreatedDate": 1521691459693,
        "Name": "XYZ Inc.",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO87PCQFV0QIRSDZZ3DN",
        "LifecycleInWeeks": 19,
        "Employees": 89
      }
    ]
  },
  "message": null
}

失敗応答のサンプル

APIリクエストがエラーになった場合、次の形式でエラーレスポンスが返されます。エラー応答には、Gainsightエラーコードとエラーの説明が含まれています。GainsightのエラーコードとHTTPステータスコードの応答は、様々な理由で発生する可能性があります。Gainsightエラーコード、エラーの説明、その理由、及びHTTPステータスコードの詳細については、会社及びカスタムオブジェクトAPIのエラーコード記事を参照してください。

API呼び出しを行うと、最初の検証に失敗したフィールドで構文解析が停止します。従って、最初に失敗したフィールドのエラー検証を含むエラー応答を受け取ります。応答のデータキーには、失敗の理由に関する追加の詳細が含まれています。全てのフィールドで検証が成功すると、レコードがオブジェクトに挿入されます。

以下は、フィールドDateTime__gcに値を挿入する際に、データ検証エラーが発生したためにAPI呼び出しが失敗した場合の応答の例です。

{
  "result": false,
  "errorCode": "GSOBJ_1005",
  "errorDesc": "Invalid dateTime format (DateTime__gc = XYZ Inc.).",
  "requestId": "39f58495-8f05-4344-8542-ca44ac9afeb8",
  "data": {
    "count": 0,
    "errors": [
      [
        {
          "success": false,
          "parsedValue": "XYZ Inc.",
          "errors": [
            {
              "errorMessage": "Invalid dateTime format",
              "errorCode": "GSOBJ_1005",
              "fieldName": "DateTime__gc",
              "invalidValue": "XYZ Inc."
            }
          ]
        }
      ]
    ],
    "records": null
  },
  "message": null
}

メソッド

入力

エンドポイント URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}?keys={fieldName1,fieldName2} 

上記のエンドポイントURLでは、customobjectapi.gainsightcloud.comはGainsightへの接続に使用するドメインです。あくまで参考です。

オブジェクト名がこのオブジェクトで、キーがEmployeesとIndustryの場合、カスタムオブジェクトのレコードを更新するための有効なエンドポイントURLは次のようになります： ...gainsightcloud.com/v1/data/objects/thisObject__gc?keys=Employees,Industry.

上記で使われているオブジェクト名とキー (フィールド名) は参考用です。要件とユースケースに対応した名前でオブジェクトを作成することができます。

条件:

• エンドポイントURLでは、文字列、GSID、数、及びメールのみのデータタイプのキーを指定することができます。
• 特定のレコードを識別するために、エンドポイントURLに最大3つのキーを入力することができます。
• キー間の演算子は常にANDです。つまり、全てのキーの条件に一致するレコードがUpdate APIを使って更新されます。

リクエスト本文のサンプル

オブジェクトで更新を希望するレコードをリクエスト本文で渡します。オブジェクト内のフィールドとそれに関連付けられた値は、以下に示す様にキーと値のペアとして渡されます。キーの値 (エンドポイントURLに記載) は、特定のレコードを識別するための参照として取得され、残りのフィールドはJSONで指定された通りに更新されます。更新するする必要がある各レコードを配列項目として渡します。API呼び出しを通して、最大50レコードを更新するすることができます。オブジェクト内の全てのデータ型のフィールドは、メソッドを通じて更新することができます。

エンドポイントURLでキーとして使われるフィールドの値は更新することができません。これらのフィールドを更新するためには、異なるフィールドをキーとして別の更新API呼び出しを渡すことが可能です。

サポートされている形式のいずれかで、APIに日付値と日時値を渡すことができます。  サポートされている形式の詳細については、Gainsightデータ管理記事を参照してください。

以下は更新API呼び出しのサンプルです。更新が必要な特定のレコードを識別するためのキーとしてNameと Employeesがあり、残りのフィールドの値は各レコードのJSONに従って更新されます。GSIDタイプフィールドの値を更新するやり方の詳細については、ルックアップのインポートセクションを参照してください。

{
  "records": [
    {
      "CSMLastName": "Lee",
      "CSMFirstName": "Shaun",
      "Name": "Gainsight, Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 23,
      "Employees": 12
    },
    {
      "CSMLastName": "Nyumbu",
      "CSMFirstName": "John",
      "Name": "Verizon",
      "Stage": "Launched",
      "LifecycleInWeeks": 13,
      "Employees": 22
    },
    {
      "CSMLastName": "Farbrace",
      "CSMFirstName": "Paul",
      "Name": "ABC Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 31,
      "Employees": 889
    },
    {
      "CSMLastName": "Wasikowska",
      "CSMFirstName": "Mitchelle",
      "LifecycleInWeeks": 9,
      "Employees": 290,
      "Name": "ACME Corp."
    },
    {
      "CSMLastName": "Sharma",
      "CSMFirstName": "Deepak",
      "LifecycleInWeeks": 19,
      "Employees": 290,
      "Name": "XYZ Inc."
    }
  ],
  "lookups": {
        "CSM__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }
}

パラメーター

応答成功のサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返さます。成功した応答には、正常に更新された全てのレコードの一覧が含まれています。これには、一意のGSIDと更新されたレコード内のフィールドの実際の値が含まれます。

成功応答の例を以下に示します：

• 各レコードの応答には、レコードの一意のGSIDと、更新されたレコードのフィールドの実際の値が含まれます。
• 以下の応答はCSM及び親会社フィールドに、それぞれGSユーザーオブジェクト及び会社オブジェクトからのGSIDが取り込まれていることも示しています。これらの値はJSONリクエスト本文のインポートルックアップ構成によって設定されます。
• 日付と日時の値はエポック形式で表示されます。
• ステージやステータス値などのドロップダウンリストアイテムには、アイテムの一意のGSIDが入力バリューされます。

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
  "data": {
    "count": 2,
    "errors": null,
    "records": [
      {
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "Trend": null,
        "Employees": 12,
        "LifecycleInWeeks": 23,
        "OriginalContractDate": 1521743018667,
        "Users": null,
        "gsd36499": null,
        "Shri_Shri_Id__gc": null,
        "ModifiedDate": 1521743018667,
        "ScorecardId": null,
        "Name": "Gainsight, Inc.",
        "Industry": null,
        "RenewalDate": 1521743018667,
        "CurrentScore": null,
        "PreviousScore": null,
        "Parent_Company__gc": null,
        "CreatedDate": 1521691459694,
        "Stage": null,
        "CustomerLifetimeInMonths": 5,
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW"
      },
      {
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Gsid": "1P02MRXML1GRDV44YODC75YNFKEJ4M1CHDR8",
        "Trend": null,
        "Employees": 22,
        "LifecycleInWeeks": 13,
        "OriginalContractDate": 1521743018667,
        "Users": null,
        "gsd36499": null,
        "Shri_Shri_Id__gc": null,
        "ModifiedDate": 1521743018667,
        "ScorecardId": null,
        "Name": "Verizon",
        "Industry": null,
        "RenewalDate": 1521743018667,
        "CurrentScore": null,
        "PreviousScore": null,
        "Parent_Company__gc": null,
        "CreatedDate": 1521691459694,
        "Stage": "1P02MRXML1GRDV44YODC75YNFKEJ4M1CHDR8",
        "CustomerLifetimeInMonths": 2,
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW"
      }
    ]
  },
  "message": null
}

失敗応答のサンプル

APIリクエストがエラーになった場合、次の形式でエラーレスポンスが返されます。エラー応答には、Gainsightエラーコードとエラーの説明が含まれています。GainsightのエラーコードとHTTPステータスコードの応答は、様々な理由で発生する可能性があります。Gainsightエラーコード、エラーの説明、その理由、及びHTTPステータスコードの詳細については、会社及びカスタムオブジェクトAPIのエラーコード記事を参照してください。

API呼び出しを行うと、最初の検証に失敗したフィールドで構文解析が停止します。従って最初に失敗したフィールドのエラー検証を含むエラー応答を受け取ります。応答データキーには、失敗の理由に関する追加の詳細が含まれています。全てのフィールドで検証が成功すると、次にレコードがオブジェクトに挿入されます。

次に示すのは、オリジナルの契約日フィールドの値の日時形式が無効なためにAPIが失敗した場合の応答の例です。

{
  "result": false,
  "errorCode": "GSOBJ_1006",
  "errorDesc": "Invalid dateTime format (OriginalContractDate = 7809).",
  "requestId": "7cba3c98-b04b-4e21-9e57-44807fa52b8a",
  "data": {
    "count": 0,
    "errors": [
      [
        {
          "success": false,
          "parsedValue": 7809,
          "errors": [
            {
              "errorMessage": "Invalid dateTime format",
              "errorCode": "GSOBJ_1006",
              "fieldName": "OriginalContractDate",
              "invalidValue": 7809
            }
          ]
        }
      ]
    ],
    "records": null
  },
  "message": null
}

メソッド

ポスト

エンドポイント URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/query/{objectName}

エンドポイント URL では:

• customobjectapi.gainsightcloud.comは、Gainsightに接続するためのドメインです。あくまで参考です。
• オブジェクト名はGainsightのカスタムオブジェクト名です。カスタム オブジェクトを含む実際のエンドポイントURL はgainsightcloud.com/v1/data/objects/thisObject__gcの様になります。

注意：上記で使われているオブジェクト名は参考用です。要件とユースケースに対応した名前でオブジェクトを作成することができます。

リクエスト本文のサンプル

{
  "select": [
    "Company_Name__gc",
    "Company_ID__gr.csm__gr.name"
  ],
  "where": {
    "conditions": [
      {
        "name": "Company_Name__gc",
        "alias": "A",
        "value": [
          "Gainsight"
        ],
        "operator": "EQ"
      },
      {
        "name": "Company_ID__gr.csm__gr.name",
        "alias": "B",
        "value": [
          "John"
        ],
        "operator": "CONTAINS"
      }
    ],
    "expression": "A AND B"
  },
  "orderBy": {
    "Company_Name__gc": "asc",
    "Company_ID__gr.csm__gr.name": "desc"
  },
  "limit": 100,
  "offset": 0
}

読み取りAPIでルックアップフィールドを使って、別のオブジェクト (ベースオブジェクトではない) から値を取得することができます。上記のサンプルAPIでは、ルックアップフィールド Company_ID__gr.csm__gr.nameが使われます。このフィールドには、ベースオブジェクト (例: thisObject) > 会社オブジェクト > ユーザーオブジェクト (会社のcsmフィールド経由) > 名前 (ユーザーオブジェクトのフィールド) からのルックアップがあります。指定されたフィールドで、ルックアップを使ってユーザーオブジェクトから名前が取得されます。

注意：読み取りAPIを使ってグループ条項でレコードをフィルター処理することはできません。

異なる演算子を使用した別のサンプル読み取りAPI:

{
  "select": [
    "Renewal_Date__gc",
    "Company_ID__gr.stage"
  ],
  "where": {
    "conditions": [
      {
        "name": "Renewal_Date__gc",
        "alias": "A",
        "value": [
          "2018-04-01",
          "2018-04-23"
        ],
        "operator": "BTW"
      },
      {
        "name": "Company_ID__gr.stage",
        "alias": "B",
        "value": [
          "New Customer",
          "Kicked Off",
          "Launched"
        ],
        "operator": "IN"
      }
    ],
    "expression": "A OR B"
  },
  "orderBy": {
    "Renewal_Date__gc": "asc",
    "Company_ID__gr.stage": "desc"
  },
  "limit": 100,
  "offset": 0
}

上記のサンプルAPIでは、使われるwhere条件は次の通りです。

• フィールド：更新日/値2018-04-01, 2018-04-23 / オペレーター。BTW.この条件では、指定された2つの値の間に更新日があるレコードが取得されます。演算子BTWを使う場合は、条件に一致するレコードを取得するために2つの値を指定します。
• フィールド：Company_ID__gr.stage / 値：新規顧客、キックオフ、ローンチ済み / オペレーター：インこの条件では、提供されるフィールドには、ベースオブジェクトから会社オブジェクト > ステージフィールドへのルックアップがあります。会社のステージが新規顧客、キックオフ、又はローンチ済みになっているレコードが取得されます。演算子INを使う場合は、基準に一致する1つ又は複数の値を指定することができます。

サポートされている形式のいずれかで、APIに日付値と日時値を渡すことができます。サポートされている形式の詳細については、Gainsightデータ管理記事を参照してください。

パラメーター

データタイプの各フィールドでサポートされている演算子は次の通りです。

 次の表は読み取りAPIでサポートされている各演算子の列挙型演算子を示しています。

応答成功のサンプル

APIリクエストが成功すると、レスポンスとしてHTTPステータスコード200が返されます。成功レスポンスのフォーマットは以下の通りです。APIリクエスト本文の「選択」セクションに記載されているフィールドは、クエリ条件に一致する全てのレコードに対して返されます。

以下は最初のサンプル読み取りAPIのサンプル成功応答です。

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": [
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "John Nyumbu"
    },
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "John Smith"
    },
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "Paul Johnson"
    }
  ],
  "message": null
}

注: 成功応答で：

• 日付と日時の値はエポック形式で表示されます。
• ステージやステータス値などのドロップダウンリストアイテムには、アイテムの一意のGSIDが入力されます。

失敗応答のサンプル

APIリクエストがエラーになった場合、次の形式でエラーレスポンスが返されます。エラー応答には、Gainsightエラーコードとエラーの説明が含まれています。GainsightのエラーコードとHTTPステータスコードの応答は、様々な理由で発生する可能性があります。Gainsightエラーコード、エラーの説明、その理由、及びHTTPステータスコードの完全なリストについては、会社及びカスタムオブジェクトAPIのエラーコード記事を参照してください。

次のエラーレスポンス本文では、エラーの説明に読み取りAPIの失敗の理由が示されています。

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "b277a27b-316f-45e8-8bd1-37bbb2eb17ef",
    "data": {
        "records": []
    },
    "message": null
}

削除API

削除APIはカスタムオブジェクトの特定のレコードを削除します。削除するレコードは、エンドポイントURLで渡されるGSIDで識別されます。

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}/{GSID}

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "6e2308e4-5e44-419b-af2a-21cd9153258c",
    "data": "Delete process initiated for 1 records.",
    "message": null
}

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "15402521-8d94-47ec-8126-ee56c45b7db0",
    "data": "Delete process initiated for 1 records.",
    "message": null
}

エラーコード

GainsightカスタムオブジェクトAPIに関連するエラーコードの一覧については、会社及びカスタムオブジェクトAPIのエラーコード記事を参照してください。