外部APIでGainsightアクションを作成する

API入門

アプリケーションプログラミングインターフェイス (API) は、ソフトウェアアプリケーションの構築に役立つルーチン、ツール、およびプロトコルのセットです。APIは、2つのソフトウェアアプリケーションが相互作用するための道を開きます。

Layman用語のAPI: アパレル店を訪れることを考えてみましょう。X-largeサイズのシャツをお探しです。ただ、店舗には必要なアパレルは中サイズがあるだけです。必要とするX-Largeサイズは倉庫にあり、アクセスできません。セールスパーソンに頼んで、必要なサイズを調達してもらいます。セールスパーソンはあなたの要望を尊重し、必要なサイズのアパレルを用意します。

上記の例では、セールスパーソンがAPIとなります。あなたは最初のシステムであり、倉庫は2番目のシステムです。上記で定義したように、API は、情報を要求するシステム (ユーザー) と、必要な情報を処理するシステムという、2つのシステム間の相互作用を容易にします。

技術用語では、APIとは、あるシステム（ソースシステム）からのリクエストを受け付け、このリクエストを必要なシステム（ターゲットシステム）に転送し、レスポンスを収集し、そのレスポンスを最初のシステムに返すメッセンジャーと定義できます。

API許可メソッド

ターゲットシステムから情報を受け取るには、ソースシステムがそれ自体を認証する必要があります。認証方法には4 つあります。

URLベースの認証: この方法では、ターゲットシステムのURL を知る必要があります。この方法では、シークレットコードやパスワードは必要ありません。上記のコスチュームの例では、知っておく必要があるのは倉庫の住所だけです。倉庫にはロックシステムはありません。
ユーザー名とパスワード認証: この方法では、ソースシステムが自身を認証するための認証情報を提供する必要があります。上記のアパレルの例では、倉庫のコンテンツにアクセスするためには、倉庫のキー（APIではユーザー名とパスワード）が必要となります。
トークンベースの認証: このアプローチでは、ソースシステムがそれ自体を認証する手段としてトークンを提供します。このトークンは、一般的にキーと値のペアです。上の服の例では、ショッピングストアから情報 (トークンなど) が記載されたメールが送信されました。倉庫に入るには、このトークンを倉庫管理人に提示する必要があります。
OAuth 2.0 認証: OAuth 2.0プロトコルを使用すれば、認証情報を公開することなく、安全で限定的な第三者による資産へのアクセスを許可できます。外部アプリケーションへの接続を作成する場合、接続を確立するための認証方法としてOAuth 2.0を選択し、この認証メカニズムに関するパラメーターを設定できるようにしました。

API での操作

APIを利用することで、以下の操作を行うことができます：

受信データ (GET): Getは、ソースシステムがターゲットシステムから情報を受信するプロセスを参照します。アパレルの例では、(ソースシステム) ウェアハウス(ターゲットシステム) から特定のクロスを取得したい場合、get 操作を実行します。
新規データの作成(POST): ソースシステムがターゲットシステムに何らかの情報を公開すると、POST 操作が実行されたと言われます。アパレルの例では、サプライヤー(ソースシステム)が新しいアパレルを倉庫(ターゲットシステム)にプッシュしたい場合、POST操作が実行されると言われています。
データ更新(PUT): ソースシステムがターゲットシステムの一部のデータを更新すると、PUT 操作が実行されたと言われます。アパレルの例では、テーラー(ソースシステム)が倉庫(ターゲットシステム)から一部のアパレルのサイズを変更すると、PUT操作が実行されると言われています。
データ削除 (DELETE): 抽出側システムで反映側システムの一部のデータを削除すると、削除処理が実行されるといいます。アパレルの例では、倉庫所有者(ソースシステム)が倉庫(ターゲットシステム)から損傷したアパレルをいくつか廃棄すると、削除操作が実行されると言われています。

API メッセージのコンポーネント

ソースシステムが API を介してターゲットシステムにデータを要求する場合、API メッセージには次のコンポーネントが含まれます。

エンドポイントURL: これは、データを要求するターゲットシステムのURL です。アパレルの例では、倉庫の住所をエンドポイントURLとして考えることができます。
メソッド: API が実行するオペレーション。GET、POST、PUT、DELETEのいずれかを指定できます。
ヘッダー: タイトルは、ソースシステムによってなされた特定の懸念事項または要求を指します。アパレルの例では、特定ブランドのアパレルを購入したいことがありますので、これをヘッダーの例とすることができます。
データ: API を介してリクエストされた実際のデータ。通常、データはキーと値のペアの形式で表示されます。以下の画像は、API データを表示しています。データがキー値形式で表示されていることがわかります。

