サポート終了通知

2018年7月 より、HTTP コネクターの V2 バージョンがリリースされています。既存の V1 HTTP コネクターと HTTP (OAuth2) コネクター、および HTTP アクションは廃止されます。

このドキュメントでは、その廃止されるコネクターについて説明します。V2 HTTP コネクターのドキュメントはこちらを参照してください。

HTTP コネクター V1

この HTTP コネクターは、HTTP ベースの API を持つ任意のクラウドアプリケーションとの統合を可能にします。新しいコネクターを作成したり、既存の Workato コネクターに新しいアクションのトリガーまたはアクションを追加することができます。

HTTP コネクターには以下の2種類があります。

1. 標準の認証とバリエーション
2. OAuth 2

HTTP コネクターと HTTP (Oauth2) コネクターの違い

接続の認証フローの他、両方のコネクターの機能は同じです。Webhook トリガー、ポーリングトリガー、および REST アクションの設定プロセスは同一です。

非 OAuth 2.0接続の場合、接続が有効であることを確認するため、追加のテスト API 要求が必要です。

HTTP コネクターとは何か、何に対して有用か

汎用の HTTP および HTTP (OAUTH2) コネクターを使用すると、アプリケーションプログラムインターフェイス (API) により、すべて (ほとんど) のクラウドアプリケーションとやり取りできます。つまり、ボックスから出した Workato 製コネクター以外で、統合レシピを動作させるために必要なトリガーまたはアクションをすべて構築できます。

HTTP コネクターでは、独自のトリガーまたはアクションを Workato で構築するのに20分もかかりません。このコースでは、以下の方法について説明します。

• 接続 (OAuth2 および非 Oauth2) をアプリに設定する方法

• アプリで何かが発生した場合に通知を受けるように独自の Workato トリガーを構築する方法

• アプリ内で特定のステップを自動的に実行するように Workato アクションを構築する方法

会計システムで請求書を作成する場合には、JSON フォーマットの要求本体を含む POST 要求を実行できます。分析アプリケーションからメトリックスを取得する場合には、クエリーパラメータを含む GET 要求を実行します。新しいリードがオンラインフォームに入力したときにトリガーする場合には、新しいリードがフォームに入力したらすぐに Workato に通知するよう、Workato トリガーを作成します。開始するにあたって支援が必要な場合は、このまま読み続けるか、カスタマーサクセスマネージャーまでお問い合わせください。 :)

OAuth 2.0接続の設定

HTTP (OAuth2) コネクターでは、OAuth 2.0標準の認証コード付与のバリアントで、現在事実上の認証標準となっており、多数のクラウドアプリで採用されているものをサポートしています。これが広く採用されているのは、ユーザーが自分のユーザー名およびパスワードをサードパーティに開示することなく、サードパーティに自分のアプリへのアクセス権を付与できるためです。この場合、Workato はユーザをそのアプリにリダイレクトするだけです。ユーザーがここでログインの資格情報を入力さえすれば、API 要求を行う際にユーザに代わって Workato が対応することをアプリが信用することができます。

HTTP (OAuth2) コネクター接続のフィールド

OAuth 2.0接続の関連コンポーネント

認証 URL

[Connect] ボタンをクリックしたときに、リダイレクトされる URL。通常はこれによってアプリのログイン画面が表示されます。

一部の API では、認証 URL に特定のパラメータを含める必要があります。一般的な例としては、response_type (code または token) や scope (read、write、admin など) があります。

これは、接続しているアプリの API ドキュメントの認証のセクションで公開されているはずです。

トークン URL

Workato が認証トークンを取得する URL。この認証トークンは、アプリとそのデータへのアクセス許可を持っていることを確認するために使用されます。

これは、接続しているアプリの API ドキュメントの認証のセクションで公開されているはずです。

クライアント ID とクライアントシークレット

ユーザーは、クライアント ID により、これらの API 呼び出しを送信しているユーザーとして特定され、クライアントシークレットにより、このユーザーとして認証されます。

これは通常、接続するアプリのログインアカウントの設定または統合ページ (または同等のページ) にあります。これはユーザーのアカウントに固有であり、秘密にしておく必要があります。

