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

Gainsightバルク API

重要 - 画像/情報は四半期ごとのリリースで更新されます!

四半期ごとのリリースにて、最新の機能・情報を反映し、画像を含めた情報は更新されます。

 

この記事では、Gainsightの管理者がGainsight バルク APIで接続を作成し、データジョブを設定してcURLコマンドを生成するプロセスを説明します。このコマンドは、データジョブで設定されているように、ソース CSV ファイルからターゲット Gainsightオブジェクトにデータをロードするために使用されます。

メモ: Gainsight バルク API を使用してデータを Gainsight ユーザーおよび個人オブジェクトモデルに読み込むことはできません。

この記事を順を追って説明すると、管理者は次のことを行うことができます。

  • バルク API 接続を作成します。
  • ジョブを作成します。
  • CSV ファイルから Gainsight オブジェクトにデータを取り込みます。

[概要]

GainsightバルクAPIは、cURLコマンドを使用してGainsightにデータをロードするチャンネルです。お客様は、外部システムからローカルコンピューターにCSVファイルをダウンロードして、外部システムからGainsightにデータをロードしたい場合があります。Gainsightの管理者は、Gainsight バルク APIで必要な構成を設定し、出力されたcURLコマンドを開発者と共有できます。開発者はコマンドを任意のアプリケーションに統合できます。設定したとおりに、データは cURL コマンドが統合されたアプリケーション内のアクションとともに、ローカルマシンから Gainsight に直接読み込まれます。

GainsightバルクAPIを使用するメリットは次のとおりです。

  • 雇用の創出と維持は簡単です。
  • 標準オブジェクトへのデータのインポートが可能です。
  • フィールドマッピングは UI で使用できます。
  • 複数のフィールドマッピングを使用してデータインポートルックアップを設定できます。
  • 更新/更新操作用の更新キー機能。
  • データインポートの成功と失敗の通知メール。
  • 実行および更新アクティビティを詳細に追跡します。

バルク API 接続の作成

重要: このシステムでは、ユーザは組織ごとに 1 つの接続を作成できます。1 つの接続で、管理者は複数のタスクを作成してデータをオブジェクトに抽出できます。

接続を作成するには:

  1. [管理] > [コネクタ 2.0] > [接続] に移動します。
  2. 接続を作成」をクリックします。[接続の作成] ダイアログが表示されます。
  3. コネクタのドロップダウンリストからGS バルク API を選択します。
  4. 接続名: 接続の名前を入力します。
  5. アクセスキーを生成」をクリックします。新しいアクセスキーが生成されます。アクセスキーをいつでもリセットしたい場合は、[アクセスキーを生成] をクリックします。
  6. アクセスキーをコピーして保存し、cURL API セクションで使用します。

    メモ: 管理者はこのアクセスキーを保存して、開発者やそれぞれのチームメイトと共有できます。チームメンバーは cURL コマンドを使用してアプリケーションと統合できます。
     
  7. 保存」をクリックします。

重要: システムでは、ユーザーは組織ごとに 1 つの接続を作成できます。 1 つの接続の下で、管理者は複数のジョブを作成してデータをオブジェクトに取り込むことができます。

バルク API ジョブの実行に対する制限は次のとおりです:

  • 接続の 1 時間あたりのバルク API 制限: 10
  • 接続の 1 日あたりのバルク API 制限: 100

ジョブの作成

接続を確立したら、必要な数だけジョブを作成できます。ジョブを作成するには:

  1. ジョブ」ページに移動します。
  2. ジョブの作成」をクリックします。「ジョブの作成」ダイアログが表示されます。
  3. ジョブの名前」テキストボックスに、ジョブ名を入力します
  4. [次へ] をクリックします。「ジョブの準備」ページが表示されます。
  5. データソース」ドロップダウンリストから、必要な GS バルク API 接続を選択します。

準備ページには以下のセクションが読み込まれます。

  • ジョブの詳細
  • フィールドマッピング
  • cURL API

ジョブの詳細

「ジョブの詳細」セクションには、次の情報が表示されます。

  1. 接続: 接続の名前が表示されます。
  2. コネクタ: コネクタ名が表示されます。
  3. ジョブ名: 一意のジョブ名を入力します。
  4. 通知の受信者: 通知受信者に、次の情報を入力します。
    • 成功者: ジョブのデータインポートの一部または全部が成功すると、ここに入力したメールアドレスに成功通知メールが送信されます。
    • 失敗した受信者: すべてのレコードのインポートに失敗すると、ここに入力したメールアドレスに失敗通知メールが送信されます。

      メモ: 複数のメールをカンマで区切って受信者リストに追加できます。
  5. 保存」をクリックします。

    メモ: システムは、同じ名前のすべてのジョブを検証します。重複するジョブ名が見つかると、「ジョブ名は既に存在します」というエラーが表示されます。常に一意のジョブ名を割り当ててください。