概要

Call External APIを使用すると、Gainsight内から外部システムに接続し、APIを介して外部システムからのアクションをリクエストできます。この場合、Gainsightがソースシステムで、接続している外部アプリケーションがターゲットシステムです。

外部アクションは、ルールエンジンアクションの作成中、およびジャーニーオーケストレーターからプログラムの設定中に使用できます。

ビジネスユースケース：

オポチュニティ獲得時にSlackにメッセージを投稿するルールを作成できます。このメッセージは、新しく獲得した商談の詳細をチームが把握するのに役立ちます。この場合、Gainsightがソースアプリで、Slackがターゲットアプリです。使用される方法は、POST (Slack に新しいメッセージを投稿する) です。
CSVファイルやS3バケットからすべてのエスカレーションを取得し、それぞれのエスカレーションに対してJIRAチケットを作成するルールを作成できます。この場合、Gainsightがソースアプリケーションで、JIRAがターゲットアプリケーションです。使用する方法はPOST(JIRAチケットの新規作成)です。

前提条件

外部システムへの接続を確立するには、認証方法 (上記で指定) のいずれかを使用する必要があります。この設定は、コネクターページのカスタムコネクターウィジェットから実行できます。
外部アプリケーションとの接続を確立した後は、必要に応じてAPIメッセージを設定できます。API構造を確定した後は、Call External APIアクションタイプでAPIを使用できます。API 設定は、Gainsight の外部アクション ページから実行できます。APIのフォーマットや構造は、外部システムから取得できます。一般的に、外部システム (slack、Zendesk など) は、そのAPIをWebサイトで公開します。

カスタムコネクターを設定

Gainsightでは、コネクター 2.0ページにカスタムコネクターが導入されています。カスタムコネクターを使用して、外部アプリケーションへの接続を確立できます。接続が確立された後は、外部アクションページで外部アプリケーションのアクションを作成できます。外部アプリケーションへの接続を作成するときは、接続を確立するために使用される許可メソッドを指定してから、この許可メカニズムのパラメーターをセットアップする必要があります。Gainsightでは、外部システムとの接続は1つだけ作成することを推奨しています。そして必要に応じて、その接続に複数のアクションを作成することができます。

カスタム接続を使用するには:

管理 > コネクター2.0に移動します。
カスタマーコネクターをクリックします。
接続を作成をクリックします。接続を作成ウィンドウが表示されます。
下記のタスクを実行します。
1. 接続名フィールドに、接続の名前を入力します。
2. 認証タイプドロップダウンメニューから、基本認証またはトークンベースの認証またはOAuth認証のいずれかを選択します。
  - 基本認証：この認証方式は、従来のユーザーIDとパスワードを使用して接続を認証するものです。オプションで、ヘッダーにキー値ペアを入力することもできます。必要に応じて、複数のヘッダーを入力することができます。また、ターゲットアプリケーションのGet URLを指定する必要があります。
  - トークンベースの認可：この認証方式は、ヘッダーベースのキー値ペアを使用して認証を実行します。必要に応じて、複数のヘッダーを入力することができます。また、ターゲットアプリケーションのGet URLを指定する必要があります。
  - OAuth 2.0認可: この認証方式では、アクセストークンを使用します。Access Token は、付与された権限を表す文字列です。
    - クライアント シークレット: 外部アプリケーションからクライアントシークレットを指定します。
    - クライアントID: 外部アプリケーションからクライアントID を入力します。
    - アクセストークンURL: 外部サービス API ドキュメントに記載されているアクセストークンを指定します。
    - 認証URL: 外部API ドキュメントに記載されている許可URL を指定します。
    - コンテンツタイプ: 外部のライセンスプロバイダーと互換性のあるコンテンツタイプを選択してください。
    - スコープ: 接続の権限スコープを指定します。
      注意: OAuth 2.0 用語のAccess Tokenで表される権限は、スコープと呼ばれます。アプリケーションが認証に Auth0 を使用する場合、必要なスコープを指定します。これらのスコープがユーザーによって認証されている場合、アクセストークンはそれらの認証範囲を表します。

注意: 認証のタイプとして、Noneを選択することもできます。これにより、アプリケーションへの直接アクセスができます。

(オプション) 接続の説明を入力します。
テスト接続をクリックし、ターゲットアプリケーションとの接続を確認します。
保存をクリックします。

管理者は、必要に応じて編集オプションを使用して、設定済みのカスタムコネクターを編集することもできます。

外部アクションを設定

外部アプリケーションとの接続を設定すると、外部アクションページでアクションを作成できます。ここでアクションを作成した後は、ルールエンジンのアクションタイプフィールドおよびJOで使用できます。外部アクションページには、あなたが設定できる5つのセクションがあります。

たとえば、Slackが設定済みの外部コネクターである場合、「Slackに投稿する」「Slackの新規チャンネルを作成する」といったアクションタイプを作成できます。

Slackコネクター用に作成されたアクションは、「外部APIコール」アクションタイプで使用できます。「外部APIコール」アクションにより、Gainsightは外部アプリケーションと対話し、外部アクションページで設定されたアクションを実行することができます。設定したアクションタイプを使用して、Slackへのメッセージ投稿、ステータスの作成またはZendeskチケットへの更新、およびJIRAチケットの作成など、日々のアクティビティを自動化することができます。

重要: アクションの接続および設定は、APIドキュメントをサポートして提供する外部アプリケーションに対してのみ可能です。

「外部アクション」ページにアクセスするには、

管理 > 外部アクションに移動します。
アクションを作成をクリックします。

「外部アクション」ページには、以下のさまざまなセクションがあります。

基本情報

このセクションでは、下記の詳細を実行します。

前提条件: ゲインインインサイトで外部アクションを設定するために必要なパラメータを収集するには、特定のアクションについて外部アプリケーションのAPI ドキュメントを参照してください。これらのAPI パラメータは、API を介して外部アプリケーションにGainsight を接続し、必要なアクションを実行するために詳細を渡すために必要です。

コネクターを選択: アクションを作成するConnector 2.0ページで作成したコネクターを選択します。
アクション名: アクションの名前を入力します。
方法とURL：HTTP メソッドを選択し、設定するアクションに固有の外部アプリケーションの API ドキュメントからエンドポイント URL を入力します。

注意: 管理者は URL のトークンまたは変数を使用して動的 URL にすることもできます。

ペイロード

API は、パラメータとして扱うには大きすぎるデータ構造を交換するためにペイロードを使用します。Gainsight での外部アクションは、次の2 種類のペイロードをサポートします。

プレーン：指定された形式でアプリケーションのAPIドキュメントからコピーして、ペイロードの詳細を入力します。(例: JSON形式)

このセクションで入力したトークンからフィールドを作成するには、下記のように二重波括弧でトークンを追加します。

{“text” :  “ {{ Message }} ” }

x-www-form-urlencoded: アプリケーションのAPI ドキュメントで定義されているキー、値のペアを入力します。このセクションに挿入されたトークンは、フィールドとして解析されます。キーと値ペアを追加するには、 +をクリックします。

Key: text, Value: {{Message}}

注意: 構文解析から二重引用符(")とバックスラッシュ(\)をエスケープするには、プレフィックスとしてバックスラッシュ(\)を使用します。他の文字用のプリフィクスをつける必要はありません。

ヘッダ情報

このセクションには、APIドキュメントで定義されているヘッダー情報のキーと値ペアを入力します。管理者は、外部アプリケーションの API ドキュメントで共有されている複数のキーと値のペアを追加することもできます。ここで入力したトークン(値) は、前のステップで説明したように、フィールド セクションのフィールドとして解析されます。

フィールド

フィールドセクションにおいて、表示されるフィールドのリストは、URL、ペイロード、ヘッダーから自動的に解析されたものです。フィールドの横にある設定アイコンは、フィールドのデータタイプを設定します (例: 以下に示すように、文字列、日付、日時など。

ルールエンジンでCall External APIアクションタイプを使用すると、フィールドセクションに表示されているフィールドがターゲットフィールドとして入力されます。これらのフィールドには、データセットから値を取り込むことができます。

詳細設定情報

このセクションでは、管理者は「最大試行回数制限」フィールドの制限を設定することができます。このフィールドに指定された数値は、アクションが失敗した場合にシステムが再試行できる回数を表します。デフォルトでは、この値は3 に設定され、最大制限は5 を超えないようにする必要があります。

作成をクリックしてアクションを保存します。

管理者は、テストをクリックして追加したアクションをテストし、必要に応じて編集オプションをクリックして設定されたアクションの詳細を編集することもできます。

この場合、操作をテストすると、チケットがZendeskに作成されます。

このセクションでは、下記の詳細を実行します。

前提条件: ゲインインインサイトで外部アクションを設定するために必要なパラメータを収集するには、特定のアクションについて外部アプリケーションのAPI ドキュメントを参照してください。これらのAPI パラメータは、API を介して外部アプリケーションにGainsight を接続し、必要なアクションを実行するために詳細を渡すために必要です。

コネクターを選択: アクションを作成するConnector 2.0ページで作成したコネクターを選択します。
アクション名: アクションの名前を入力します。
方法とURL：HTTP メソッドを選択し、設定するアクションに固有の外部アプリケーションの API ドキュメントからエンドポイント URL を入力します。

注意: 管理者は URL のトークンまたは変数を使用して動的 URL にすることもできます。

API は、パラメータとして扱うには大きすぎるデータ構造を交換するためにペイロードを使用します。Gainsight での外部アクションは、次の2 種類のペイロードをサポートします。

プレーン：指定された形式でアプリケーションのAPIドキュメントからコピーして、ペイロードの詳細を入力します。(例: JSON形式)

このセクションで入力したトークンからフィールドを作成するには、下記のように二重波括弧でトークンを追加します。

{“text” :  “ {{ Message }} ” }

x-www-form-urlencoded: アプリケーションのAPI ドキュメントで定義されているキー、値のペアを入力します。このセクションに挿入されたトークンは、フィールドとして解析されます。キーと値ペアを追加するには、 +をクリックします。

Key: text, Value: {{Message}}

注意: 構文解析から二重引用符(")とバックスラッシュ(\)をエスケープするには、プレフィックスとしてバックスラッシュ(\)を使用します。他の文字用のプリフィクスをつける必要はありません。

このセクションには、APIドキュメントで定義されているヘッダー情報のキーと値ペアを入力します。管理者は、外部アプリケーションの API ドキュメントで共有されている複数のキーと値のペアを追加することもできます。ここで入力したトークン(値) は、前のステップで説明したように、フィールド セクションのフィールドとして解析されます。

フィールドセクションにおいて、表示されるフィールドのリストは、URL、ペイロード、ヘッダーから自動的に解析されたものです。フィールドの横にある設定アイコンは、フィールドのデータタイプを設定します (例: 以下に示すように、文字列、日付、日時など。

ルールエンジンでCall External APIアクションタイプを使用すると、フィールドセクションに表示されているフィールドがターゲットフィールドとして入力されます。これらのフィールドには、データセットから値を取り込むことができます。

このセクションでは、管理者は「最大試行回数制限」フィールドの制限を設定することができます。このフィールドに指定された数値は、アクションが失敗した場合にシステムが再試行できる回数を表します。デフォルトでは、この値は3 に設定され、最大制限は5 を超えないようにする必要があります。

作成をクリックしてアクションを保存します。

管理者は、テストをクリックして追加したアクションをテストし、必要に応じて編集オプションをクリックして設定されたアクションの詳細を編集することもできます。

この場合、操作をテストすると、チケットがZendeskに作成されます。

Gainsight APIの制限

Gainsight APIの推奨API制限は次のとおりです（正確な制限はパッケージによって異なる場合があります）。

同期APIコール: 1 分あたり 100 回の API 呼び出し/1 日あたり 50,000 回の API 呼び出し
非同期APIコール （GainsightバルクAPI制限）：1 時間あたり 10 コール/1 日あたり 100 コール

注意: 上記のAPI制限はすべて*固定ウィンドウ速度制限です。

* 固定ウィンドウのレート制限により、特定時間におけるAPIリクエスト数を制限します。たとえば、サーバーには、1分あたり100件のリクエストしか受け付けない固定ウィンドウアルゴリズムを実装するレート制限コンポーネントを含めることができます。時間枠は固定されており、特定の時間に始まります。たとえば、サーバーは午前10:00から午前10:01までの間に 100 件のリクエストのみを処理します。

その他のリソース

ルールエンジンにおける外部APIコールアクションの使用方法に関する詳細情報については、「外部APIコールアクションタイプ」の記事をご参照ください。

プログラムでの「外部APIコール」アクションの使用方法に関する詳細情報については、プログラムでAPIアクションタイプを呼び出しの記事をご参照ください。

ルールエンジンで外部APIコールアクションタイプを使用して、Zendesk チケットを自動作成する方法に関する詳細情報については、「外部APIコールからZendeskのチケットを作成するアクションタイプ」の記事をご参照ください。

ルールエンジンで外部APIコールアクションタイプを使用して、Slackに自動的にメッセージを投稿する方法に関する詳細情報ついては、外部APIコールアクションタイプでSlackにメッセージを投稿するの記事をご参照ください。