資格情報

アプリにログインするためのユーザー名とパスワードのセット。Workato がアプリ内のデータにアクセスする許可を与えます。

この資格情報を持つユーザーは、アクセスするレコード (顧客レコード、売り上げ請求書レコードなど) に対する適切な読み取り / 書き込み権限を持っている必要があります。

リダイレクト / コールバック URL (アプリで設定)

認証フローおよび資格情報 / トークンの交換の後に Workato にリダイレクトバックするためにアプリに指定された URL。

統合設定画面で要求されたら、この URL https://www.workato.com/oauth/callback をアプリに指定します。

例 - OAuth2 を介して Eventbrite に接続する

OAuth 2.0アプリケーションに接続する例を見てみましょう。ここでは、イベント管理および発券アプリケーションである Eventbrite を使用します。

Eventbrite の OAuth 2.0 [Authentication] ページ

接続に必要な2つのフィールド、[authorize URL] と [access token URL] の値はドキュメントの該当ページに記載されています。URL にさらにパラメータを付加する必要がある場合もあります。Eventbrite のドキュメントには、URL : https://www.eventbrite.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_KEY にポストする必要があると記載されています。

ただし、Workato ではクライアントキーを処理するため、接続のための入力フィールドで必要な項目は以下のとおりとなります。

Eventbrite authorize URL :

https://www.eventbrite.com/oauth/authorize?response_type=code

Eventbrite access token URL :

https://www.eventbrite.com/oauth/token

Eventbrite アカウントに正常に接続するには、クライアント ID とクライアントシークレットも必要となる場合があります。これを取得するには、アプリにクライアント ID とシークレットを割り当てることができるよう、アプリを Eventbrite に登録する必要があります。Eventbrite にログインし、[Account Settings] > [App Management] に移動します。

Eventbrite の [App Management] 画面

[App Management] ページに、クライアント ID (および呼び出されるキー) が表示されます。[Show Client Secret] および [OAuth Token] セクションを展開し、クライアントシークレットを取得して、[App Extension] セクションに移動し、Eventbrite にコールバック URL https://www.workato.com/oauth/callback を入力します。

完了した Eventbrite 接続

非 OAuth 2.0接続の設定

非 OAuth 2.0接続の確立は、OAuth 2.0接続の確立よりやや複雑で、統合するアプリケーションに固有の認証タイプを選択する必要があります。ここでは、使用可能なさまざまなオプションを紹介します。

None

認証の詳細を指定せずに接続を作成できます。通常、アプリから Workato トリガーを受け取るのみの場合に使用されます。Workato は webhook を送る URL を生成し、送信された Webhook ペイロードから情報を取得します。 HTTP コネクターの認証タイプ : None

Basic

ユーザー名とパスワードを必要とします。ユーザー名とパスワードの代わりに、アカウント設定から取得できる API キーと API トークンも使用できます。これは、SSL での送信時に Base64 でエンコードされます。これが一般的な認証フローです。 HTTP コネクターの認証タイプ : Basic

Header Auth

通常のユーザー名とパスワード、または API キー以外の追加ヘッダーを必要とするアプリケーション用、または要求で送信されるヘッダーをカスタマイズする場合に使用します。ヘッダー認証は、そのまま使用できる生成済みのトークンがある場合に使用できます。 HTTP コネクターの認証タイプ : Header Auth

Query params

認証構造が、パラメータとして API キーを使用した認証に基づいているアプリケーション用です。ユーザーは、パラメータ認証フィールドに、キーと値のペアのパラメータを追加する必要があります。 HTTP コネクターの認証タイプ : Query params

Custom

上記の任意のフィールドの組み合わせを使用できます。 HTTP コネクターの認証タイプ : Custom

非 OAuth 2.0接続のテスト

接続したら、非 OAuth 2.0接続をテストして、それが有効であることを確認する必要があります。このためには、テスト API 要求 (簡単なものは GET 要求) を送信します。これに成功すれば、接続が有効であることがわかります。

例 - 基本認証を介して JIRA に接続し、GET アクションを介して接続をテストする

基本認証を使用して JIRA に接続してみましょう。基本認証に関する JIRA のドキュメントはこちら (opens new window)を参照してください。JIRA の場合、サブドメイン (これにより、JIRA の企業インスタンスの接続先 (基本的には企業の JIRA データベース) がわかります)、ユーザー名、パスワードを指定する必要があります。

この例では、企業名 Workato321 で企業インスタンスを作成し、JIRA によって自動的にサブドメインが workato321.atlassian.net (opens new window) に割り当てられています。

PPP という新しい JIRA インスタンスにプロジェクトも作成しました。これは後で接続のテストに使用されます。

JIRA 接続の設定

既存のプロジェクト PPP が表示されたサブドメイン workato321.atlassian.net (opens new window) の JIRA スクリーンショット

ユーザー名とパスワードは、接続設定で以下のように指定できます。クラウド上に JIRA インスタンスがあるため、[On-prem secure agent] フィールドではゲートウェイは選択していません。

JIRA 接続設定

GET アクションの実行による JIRA 接続のテスト

まだ終わっていません。接続をテストしましょう。JIRA の場合、インスタンス (サブドメイン) の情報を API エンドポイントに送信する必要があるため、接続設定では指定する必要はありません。

接続をテストするため、以下のすべてのプロジェクトのエンドポイントの GET を実行することにより、JIRA インスタンス内のすべてのプロジェクトを取得するよう、Workato に依頼します。https://workato321.atlassian.net/rest/api/2/project。

これはテストレシピの外観です。スケジューラートリガーがあります。これは実行レシピを選択するとすぐにジョブが実行されるように、新たにスケジュールされたイベントです。これは単に API エンドポイントを呼び出します。これは簡単なテストなので、サンプル応答本体には入力していません。後続のステップで使用するデータベースの構築についてはまだ考慮していません。

JIRA プロジェクトのリストを取得するように設定された HTTP アクション

ここで、レシピを実行し、実施するジョブを選択します。入力タブで HTTP コネクターにより何が送信されているかを確認できます。

ジョブの詳細入力タブに表示される、送信された API 要求

また、API エンドポイント、およびユーザー名とパスワードが正しい場合、出力タブ (ここでは PPP プロジェクト) の下に返されたデータが表示されます。

ジョブの詳細出力タブに表示される、JIRA から取得された API 応答

Webhook トリガーの構築

統合するアプリが Webhook をサポートしている場合、これはアプリの API ドキュメントに記載されているはずです。Webhook は、イベントが発生すると直ちにアプリからターゲット URL に送信される通知です。通常は、どのイベントの通知を受け取るのかを定義できます。Workato で Webhook トリガーを構築するには、これらの通知を Workato レシピに送るよう指定し、アプリでイベントが発生した場合には必ずそのレシピアクションがトリガーされ、実行されるようにします。

たとえば、新しい顧客のチケットが Urgent というステータスでマークされた場合に必ずレシピに通知する Webhook トリガーを構築し、SMS をこの顧客のアカウントマネージャーに送信するアクションを取ることができます。この場合、レシピにより、確実に緊急のチケットにタイムリーに応答することができます。

アプリケーションから Webhook を受け取ることのみを検討している場合は、接続を設定したり、認証フローを実行する必要はありません。HTTP 接続を設定する場合は、None の認証タイプを選択してください。

以下は、Workato の Webhook トリガーの入力フィールドです。Webhook トリガーの構築時に注意する主なフィールドについて見てみましょう。

HTTP コネクターの Webhook トリガー

Webhook で生成されたターゲット URL

アプリで生成された Webhook を送る URL アドレス。この URL で生成された36文字の文字列はアカウントに固有で、アカウントを安全に保ちます。そうしない場合は、インターネット上の他者がランダムデータを送信することができます。

デフォルトでは、この URL は不完全です。ターゲット URL として使用されるフル URL を生成するイベント名を指定します。

イベント名

このトリガーで実行することの説明に使用されます。通知を受け取るイベントが何であるかがわかるように、ここにはわかりやすい名前を入力します。

イベント名が Workato で生成された URL の末尾に付加されて、このレシピで一意の URL が生成されます。