CSV ファイルから Gainsight オブジェクトにデータを取り込む

タスク作成プロセスを完了するには、CSV 列と Gainsight オブジェクトフィールドをマッピングする必要があります。この例では、レコードは CSV ファイル CompanyDetails.csv から企業オブジェクトに抽出されます。

例として、名前、業種、従業員、当初の契約日、更新日、ARRCSMFirstNameCSMLastNameというヘッダーが付いたCSVファイル内のレコードを以下に示します。

メモ: このドキュメントで使用されている名前、レコード、およびアクセスキーは参照用です。

Image 1.jpg

メモ:

  • CSV ファイル名にスペースが含まれていないことを確認します。
  • CSM のファーストネームとラストネームは、派生マッピングで使用できるようにここに追加されています。

CSVファイルの日付と日時の値の形式がGainsightでサポートされていることを確認してください。Gainsightでサポートされているフォーマットのリストについては、この記事の最後にある「追加リソース」セクションにある「データ管理の基本操作」を参照してください。

管理者は複数のジョブを作成してデータをオブジェクトに取り込むことができます。

フィールドマッピング

[フィールドマッピング] をクリックしてセクションを展開し、次の詳細を入力します。

  1. ターゲットオブジェクト: 「ターゲットオブジェクト」ドロップダウンリストから、データを抽出するターゲットオブジェクトを選択します。たとえば、「会社オブジェクト」を選択します。特定の Target Object でジョブを保存すると、データを取り込む前にジョブを変更することはできません。
  2. BROWSE をクリックして、ローカルマシンから CSV ファイルを選択します。このセクションのCSVファイルは、CSVヘッダーとGainsightオブジェクトフィールド間のマッピングを選択するためにアップロードされます。

    メモ:
    • CSV ファイルにヘッダーがあることを確認します。
    • 最大サイズが 1MB の CSV ファイルをロードできます。
  3. データロード操作: 必要なデータロード操作を選択します。それぞれの操作で、[アップサート]、[更新]、または [挿入] を選択します。
  4. Upsert Update では、+ アイコンをクリックして識別子として使用できるキーフィールドを設定します。
  5. CSV プロパティ: 適切な CSV プロパティを選択します。推奨される CSV プロパティ:
    1. 文字エンコーディング: UTF-8
    2. セパレーター: , (カンマ)
    3. 引用文字: 「(二重引用符)
    4. エスケープ・チャー: バックスラッシュ
    5. ヘッダー行: 1 (必須)
    6. 複数選択セパレータ: ; (セミコロン)

       :
      • Gainsight バルク API は常に UTF-8 でエンコードされたファイルのみをサポートします。
      • セパレータは、CSV 内のさまざまなフィールドの値を区切るために使用されます。ユーザーは、アップロードする CSV ファイルで使用されているジョブ設定と同じ区切り文字を使用する必要があります。デフォルトでは、(カンマ) が区切り文字として選択されていますが、ユーザーは必要に応じて変更できます。
      • 引用文字は、データをインポートする際に、見積書で指定された値を (特殊文字と一緒に) インポートするために使用されます。アップロードする CSV ファイルで使用されているジョブ設定と同じ引用符文字を使用することを推奨します。デフォルトでは、タスク設定では二重引用符が選択されていますが、ユーザーは必要に応じて一重引用符に変更できます。
      • エスケープ文字は、値に特殊文字を含めるために使用されます。デフォルトでは、バックスラッシュは値の特殊文字の前のエスケープ文字として使用されます。ロード後のデータに不一致が生じないように、CSV ファイルではバックスラッシュを使用することをお勧めします
      • 複数選択セパレータは、データタイプの複数選択ドロップダウンリストのフィールドの複数の値を区切るために使用されます。ユーザーは、アップロードする CSV ファイルで使用されているのと同じ複数選択区切り文字を使用する必要があります。デフォルトでは、; (セミコロン) が区切り文字として選択されていますが、ユーザーは必要に応じて変更できます。
  6. マッピングを取得」をクリックします。フィールドが正常に取得されたことを示す成功メッセージが表示されます

マッピング」タブと「ルックアップマッピング」タブが表示されます。

マッピング

マッピング」タブでは、

  1. それに応じて、ターゲットフィールドソースフィールド (CSV ファイルのタイトル) にマップします。
  2. ソースフィールドデータタイプを選択します。それに応じて、ターゲットオブジェクトを適切なデータ型に一致させます。次の表は、ソースデータタイプとそれに対応するターゲットデータタイプを示しています。

ソースデータタイプ

ターゲットデータタイプ

ストリング

文字列、ドロップダウンリスト、電子メール、GSID、リッチテキストエリア、複数選択ドロップダウンリスト

番号

数値、パーセンテージ、通貨

ブール値

ブール値

日付

日付

DateTime

日付/時間

