Embeddedコネクションウィジェットの実装 ​

Embeddedコネクションウィジェットを使用して、顧客に代わって連携を構築および保守できます（これはManaged Servicesモデルとも呼ばれます）。 Embeddedパートナーが顧客に代わって連携を構築および保守するケースでは、Embeddedコネクションウィジェットを推奨します。

Embeddedコネクションウィジェットは、パートナーUI内に埋め込まれたiframeです。 埋め込まれたiframeには、パートナーのアプリケーションを離れることなく、顧客がWorkatoでコネクションを認証するためのログインウィンドウが含まれています。 アプリコネクションが認証された後、パートナーはWorkatoのEmbedded APIを使用して、顧客向けに構築されたレシピをプログラムで開始または停止できます。

Embeddedコネクションウィジェットを使用するには、直接リンクURLを構築し、パートナーUIのiframe内に埋め込む必要があります。

このページは、次のセクションで構成されています:

• 前提条件
• direct link URLの構築
• URLをiframeに埋め込む
• PostMessage API

前提条件 ​

直接リンクURLを構築する前に、次の前提条件を満たしていることを確認してください。

• JSON Web Token（JWT）

• (必須) JWTはユーザーを認証し、アプリケーションとリソースへの検証済みアクセスを提供します。 Workatoでコネクションへの安全なアクセスを容易にするには、JWTを生成します。

• RSA秘密鍵と公開鍵

• 埋め込まれたiFrameはJWTトークンを使用して認証されます。JWTトークンは、RS256アルゴリズムで生成された秘密鍵を使用して署名する必要があります。 公開鍵をWorkato Success Representativeに提供する必要があります。 この鍵は、生成されたJWTトークンを検証するために使用されます。 生成された鍵はPEM形式である必要があります。 Workatoドキュメントで、秘密鍵と公開鍵のペアを生成する方法の手順を参照してください。

• EmbeddedベンダーID

• JWT署名検証キーの更新APIエンドポイントを使用して、EmbeddedベンダーIDを取得します。 このIDを使用してJWTトークンを生成します。

• Workato APIキー

• このAPIキーは、Embedded Partner APIへのアクセスを認証するために使用されます。 ワークスペース管理者 > APIクライアントに移動し、新しいAPIクライアントを作成して、生成されたAPIトークンを保存することで、APIキーを作成できます。

• オリジンURL

• オリジンURLは、コネクションウィジェットのiframeを埋め込むデフォルトドメインです。 これにより、親ウィンドウはPostMessage APIを介してメッセージを受信できます。 origin URLをWorkato Success Representativeに提供してください。

• コネクションID
• (必須) 各Workatoコネクションには、対応するコネクションIDがあります。 ウィジェットで顧客に認証してもらう各Workatoコネクションについて、そのコネクションのコネクションIDが必要です。 コネクションIDがわからない場合は、コネクション一覧APIを呼び出して取得できます。

• 顧客Team Account ID

• (必須) これはEmbedded顧客ワークスペースの一意のIDです。 UIまたはAPIでTeamアカウントIDを取得できます。 UIからTeam IDを取得するには、Admin Consoleに移動し、特定の顧客を選択します。Team IDはURLに表示されます。 Team IDは、WorkatoのEmbedded Partner APIを呼び出して顧客ワークスペースまたは顧客ワークスペースのリストを取得することでも取得できます。

• 直接URL

• (必須) 直接リンクURLのベースは、使用するデータセンターによって異なります。 使用するデータセンターに合わせてフォーマットされた直接URLを構築し、コネクションウィジェットをパートナーUIに埋め込む必要があります。

URLパラメーターの設定 ​

直接URLの形式は、使用するデータセンターによって異なります。 形式は次の構造を使用します:

https://<data_center>/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

USデータセンターhttps://app.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

EUデータセンターhttps://app.eu.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

JPデータセンターhttps://app.jp.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

SGデータセンターhttps://app.sg.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

AUデータセンターhttps://app.au.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

ILデータセンターhttps://app.il.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

CNデータセンターhttps://app.workatoapp.cn/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

KRデータセンターhttps://app.kr.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>

iframeにURLを埋め込む ​

次のコードを使用して、アプリケーション内のiframeに直接リンクURLを埋め込みます:

<iframe src="https://www.workato.com/direct_link/embedded/connections/<connection_id>?workato_dl_token=<jwt_token>"></iframe>

PostMessage API ​

Workatoはwindow.PostMessage()メソッドを使用して、コネクションウィジェットからアプリケーションにメッセージを送信します。 このメソッドは、EmbeddedコネクションウィジェットウィンドウにさまざまなUI状態をレンダリングします。 Postメッセージは次の形式に従います:

{ type: string, payload: object }

サポートされているPostMessages ​

heightChange ​

コンテンツの高さを変更し、iframeがパートナーのUIに合わせてサイズを調整できるようにします。

ペイロード:

{
   height: number
}

サンプルPostメッセージ:

{
    "wk": true,
    "type": "heightChange",
    "payload": {
        "height": 467
    }
}

connectionStatusChange ​

コネクションステータスの変更を報告します。 このイベントを使用して、レシピの開始、外部APIの呼び出し、その他コネクションステータスが変更される場合など、さまざまなワークフローを処理します。

ペイロード:

{
  id: number,
  provider: string,
  connected: boolean,
  error: string
}

サンプルPostメッセージ:

{
    "wk": true,
    "type": "connectionStatusChange",
    "payload": {
        "id": 453799,
        "provider": "google_drive",
        "connected": false
    }
}

error ​

エラーメッセージを報告します。

ペイロード:

{
  message: string
}

サンプルPostメッセージ:

{
  "wk": true,
  "type": "error",
  "payload": {
    "type": "FatalEmbeddingError",
    "message": "Fatal embedding error: sub_missing",
    "details": {
      "reason": "sub_missing"
    }
  }
}

サポートされているPostMessagesの例 ​

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script>
      window.addEventListener('message', receiveMessage);
      function receiveMessage(event) {
        var data = JSON.parse(event.data);

        switch (data.type) {
          case 'heightChange':
            document.getElementById('workatoId').style.height = data.payload.height + 'px';
            break;
          case 'connectionStatusChange':
            var message = data.error || (data.payload.connected ? 'Connected' : 'Disconnected');
            document.getElementById('statusId').innerText = message;
            break;
          case 'error':
            console.log(data.payload.message);
        }
      }
    </script>
  </head>
  <body>
    <h4>Status: <span id="statusId"></span></h4>
    <iframe id="workatoId" src="https://www.workato.com/direct_link/embedded/connections/<connection_id>>?workato_dl_token=<token>" style="width: 500px; height: 150px; border: 0"></iframe>
  </body>
</html>