Webhook のタイプ

ペイロードの解読および処理方法がわかるように、レシピに、期待される Webhook のタイプと受信するデータのフォーマットを指示します。これは、API ドキュメントに記載された仕様に依存します。

一部の API では、さまざまなフォーマットで Webhook ペイロードを送信することができます。その場合は、より使いやすいものを選択し、Webhook ペイロードの例の入力フィールドに適切なフォーマットでペイロードを指定してください。

Webhook ペイロードの例

アプリから Workato に送信されることが期待される Webhook ペイロードのサンプルを指定します。一般に API ドキュメントに記載されているため、適切な JSON、XML、または定義したとおりのフォームエンコードフォーマットでこれを単にコピーして貼り付けます。アプリによって送信されるカスタムの値があることがわかっている場合は、これに正しいフォーマットでフィールドを追加することもできます。

ここで指定されるペイロードの例は、トリガーイベントの発生時に Workato に送信される実際のペイロードには影響を与えません。代わりに、サンプルスキーマを使用して、出力データツリーとそのデータピルを構築し、Webhook に入ってくるデータを、データツリー内の後続のステップに適切にマッピングできるようにします。

設定された Webhook トリガーの例

設定で指定した Webhook ペイロードの例に対応するトリガーデータスキーマ

例 - Eventbrite で新しい注文トリガーを構築する

この例では、イベント Christmas Marathon で、Eventbrite で注文が発生するたびにトリガーするリアルタイムの Webhook トリガーの構築について説明します。要件については、Eventbrite の Webhook ドキュメント (opens new window)を参照してください。

Workato HTTP トリガーの設定

まず、Webhook を送信する URL を Workato から取得する必要があります。このために、Workato で Webhook トリガーの作成を開始します。イベント名を入力して完全なターゲット URL を作成し、Eventbrite Webhook のフォーマットである JSON ペイロードでの PUT/POST を選択しています。

ペイロードがどのように見えるかがまだよくわからないため、ここでは Webhook ペイロードの例は空のままにします。

イベント名と空のペイロードによる Webhook トリガーの設定例

Eventbrite Webhook の設定

Eventbrite で、 [Account Settings] > [Webhooks] に移動し、Webhook を追加します。Workato から取得したペイロード URL を入力し、監視するイベントを選択します (オプションとして [All events] も使用できます)。さまざまなイベントを待ち受けてトリガーするように選択できることがわかりますが、ここでは Christmas Marathon イベントの新しい注文を監視するだけです。

Eventbrite で行われる新しい注文を監視する Webhook の作成

トリガーをテストするため、Webhook の設定ページから、または監視しているイベントで注文を作成することにより、テスト注文を送信できます。Webhook トリガーを設定できたら、ジョブを受信します。

ここでは、テストジョブは正常に実行されており、ジョブの詳細ページのトリガー出力タブに移動することで Webhook ペイロードを確認することができます。

Eventbrite からの実際の JSON 応答を表示するジョブの詳細出力タブ

トリガーのテストおよび API 応答の取得によるデータツリーの生成

Webhook はほぼ完了していますが、レシピ内の後続のステップで使用するデータツリーを生成できるようにする必要があります。上記で入力した空のペイロードでは、後続のレシピステップでトリガーデータツリーは使用できません。ジョブレポートの詳細で取得した JSON 応答をペイロードの例のセクションに移動し、確実に JSON フォーマットになるように微調整しします。

Webhook ペイロードを定義することによる Workato データツリーの構築

代わりに、API ドキュメントから JSON を取得することもできます (存在する場合)。

Eventbrite の Webhook 管理コンソールから取得できる要求ペイロード

以下に、Webhook ペイロードの例のフィールドに入力される JSON 応答を示します。

JSON フォーマットの Webhook ペイロードの例 :

{
"config": {
"action":"order.placed",
"user_id":"144138753572",
"endpoint_url":"https://www.workato.com/webhooks/rest/4c364864-e1f8-4c58-b6af-29127d1f6b60/order",
"webhook_id":"287968"
},
"api_url":"https://www.eventbriteapi.com/v3/orders/579759447/"
}

