HTTP connector V1
HTTP connectorを使用すると、HTTPベースのAPIを持つ任意のクラウドアプリケーションと連携できます。 新しいconnectorを作成したり、既存のWorkato connectorに新しいトリガーまたはアクションを追加したりできます。
非推奨に関する注意
2018年7月時点で、HTTP connectorのV2バージョンがリリースされています。 既存のV1 HTTP connector、HTTP(OAuth2)connector、およびHTTPアクションは非推奨になりました。
このドキュメントは非推奨のconnector向けです。 現在のconnectorドキュメントについては、HTTP connector V2を参照してください。
HTTP connectorには2種類あります:
- 標準認証とそのバリエーション
- OAuth 2
HTTPとHTTP(OAuth2)connectorの違い
コネクションの認証フローを除き、両方のconnectorの機能は同じです。 Webhookトリガー、ポーリングトリガー、RESTアクションの設定プロセスは同一です。
非OAuth 2.0コネクションでは、コネクションが有効であることを確認するために追加のテストAPIリクエストが必要です。
HTTP connectorとは何か、何に役立つのか。
汎用HTTPおよびHTTP(OAUTH2)connectorを使用すると、すべての(ほぼすべての) アプリケーションプログラムインターフェイス(略してAPI)を持つクラウドアプリケーションと通信できます。 つまり、標準で提供されるWorkato製connector以外でも、連携レシピを強化するために必要なトリガーまたはアクションを自由に作成できます。
HTTP connectorを使用すると、Workato上で独自のトリガーまたはアクションを20分未満で作成できます。 このコースでは、次の内容を説明します:
アプリへのコネクション(Oauth2および非OAuth2)の設定方法
アプリで何かが発生したときに通知を受け取る独自のWorkatoトリガーを作成する方法
アプリ内の特定のステップを自動的に実行する独自のWorkatoアクションを作成する方法
会計システムで請求書を作成したいですか。 JSONリクエスト本文を使用してPOSTリクエストを行います。 分析アプリケーションからメトリクスを取得したいですか。 クエリパラメータを使用してGETリクエストを行います。 新しいリードがオンラインフォームに入力したときにトリガーしたいですか。 新しいリードがフォームを完了するたびにWorkatoへ即時に通知するWebhookトリガーを作成します。 開始にあたってサポートが必要ですか。 このまま読み進めるか、Customer Success superheroesのいずれかにチャットしてください :)
OAuth 2.0コネクションの設定
HTTP(OAuth2)connectorは、OAuth 2.0標準の認可コードグラントバリアントをサポートしています。これは、多くのクラウドアプリで採用されている現在の事実上の認証標準です。 これは、ユーザー名とパスワードを第三者に開示せずに、第三者へアプリへのアクセス権を付与できるため広く採用されています。 この場合、Workatoはユーザーをアプリにリダイレクトするだけです。そこでログイン資格情報を入力すれば、アプリはWorkatoがユーザーに代わってAPIリクエストを行うことを信頼できます。
HTTP(OAuth2)connectorのコネクションフィールド
OAuth 2.0コネクションの関連コンポーネント
認可URL
「Connect」ボタンを選択したときにWorkatoがリダイレクトするURL。 通常、これによりアプリのログイン画面が表示されます。
一部のAPIでは、認可URLに特定のパラメータを含める必要があります。 一般的な例として、response_type(codeまたはtoken)やscope(read、write、adminなど)があります。
これは通常、接続先アプリのAPIドキュメントのAuthenticationセクションで公開されています。
トークンURL
Workatoが認証トークンを取得するURL。 この認証トークンは、アプリとそのデータにアクセスする権限があることを確認するために使用されます。
これは通常、接続先アプリのAPIドキュメントのAuthenticationセクションで公開されています。
クライアントIDとクライアントシークレット
クライアントIDはこれらのAPI呼び出しを送信しているユーザーとしてユーザーを識別し、クライアントシークレットはそのユーザーであることを認証します。
これは通常、接続したいログイン済みアプリアカウントのSettingsまたはIntegrationsページ(または同等の場所)にあります。 これはアカウント固有の情報であり、秘密にしておく必要があります。
資格情報
Workatoがアプリ内のデータにアクセスする権限を付与するために、アプリへのログインに使用するユーザー名とパスワードのセット。
このユーザー(資格情報の所有者)は、アクセスしたいレコード(例: 顧客レコード、売上請求書レコード)を読み書きするための適切な権限を持っている必要があります。
リダイレクト/コールバックURL(アプリで設定)
認証フローと資格情報/トークン交換を経た後にWorkatoへリダイレクトするため、アプリに提供されるURL。
Integrationセットアップ画面で求められた場合は、このURLhttps://www.workato.com/oauth/callbackをアプリに提供します。
例: OAuth2を介したEventbriteへの接続
OAuth 2.0アプリケーションに接続する方法の例を見ていきましょう。 この場合は、イベント管理およびチケット販売アプリケーションであるEventbriteを使用します。
Eventbrite OAuth 2.0認証ページ
ドキュメントページから、コネクションに必要なフィールドのうち2つ、authorize URLとaccess token URLを取得できます。 URLに追加のパラメータを付加する必要があります。 Eventbriteのドキュメントには、このURLにpostする必要があると記載されています: 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=codeEventbriteアクセストークンURL:
https://www.eventbrite.com/oauth/tokenEventbriteアカウントに正常に接続するには、クライアントIDとクライアントシークレットのセットも必要です。 これを取得するには、Eventbriteにアプリを登録し、アプリにクライアントIDとシークレットを割り当ててもらう必要があります。 Eventbriteにログインし、Account Settings > App Managementに移動します。
Eventbriteのアプリ管理画面
アプリ管理ページで、クライアントID(keyとも呼ばれます)を確認できます。 Show Client Secret and OAuth Tokenセクションを展開してクライアントシークレットを取得し、App Extensionセクションに移動してコールバックURLhttps://www.workato.com/oauth/callbackをEventbriteに入力します。
完了したEventbriteコネクション
非OAuth 2.0コネクションの設定
非OAuth 2.0コネクションの確立は、OAuth 2.0コネクションの確立よりも少し複雑です。連携しようとしているアプリケーション固有の認証タイプを選択する必要があります。 このセグメントでは、利用可能なさまざまなオプションを説明します。
なし
これにより、認証の詳細を提供せずにコネクションを作成できます。 通常、これはアプリからWebhookトリガーを受信するだけの場合に該当します。 WorkatoはWebhookの送信先となるURLを生成し、送信されたWebhookペイロードから情報を取得します。
HTTP connector認証タイプ: None
Basic
これにはユーザー名とパスワードが必要です。 ユーザー名とパスワードの代替として、アカウント設定から取得したAPIキーまたはAPIトークンを使用できます。 これはSSL上の転送中にBase64でエンコードされます。 これは一般的な認証フローです。
HTTP connector認証タイプ: Basic
Header Auth
通常のユーザー名とパスワードまたはAPIキー以外に追加ヘッダーが必要なアプリケーションや、リクエストで送信するヘッダーをカスタマイズしたい場合に使用します。 生成済みのトークンを使用できる状態にしている場合、ヘッダー認証を使用できます。
HTTP connector認証タイプ: Header authorization
クエリパラメーター
認証構造がパラメータとしてAPIキーを検証することに基づくアプリケーション向けです。 必要なのは、params認可フィールドにパラメータのキー/値ペアを追加することです。
HTTP connector認証タイプ: Query params
Custom
Customを使用すると、上記のいずれかのフィールドを組み合わせて使用できます。
HTTP connector認証タイプ: Custom
非OAuth 2.0コネクションのテスト
接続後、非OAuth 2.0コネクションが有効であることを確認するためにテストする必要があります。 そのためには、テストAPIリクエストを送信します。単純な例としてGETリクエストがあります。 成功すれば、コネクションが有効であることがわかります。
例: 基本認証を介したJIRAへの接続とGETアクションによるコネクションのテスト
基本認証を使用してJIRAに接続してみましょう。 JIRAの場合、サブドメイン(接続先のJIRA会社インスタンス、つまり会社のJIRAデータベースを示します)、ユーザー名、パスワードなど、いくつかの情報を提供する必要があります。 詳細については、AtlassianのJira REST API basic authenticationドキュメントを参照してください。
この例では、会社名Workato321でJIRAに会社インスタンスを作成しました。JIRAによってサブドメインがworkato321.atlassian.netとして自動的に割り当てられています。
また、新しいJIRAインスタンスにPPPという名前のプロジェクトを作成しました。これは後でコネクションをテストするために使用します。
JIRAコネクションの設定
サブドメインworkato321.atlassian.netと既存プロジェクトPPPを含むJIRAスクリーンショット
以下のように、コネクション設定でユーザー名とパスワードを提供できます。 On-prem secure agentフィールドでは、JIRAインスタンスがクラウド上にあるためno gatewayを選択しました。
JIRAコネクション設定
GETアクションを実行してJIRAコネクションをテスト
まだ完了していません。 コネクションをテストしましょう。 JIRAの場合、インスタンス(サブドメイン)情報をAPIエンドポイント内で送信する必要があるため、コネクション設定で提供する必要はありません。
コネクションをテストするために、このGET all projectsエンドポイントhttps://workato321.atlassian.net/rest/api/2/projectを使用して、JIRAインスタンス内のすべてのプロジェクトを取得するようWorkatoに指示します。
私のテストレシピは次のようになります。Schedulerトリガー(New scheduled event)があり、run recipeを選択するとジョブが即時に実行され、単にAPIエンドポイントを呼び出します。 これは単なる簡単なテストであり、後続のステップで使用するデータツリーの構築にはまだ実際には関心がないため、サンプル応答本文には入力していません。
JIRAプロジェクトのリストを取得する設定済みHTTPアクション
次にレシピを実行し、実行されたジョブを選択します。 inputタブで、HTTP connectorによって送信された内容を確認できます。
ジョブ詳細のinputタブから表示した、送信済みAPIリクエスト
APIエンドポイントとユーザー名およびパスワードが正しい場合、outputタブで返されたデータを確認できます。この場合はPPPプロジェクトです。
ジョブ詳細のoutputタブから表示した、JIRAから受信したAPIレスポンス
Webhookトリガーの作成
連携したいアプリがWebhookをサポートしている場合、それはアプリのAPIドキュメントに記載されているはずです。 Webhookは、イベントが発生したときにアプリからターゲットURLへ即時に送信される通知です。 通常、どの特定のイベントについて通知を受け取りたいかを定義できます。 WorkatoでWebhookトリガーを作成するには、これらの通知をWorkatoレシピに送信します。これにより、アプリでイベントが発生するたびにトリガーされ、レシピアクションが実行されます。
たとえば、新しいカスタマーチケットのステータスが「Urgent」とマークされたときにレシピへ通知するWebhookトリガーを作成し、この顧客のアカウントマネージャーへSMSを送信するアクションを用意できます。 この場合、レシピにより緊急チケットへのタイムリーな対応を確保できます。
アプリケーションからWebhookを受信することだけに関心がある場合、コネクションを設定したり認証フローを実行したりする必要はありません。 HTTPコネクションを設定するときは、認証タイプとしてNoneを選択します。
これらはWorkatoのWebhookトリガーの入力フィールドです。 Webhookトリガーを作成する際に注意すべき主要フィールドを見ていきましょう。
HTTP connectorのWebhookトリガー
Workato生成ターゲットURL
アプリで生成されたWebhookの送信先となるURLアドレス。 このURLで生成される36文字の文字列はアカウント固有であるため、安全に保管してください。そうしないと、インターネット上の誰でもランダムなデータを送信できてしまいます。
デフォルトでは、このURLは未完成です。 ターゲットURLとして使用する完全なURLを生成するには、イベント名を指定します。
イベント名
このトリガーで行っていることを説明するために使用します。 どの特定のイベントについて通知を受信しているかを覚えておけるよう、ここにわかりやすい名前を入力します。
イベント名はWorkato生成URLの末尾に追加され、このレシピに固有のURLを生成します。
Webhookタイプ
想定するWebhookのタイプと受信データの形式をレシピに伝え、ペイロードを解読して処理できるようにします。 これはAPIドキュメントで提供される仕様によって異なります。
一部のAPIでは、さまざまな形式でWebhookペイロードを送信できる場合があります。その場合は、扱いやすいものを選択し、Webhook payload example入力フィールドに正しい形式でペイロードを提供してください。
Webhookペイロード例
アプリからWorkatoに送信されることが想定されるWebhookペイロードのサンプルを提供します。 通常はAPIドキュメントにあります。事前に定義した適切なJSON、XML、またはフォームエンコード形式でコピーして貼り付けるだけです。 アプリから送信されるカスタム値があることがわかっている場合は、正しい形式で追加フィールドをこれに追加することもできます。
提供されたこのペイロード例は、トリガーイベントが発生したときにWorkatoへ送信される実際のペイロードには影響しません。 代わりに、このサンプルスキーマは出力データツリーとそのデータピルを構築するために使用されます。これにより、Webhookで受信したデータをデータツリー内の後続ステップへ適切にマッピングできます。
設定済みWebhookトリガーの例
トリガーデータスキーマは、設定で提供されたWebhookペイロード例に対応します
例: Eventbriteで新規注文トリガーを作成
この例では、Eventbriteで「Christmas Marathon」というイベントに新しい注文が行われるたびにトリガーされるリアルタイムWebhookトリガーの作成手順を説明します。 必要な情報はEventbriteのWebhookドキュメントで確認できます。
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レスポンスを表示するジョブ詳細outputタブ
トリガーのテストとデータツリー生成用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 connectorでは、APIでサポートされている任意のアクションを作成できます。たとえば、create、update、search、get、deleteアクションです。 次のスクリーンショットは、HTTP RESTリクエストアクションで利用可能な入力フィールドを示しています。 アクションを作成する際に注意すべき主要フィールドを見ていきましょう。