: ソースで数値タイプのフィールドを選択すると、ターゲットオブジェクトのフィールドが数値、パーセンテージ、通貨のデータタイプで表示されます。必要に応じて、ターゲットオブジェクト内のフィールドを選択できます。

複雑なデータ型 (例: (ターゲットオブジェクト内の複数選択ドロップダウンリスト) は、基になるデータタイプからマッピングできます (例: 表に示すように、ソース CSV フィールドに文字列 () を入力します。

Image 2.jpg

  1. 時計アイコンをクリックして、「日付」と「日時」フィールドのタイムゾーンを設定します。「タイムゾーンの選択」ウィンドウが表示されます。
  2. タイムゾーン」ドロップダウンリストから、適切なタイムゾーンを選択します
  3. OK」 をクリックします。

Image 3.jpg

メモ: 次に、日付と日時の値は、選択したタイムゾーンからUTCに変換され、Gainsightオブジェクトに保存されます。タイムゾーンを選択しない場合、レコードはGainsightタイムゾーンにあると見なされます。

  1. (オプション) 追加のターゲットフィールドを CSV ソースフィールドにマッピングするには、「追加」をクリックします。
  2. 必要に応じて、ゴミ箱アイコンをクリックしてフィールドを削除します
  3. マッピングを保存」をクリックします。マッチングが正常に保存されたことを示す成功メッセージが表示されます


Image 4.jpg

ルックアップマッピング

ルックアップマッピング」セクションで、「追加」をクリックします。データインポート検索設定ダイアログが表示されます

これは、同じまたは別の Gainsight標準オブジェクトを検索し、フィールドを照合して、検索したオブジェクトからGainsightID(GSID)を取得し、ターゲットフィールドに入力するためです。派生マッピングは GSID データ型のターゲットフィールドでのみ実行できます。

ルックアップには次の 2 種類があります。

  • 直接検索: ダイレクトルックアップにより、管理者は別の Gainsight標準オブジェクトを検索し、その参照オブジェクトからレコードのGSIDを取得できます。
  • セルセルックアップ: セルフルックアップを使用すると、管理者は同じ標準オブジェクトを検索し、別のレコードの GSID をターゲットフィールドに取得できます。

    詳細については、この記事の最後にある「追加リソース」セクションの「データインポート検索」を参照してください。

データインポート検索設定ダイアログで次のアクションを実行します。

  1. 検索タイプ: ドロップダウンリストから、必要に応じて [直接検索] または [自己検索] を選択します。
  2. から: ドロップダウンリストから、ソースオブジェクトを選択します
  3. ターゲットフィールドへ: ドロップダウンリストから、対応するフィールドを選択します
  4. 照合基準: ソース CSV ファイルと検索されたオブジェクトの複数のフィールドを照合して、標準オブジェクトからターゲットオブジェクトに正しい GSID をインポートします。
  5. 一致するものが複数ある場合や一致するものが見つからない場合は、必要に応じて表示されるオプションから1つを選択できます。
  6. 適用」をクリックします。
  7. マッピングを保存」をクリックします。

cURL API

cURL コマンドを生成するには:

  1. cURL API セクションに移動します。cURL コマンドテキストボックスが表示されます。
  2. 生成」をクリックします。cURL コマンドが生成されます。

    メモ: cURL コマンドで生成されるサブドメインは、現在の組織のサブドメインとは異なります。生成されたコマンドは、サブドメインを変更せずに実行できます。テナントは、入力されたアクセスキーで一意に識別されます。

Image 5.jpg

  1. コピー」をクリックして cURL コマンドをコピーします。cURL コマンドを任意のテキストエディタに貼り付けます。
  2. テキストエディタで、「バルク API 接続の作成」で生成されたアクセスキーを入力します。
  3. 下の画像に示すように、CSV ファイルのファイルパスを入力します。

clipboard_ee039d1f3934b0aa0a331fc5cf4ca7def.png

  1. ターミナルまたはコマンドプロンプトに cURL コマンドを入力して送信します。データはターゲットオブジェクトに正常に取り込まれます。
  2. 下の画像に示すように、ジョブの成功または失敗を通知するメールが受信者に送信されます。


image 6.jpg

バルクステータス API  

バルク ステータス API を使用して、バルク API ジョブの進行状況を確認できます。cURL コマンドを正常に実行すると、リクエスト ID とステータス ID とともに true が返されます。このステータス ID は、アップロードの進行状況を追跡するために バルク ステータス API からデータを取得するために使用されます。バルクステータス API の詳細については、バルクステータス API の記事を参照してください。

仕事活動 

アクティビティページでは、すべてのデータジョブの実行アクティビティと更新アクティビティを表示できます。このページからジョブのエラーログをダウンロードして、構成の問題のトラブルシューティングに役立てることもできます。詳細については、この記事の最後にある「その他のリソース」セクションのアクティビティページを参照してください。

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