完成した Webhook トリガー

以上です。これで Eventbrite Webhook トリガーを自分自身で作成できました。

この特定の Eventbrite ユースケースでは、このトリガーはユーザーに API の URL を渡し、行われた注文の実際のデータを取得するのみであることに注意してください。このデータを取得するには、この API URL の注文を GET する簡単な REST アクションを作成します。これはこのコース内で後ほど扱います。

設定された Webhook トリガー

この Webhook トリガーのデータツリーは次のように表示されます。これは、トリガー設定で指定されたサンプルの Webhook ペイロードにより生成されます。

Webhook データツリー

REST 要求アクションの構築

作成、更新、検索、取得、削除など、HTTP コネクター上の API でサポートされている任意のアクションを構築できます。次のスクリーンショットは、HTTP REST 要求アクションで使用できる入力フィールドを示しています。アクションの構築時に注意する主なフィールドについて見てみましょう。

REST アクションの入力フィールド

Request name

このアクションで実行することの説明に使用されます。このアクションで何を実行するのかがわかるように、ここにはわかりやすい名前を入力します。

Method

呼び出す特定の HTTP メソッド。一般に、API ドキュメントには、呼び出す API エンドポイントと関連付けられた HTTP メソッドが何であるかが記載されています。

Request URL

要求を送信する API エンドポイント。

Request body

その要求で送信される JSON フォーマットのデータ。これは一般に、作成および更新アクション (PUT、POST、PATCH メソッド) でのみ必要となります。作成または更新されるレコードのデータを提供する必要があるためです。

Response type

期待される API 応答のフォーマットを指定します。レシピの下流で使用するために応答をデータツリーに変換することを考えていない場合は、単に [Raw HTTP response body] のオプションを選択します。そうでない場合は、適宜 [JSON] または [XML] を選択します。

Response body example

これは、レシピ内で後で使用するために、データツリーに変換されます。上に示されている [Parse response as JSON] を選択した場合、期待されるスキーマを JSON フォーマットで入力する必要があります。[Parse response as XML] を選択した場合、期待されるスキーマを XML フォーマットで入力する必要があります。

例 - Eventbrite で注文の詳細の取得アクションを構築する

前に設定した Eventbrite の新しい注文の Webhook トリガーに続いて、行われた特定の注文について、注文の詳細を取得する (opens new window) API エンドポイントが用意できました。

HTTP アクションの設定

このアクションに関連する入力フィールドは以下のもののみです。API URL ピルを要求 URL の入力フィールドに渡し、特定の注文の詳細を取得するための呼び出しを行うことができます。応答本体の例は今のところ空白のままにできます。つまり、これまでのところ、このステップではデータツリーは生成されません。

データツリーを生成するためのオプションの応答本体の例が未記入の、部分的に設定された GET 要求

アクションのテスト

以前にトリガーを設定しなかった場合は、単にハードコーディングされた URL を要求 URL に渡し、特定の注文 ID 579759447を Eventbrite アカウントに存在する Eventbrite 注文の ID に置き換えることができます。

Eventbrite の注文の詳細の GET の API 呼び出し :

https://www.eventbriteapi.com/v3/orders/579759447/

以前に Webhook トリガーを設定し、いくつかのサンプルジョブを実行した場合は、単にジョブを再実行することができます。トリガーデータは Workato でキャッシュされるため、ジョブの再実行では、そのトリガーで受け取ったペイロードデータを再利用して、このGET アクションを実行するだけです。

トリガーからの API URL が要求 URL としてアクションに渡される

データツリーの生成のための API 応答の取得

ジョブレポートを見ると、応答を確認できます。本体のテキストは正確に JSON でフォーマットされているため、単にこれをコピーして、[Response body example] 入力フィールドに貼り付けるだけです (最初と最後の二重引用符は不要)。

ジョブレポートの出力タブに表示される Eventbrite の注文の GET の API 呼び出しに対する API 応答

Eventbrite の注文の GET の API 呼び出しに対する API 応答