RESTアクションの入力フィールド
リクエスト名
これは、このアクションで行っていることを説明するために使用します。 このアクションが実行する内容を覚えておけるよう、ここにわかりやすい名前を入力します。
メソッド
呼び出す特定のHTTPメソッド。 APIドキュメントには通常、呼び出したいAPIエンドポイントに関連付けられたHTTPメソッドが記載されています。
リクエストURL
リクエストの送信先となるAPIエンドポイント。
リクエスト本文
リクエストとともに送信するデータ(JSON形式)。 これは通常、作成または更新アクション(PUT、POST、またはPATCHメソッド)でのみ必要です。作成または更新するレコードのデータを提供する必要があるためです。
レスポンスタイプ
これは、想定されるAPIレスポンスの形式を指定します。 レスポンスをレシピ内の後続の下流処理で使用するデータツリーに変換する必要がない場合は、「Raw HTTP response body」オプションを選択します。 それ以外の場合は、必要に応じてJSONまたはXMLを選択します。
レスポンス本文例
これはレシピ内の後続使用のためにデータツリーに変換されます。 上で「Parse response as JSON」を選択した場合は、想定されるスキーマをJSON形式で入力する必要があります。 上で「Parse response as XML」を選択した場合は、想定されるスキーマをXML形式で入力する必要があります。
例: Eventbriteで注文詳細取得アクションを作成
以前に設定したEventbriteの新規注文Webhookトリガーに続き、配置されたばかりの特定の注文の注文詳細を取得するためのAPIエンドポイントができました。
HTTPアクションの設定
このアクションに関連する入力フィールドは次のものだけです。 特定の注文詳細を取得する呼び出しを行うため、API URLピルをリクエストURL入力フィールドに渡すことができます。 レスポンス本文例は今のところ空のままにできます。つまり、このステップではまだデータツリーは生成されません。
データツリー生成用の任意のレスポンス本文例が不足している、部分的に設定されたGETリクエスト
アクションのテスト
以前にトリガーを設定していない場合は、特定の注文ID 579759447をEventbriteアカウントに存在するEventbrite注文のIDに置き換えて、ハードコードされたURLをリクエストURLに渡すだけでかまいません。
EventbriteのGET注文詳細API呼び出し:
https://www.eventbriteapi.com/v3/orders/579759447/または、以前にWebhookトリガーを設定し、いくつかのサンプルジョブを実行している場合は、ジョブを再実行するだけでかまいません。 トリガーデータはWorkatoにキャッシュされているため、ジョブを再実行すると、トリガーで受信済みのペイロードデータを再利用してこのGETアクションを実行します。
トリガーからのAPI URLがリクエストURLとしてアクションに渡されます
データツリーを生成するためのAPIレスポンスの取得
ジョブ履歴を見ると、レスポンスを表示できます。 本文内のテキストはJSONとして正確に形式設定されているため、必要に応じてそれをコピーし、Response body example入力フィールドに貼り付けることができます(最初と最後の二重引用符は除きます)。
ジョブ履歴のoutputタブで表示した、EventbriteのGET order API呼び出しに対するAPIレスポンス
EventbriteのGET order 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アクション
提供されたレスポンス本文例から生成されたStep 1出力データツリー
例: JIRAでプロジェクト作成アクションを作成
HTTP connectorを介してJIRAに新しいプロジェクトを作成しましょう。 APIエンドポイントの詳細については、AtlassianのCreate project APIドキュメントを参照してください。
RESTアクションの設定
必要最小限の値セットでアクションを設定します。 以下は、未設定のHTTP RESTアクションを示しています。

