Gainsightからの外部アクションの構成

概要

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

Layman の用語 のAPI: アパレル店を訪れることを考えてみましょう。X-largeサイズのシャツをお探しです。ただ、店舗には必要なアパレルだけが中サイズであります。必要なX-large サイズは、アクセスできない倉庫にあります。必要なサイズを取得するよう営業担当者に依頼する。営業担当者は、要求に応じて、必要なサイズのアパレルを入手します。

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

専門用語では、APIは、システム(ソースシステム)からの要求を受け付け、要求されたシステム(ターゲットシステム)にこの要求を転送し、応答を収集し、最初のシステムに応答を返すメッセンジャーとして定義されます。

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

外部アクションは、ルールエンジンアクションの作成中、およびジャーニーOrchestrator からのプログラムの構成中に使用できます。

ビジネスユースケース:

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

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 データを表示します。データはkey-value 形式で表示されます。

前提条件

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

カスタムコネクターの構成 

Gainsight では、Connector 2.0 ページにカスタムコネクタが導入されています。カスタムConnectorを使用して、外部アプリケーションへの接続を確立します。接続が確立されたら、外部アクションページで外部アプリケーションのアクションを作成します。

外部アプリケーションへの接続を作成するときは、接続を確立するために使用される許可メソッドを指定してから、この許可メカニズムのパラメータをセットアップする必要があります。Gainsightでは、必要に応じて、外部システムへの単一の接続のみを作成し、接続に複数のアクションを作成することをお勧めします。

カスタム接続を作成するには:

1. Administration > Connectors 2.0 に移動します。
2. Create Connection.をクリックしますCreate Connectionウィンドウが表示されます。
3. ドロップダウンメニューで、カスタムコネクタを検索して選択します。
4. 次のフィールドに詳細を入力します。
   1. 接続名: 接続の名前を入力します。
   2. 認証タイプドロップダウンメニューから、Basic またはToken Based またはOAuth 2.0認証のいずれかを選択します。

• 基本: この認証方法では、従来のユーザー名とパスワードを使用して接続を認証します。次の詳細を入力します。
  • ユーザ名: ターゲットアプリケーションのユーザー名を入力します。
  • パスワード: ターゲットアプリケーションのパスワードを入力します。
  • ヘッダ: キーと値のペアをヘッダフィールドに入力します。 + アイコンをクリックして、複数のヘッダを指定します。ヘッダーを削除するには、Xアイコンをクリックします。
  • (オプション)説明: 接続の説明を入力します。
  • URL を取得: ターゲットアプリケーションのGET URL を指定します。
  • Test Connectionをクリックして、ターゲットアプリケーションへの接続を確認します。
  • Saveをクリックします。
• トークンベース: この許可メソッドは、ヘッダーベースのキーと値のペアを使用して許可を実行します。次の詳細を入力します。
  • ヘッダ: キーと値のペアをヘッダフィールドに入力します。 + アイコンをクリックして、複数のヘッダを指定します。ヘッダーを削除するには、Xアイコンをクリックします。
  • (オプション)説明: 接続の説明を入力します。
  • URL を取得: ターゲットアプリケーションのGET URL を指定します。
  • Test Connectionをクリックして、ターゲットアプリケーションへの接続を確認します。
  • Saveをクリックします。
• OAuth 2.0: この認証方式では、アクセストークンを使用します。Access Token は、付与された権限を表す文字列です。次のフィールドに詳細を入力します。
  • コンテンツタイプ: 外部のライセンスプロバイダーと互換性のあるコンテンツタイプを選択してください。
  • リダイレクトURL: これは、アプリが承認されるとリダイレクトされるコールバック URL です。これは、認証コードまたはアクセストークンの抽出に使用されます。コールバックURL は、アプリケーション登録プロセスで使用するURL と一致する必要があります。URL はデフォルトで表示され、コピーするにはコピーアイコンを使用します。
  • 認証URL: 外部API ドキュメントに記載されている許可URL を指定します。
  • アクセストークン URL: 外部サービス API ドキュメントに記載されているアクセストークンを指定します。
  • クライアントID: 外部アプリケーションからクライアントID を入力します。
  • クライアント シークレット: 外部アプリケーションからクライアントシークレットを指定します。
  • スコープ：接続の許可範囲を指定します。
    
    注: OAuth 2.0 用語のAccess Token で表される権限は、スコープと呼ばれます。アプリケーションが認証に Auth0 を使用する場合、必要なスコープを指定します。これらのスコープがユーザーによって承認されている場合、アクセストークンはそれらの承認範囲を表します。
  • (オプション) 説明: 接続の説明を入力します。

5. 接続を検証するには、Authorizeをクリックします。

管理者は、  オプションを編集して、設定したカスタムコネクタを編集することもできます。

外部アクションの設定

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

たとえば、Slack が外部コネクタとして設定されている場合は、「Post to Slack」や「Create a New Slack channel」などのアクションタイプを作成します。

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

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

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

1. Administration > External Actions.に移動します。
2. アクションの作成をクリックします。

External Action ページには、以下のさまざまなセクションがあります。

その他のリソース

Gainsight API の詳細については、以下の記事を参照してください。

•  外部APIアクションタイプの呼び出し 
•  プログラムでのAPI アクションタイプの呼び出し 
• コール外部API アクションタイプからのZendesk チケットの作成
• コール外部API アクションタイプを使用してメッセージをSlack に送信する