{"costs": {"base_price": {"display": "$0.00", "currency": "USD", "value": 0, "major_value": "0.00"}, "eventbrite_fee": {"display": "$0.00", "currency": "USD", "value": 0, "major_value": "0.00"}, "gross": {"display": "$0.00", "currency": "USD", "value": 0, "major_value": "0.00"}, "payment_fee": {"display": "$0.00", "currency": "USD", "value": 0, "major_value": "0.00"}, "tax": {"display": "$0.00", "currency": "USD", "value": 0, "major_value": "0.00"}}, "resource_uri": "https://www.eventbriteapi.com/v3/orders/579759447/", "id": "579759447", "changed": "2016-12-16T00:40:47Z", "created": "2016-12-16T00:40:46Z", "name": "hl y", "first_name": "hl", "last_name": "y", "email": "[email protected]", "status": "placed", "time_remaining": null, "event_id": "30343163218"}

完了したアクション

以下に、アクションが最終的にどのように表示されるかを示します。

設定された GET アクション

設定された GET アクション

ステップ1指定された応答本体の例から生成された出力データツリー

例 - JIRA でのプロジェクトの作成アクションの構築

HTTP コネクターを介して JIRA で新しいプロジェクトを作成しましょう。参照する API エンドポイントはこちら (opens new window)です。

REST アクションの設定

必要な最小限の値セットでアクションを設定します。以下は、未設定の HTTP REST アクションを表しています。

未設定の HTTP REST アクション

要求名

Create project

HTTP メソッド

POST (API ドキュメントの指定どおり)

要求 URL

https://[subdomain here]/rest/api/[version number here]/project

要求本体

プロジェクトを作成するにはデータを提供する必要があるため、ここでは必須です。送信する要求は、以下を参照してください。

応答のタイプ

JSON。これが JIRA API で使用するフォーマットです。

応答本体の例

これも API ドキュメントから取得しています。提供する応答は、以下を参照してください。

要求および応答本体

要求本体については、実際の値を送信する必要があります。以下のように JSON 表現の要求本体を含めていますが、EX というキーと Example という名前でプロジェクトを作成したくなければ、レシピの前のステップのピルを含むハードコーディングされた値を置き換える必要があります。

新しい JIRA プロジェクトを作成するための要求本体。新しいプロジェクトを作成するための実際のデータをここに挿入する必要があります。

{
    "key": "EX",
    "name": "Example",
    "projectTypeKey": "business",
    "projectTemplateKey": "com.atlassian.jira-core-project-templates:jira-core-project-management",
    "description": "Example Project description",
    "lead": "admin",
    "assigneeType": "PROJECT_LEAD"
}

応答本体については、データツリーの生成に使用する JSON の例のみが必要であるため、API ドキュメントからの応答例を使用するだけでかまいません。

データツリーを生成するための応答本体の例。ここには任意のサンプルデータを使用できます。

{
    "self": "http://example/jira/rest/api/2/project/10042",
    "id": 10010,
    "key": "EX"
}

設定されたアクション

以下に、設定された現在のアクションを示します。

設定された JIRA プロジェクトの REST 要求

以下に、設定された GET アクションのデータツリーを示します。これは、 応答本体の例 から生成されています。

次のステップで表示される、応答本体の例から生成されたデータツリー

設定したアクションのテスト

これをテストするには、完全なレシピを用意して、このレシピをテストする必要があります。ここでは、アクションを迅速にテストできるスケジューラートリガー New scheduled event を使用します。

スケジューラートリガーと HTTP アクションを含む完成したレシピ

完成したレシピ (トリガーとアクションの両方を含む) で、[Test recipe] を選択しましょう。[Test recipe] により、以下に示すように、1つのサンプルジョブが実行されます。

[Test recipe] をクリックすることによる1つのサンプルジョブの実行

ジョブの詳細を調べるジョブを選択し、何が起きているのかを正確に確認します。成功したジョブがあれば、JIRA 内で作成したプロジェクトを確認できます。

ジョブの入力タブには、GET アクションに渡されたデータが示されます。

ジョブの入力タブに表示される、送信された API 要求

ジョブの出力タブには、API 応答として受信されたデータが示されます。

ジョブの出力タブに表示される、受信された API 要求