未設定のHTTP RESTアクション
リクエスト名
プロジェクトを作成します。
HTTPメソッド
APIドキュメントで指定されているとおり、POSTです。
リクエストURL
https://[subdomain here]/rest/api/[version number here]/project
リクエスト本文
この場合は、プロジェクトを作成するためのデータを提供する必要があるため必須です。 送信するリクエストについては以下を参照してください。
レスポンスタイプ
JIRA APIが使用する形式であるため、JSONです。
レスポンス本文例
これもAPIドキュメントから取得しています。 提供するレスポンスについては以下を参照してください。
リクエスト本文とレスポンス本文
リクエスト本文には、実際の値を送信する必要があります。 以下のようにリクエスト本文のJSON表現を含めていますが、keyがEXでnameが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リクエスト
以下は、Response body exampleから生成された、設定済みGETアクションのデータツリーを示しています。
次のステップから表示した、レスポンス本文例から生成されたデータツリー
設定済みアクションのテスト
これをテストするには、完全なレシピを用意し、レシピをテストする必要があります。 ここではSchedulerトリガー「New scheduled event」を使用しています。これにより、アクションをすばやくテストできるためです。
SchedulerトリガーとHTTPアクションを含む完成したレシピ
完成したレシピ(トリガーとアクションの両方を含む)で、「Test recipe」を選択しましょう。 Test recipeは、以下のように単一のサンプルジョブを実行します。
「Test Recipe」をクリックして1つのサンプルジョブを実行
ジョブを選択してジョブの詳細を確認し、何が正確に起こったかを確認します。 ジョブが成功した場合、JIRAでプロジェクトが作成されたことを確認できます。
ジョブinputタブには、GETアクションに渡されたデータが表示されます。
ジョブinputタブから表示した、送信済みAPIリクエスト
ジョブoutputタブには、APIレスポンスとして受信したデータが表示されます。
ジョブoutputタブから表示した、受信済みAPIリクエスト
Last updated: