HTTP コネクションの設定

API を操作するには、まず、対象となるアプリへのコネクションを設定する必要があります。[Link your account] ボタンをクリックすると、コネクションのポップアップが表示されます。

HTTP コネクターのコネクションのポップアップ

正常に接続するには、以下の入力項目を設定します。認証タイプと、タイプを選択したときに生成される項目を除き、通常ほとんどの項目はデフォルト値のままで構いません。

入力項目	説明
Connection name	この HTTP コネクションを識別する名前を付けます。
Authentication type	アプリへの接続に使用する認証のタイプ。詳細については、接続するアプリの API ドキュメントを参照してください。
Base URL	このコネクションを使用するすべてのリクエストのベース URL を設定します。設定した URL をレシピで上書きすることはできません。HTTP のベース URL の詳細については、こちらを参照してください。
Use client SSL certificate	API でクライアント SSL 証明書を必要とする場合は [Yes]、必要としない場合は [No] を指定します。
Is this app in a private network?	ファイアウォールの内側にあるオンプレミスアプリに接続する場合は [Yes] を指定します。これには、Workato でオンプレミスエージェントを設定する必要があります。パブリッククラウド上のアプリに接続する場合は [No] を指定します。

認証タイプ

以降のセクションでは、さまざまな認証タイプとその設定方法について詳しく説明します。内容は以下のとおりです。

• None
• Basic
• Header auth
• Query params
• Custom
• OAuth2 (authorization code grant)
• OAuth2 (client credentials grant)
• AWS access key auth
• AWS IAM role auth

Workato で非 OAuth 2.0コネクションを設定するプロセスは、認証タイプに関係なく類似しています。これは、非 OAuth 2.0コネクションを設定した後、それが有効であることを確認するテストを行う必要があるためです。そのためには、テスト API リクエスト (簡単なものは GET リクエスト) を送信する必要があります。これに成功すれば、接続が有効であることがわかります。

この記事では、非 OAuth 2.0コネクションの例として基本認証と、OAuth2 の例を示します。

認証タイプ : None

認証情報を提供せずにコネクションを作成できます。これは通常、アプリから Webhook トリガーを受信するだけの場合に指定します。Workato は Webhook を送信する URL を生成し、送信された Webhook ペイロードから情報を取得します。

HTTP コネクターの認証タイプ : None

認証タイプ : Basic

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

例 - 基本認証で Jira に接続し、GET アクションでコネクションをテストする

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

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

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

Jira コネクションの設定

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

ユーザー名とパスワードは、コネクションの設定で以下のように指定できます。[Is the app in a private network] には、HTTP クライアントが OPA により保護されるかどうかを指定します。Jira はクラウド上にあるため、[No gateway] を選択します。

Jira コネクションの設定

[Connect] をクリックします。非 OAuth 2.0コネクションの場合は、正常にアプリに接続されていることを検証するため、GET リクエストなど簡単なテストリクエストを送信することを忘れないでください。

認証タイプ : Header auth

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

認証タイプ : Query params

認証構造がパラメータとしての API キーの検証に基づいているアプリケーションの場合に指定します。[params authorization] 項目にパラメータのキーと値のペアを追加する必要があります。 HTTP コネクターの認証タイプ : Query params

認証タイプ : Custom

必要に応じて入力項目を組み合わせて使用できます。 HTTP コネクターの認証タイプ : Custom

認証タイプ : OAuth 2.0 (authorization code grant)

OAuth2 は、多くのクラウドアプリで採用されている認証標準です。広く採用されている理由は、ユーザー名とパスワードを開示することなく第三者にアプリへのアクセスを許可できるためです。この場合、Workato はユーザーをアプリにリダイレクトするだけです。API リクエストを行う際に Workato がユーザーに代わって対応していることをアプリが信用するには、ここでログイン資格情報を入力すれば十分です。

認証コード付与タイプは、アクセストークンの認証コードを交換するために機密およびパブリックのクライアントによって使用されます。さらにこのタイプでは、次の情報を用意する必要があります。

入力項目	説明
Authorization URL	[Connect] ボタンをクリックしたときに Workato がユーザーをリダイレクトする URL。これにより、通常はアプリのログイン画面が表示されます。一部の API では、認証 URL に特定のパラメータを含める必要があります。一般的な例としては、response_type (code または token) や scope (read、write、admin など) があります。これは、接続するアプリの API ドキュメントの認証セクションで公開されているはずです。
Token URL	Workato が認証トークンを取得する URL。この認証トークンは、アプリとそのデータにアクセスする権限があることを確認するために使用されます。これは、接続するアプリの API ドキュメントの認証セクションで公開されているはずです。
Client ID and client secret	ユーザーは、クライアント ID によってこれらの API 呼び出しを送信しているユーザーとして識別され、クライアントシークレットによってこのユーザーとして認証されます。これは通常、接続するアプリのログインアカウントの [Settings] または [Integrations] (または同等) のページにあります。これはユーザーのアカウントに固有であり、秘密にしておく必要があります。

HTTP (OAuth2 authorization code grant) コネクターのコネクションの設定項目

認証タイプ : OAuth 2.0 (client credentials grant)

クライアント資格情報付与を使用すると、クライアントは、そのクライアント資格情報のみを使用してアクセストークンを要求できます。これは通常、クライアントがその制御下にある保護されたリソースへのアクセスを要求している場合、またはデータのアクセスに特定ユーザーの許可が不要な機器間 (M2M) 認証に使用されます。

クライアント資格情報付与タイプは、機密クライアントのみが使用する必要があります。

HTTP (OAuth2 client credentials grant) コネクターのコネクションの設定項目

OAuth2 認証タイプでは、以下の項目が必要です。

情報	説明
資格情報	アプリにログインするためのユーザー名とパスワードのセット。Workato がアプリ内のデータにアクセスする許可を与えます。この資格情報を持つユーザーには、アクセスするレコード (顧客レコード、売上請求書レコードなど) に対する適切な読み取り/書き込み権限が必要です。
リダイレクト/コールバック URL (アプリで設定)	認証フローを実行して資格情報/トークンを交換した後、Workato にリダイレクトするためにアプリに提供される URL。統合設定画面で要求された場合は、この URL https://www.workato.com/oauth/callback をアプリに提供します。

例 - OAuth2 で Eventbrite に接続する

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

Eventbrite の OAuth 2.0 [Authentication] ページ

ドキュメントの該当ページから、接続に必要な2つの項目である認証 URL とアクセストークン URL を取得できます。URL にさらにパラメータを付加する必要があります。Eventbrite のドキュメントには、URL https://www.eventbrite.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_KEY にポストする必要があると記載されています。

ただし、Workato がクライアントキーを処理するため、コネクション設定の入力項目には以下を指定する必要があります。

Eventbrite の認証 URL :

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

Eventbrite のアクセストークン 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 and OAuth Token] セクションを展開してクライアントシークレットを取得し、[App Extension] セクションに移動して、コールバック URL https://www.workato.com/oauth/callback を Eventbrite に入力します。

設定が完了した Eventbrite コネクション

認証タイプ : AWS access key auth

AWS アクセスキー認証では、AWS のルートユーザーまたは IAM ユーザーとして作成したアクセスキーを使用できます。1ユーザー (ルートユーザーまたは IAM ユーザー) には最大2つまでアクセスキーを割り当てることができます。それぞれのキーが無効になっている場合、それを使用することはできませんが、2つのアクセスキーという制限にはカウントされます。アクセスキーを削除すると永久に失われますが、新しいアクセスキーに置き換えることができます。詳細については、こちら (opens new window)を参照してください。

TIP

通常は、アクセスキー認証ではなく AWS IAM 認証を使用することをお勧めします。

HTTP (AWS Access key auth) コネクターのコネクションの設定項目

AWS アクセスキー認証タイプでは、以下の項目が必要です。

情報	説明
AWS Name	AWS サービスの名前。ドロップダウンから選択することも、独自の AWS サービス名を入力することもできます。ドロップダウンでサポートしているのは、すべての AWS サービスのサブセットのみです。AWS サービス名を入力する場合は、必ず API 内でのサービス名を使用してください。これは通常、AWS サービスの API エンドポイントの先頭に付加されています。
Region	リージョンは通常、アカウント URL で提供されます。アカウント URL が https://eu-west-1.console.s3.amazon.com (opens new window) であれば、リージョンとして eu-west-1 を使用します。
AWS access key ID	AWS アカウント名 > [マイセキュリティ資格情報] > [ユーザー] に移動します。既存のユーザーから API キーを取得するか、新しいユーザーを作成します。
Secret access key	AWS アカウント名 > [マイセキュリティ資格情報] > [ユーザー] に移動します。既存のユーザーからシークレットキーを取得するか、新しいユーザーを作成します。

認証タイプ : AWS IAM role auth

AWS IAM ロール認証では、AWS インスタンスで Workato が使用する専用のロールを指定できます。専用の IAM プロファイルをプロビジョニングすることによって、AWS インスタンスの所有者は、AWS セキュリティ資格情報を共有せずに、Workato に AWS リソースへのアクセス権を付与できます。特定の AWS サービスへのアクセス制御、サードパーティアプリケーション (Workato など) によって許可されるアクションなど、アクセス許可の境界の維持にも役立ちます。

必要なアクセス許可のみを付与し、可能なかぎり AllAccess ポリシーの使用を避けることをお勧めします。

TIP

通常は、アクセスキー認証ではなく AWS IAM 認証を使用することをお勧めします。

HTTP (AWS IAM role auth) コネクターのコネクションの設定項目

AWS IAM ロール認証タイプでは、以下の項目が必要です。

情報	説明
AWS Name	AWS サービスの名前。ドロップダウンから選択することも、独自の AWS サービス名を入力することもできます。ドロップダウンでサポートしているのは、すべての AWS サービスのサブセットのみです。AWS サービス名を入力する場合は、必ず API 内でのサービス名を使用してください。これは通常、AWS サービスの API エンドポイントの先頭に付加されています。
Region	リージョンは通常、アカウント URL で提供されます。アカウント URL が https://eu-west-1.console.s3.amazon.com (opens new window) であれば、リージョンとして eu-west-1 を使用します。
IAM role ARN	Amazon リソースネーム (ARN)。以下に、IAM ロールを作成して ARN を取得する方法を示します。

IAM ロール ARN を取得する方法

以下のステップに従って、コネクションの設定に必要な ロール ARN を取得します。コネクションのページにある Workato で生成された外部 ID を使用することを忘れないでください。

ステップ	説明
1.	AWS 上の IAM に移動し、新しいロールを作成します。[ロール] > [ロールの作成] を選択します。
2.	[別の AWS アカウント] を選択します。Workato の Amazon S3 アカウント ID (353360065216) を入力します。
3.	[外部 ID が必要] を選択し、Workato で生成された 外部 ID を指定します。 すべての Workato ユーザーには一意の 外部 ID (workato_iam_external_id_77630 など) があります。この値は、コネクションの設定の [IAM role ARN] の部分にあります。
4.	このロールにアクセス権限ポリシーをアタッチするよう求められます。ここでは、Workato の詳細なアクセス権限制御を指定できます。このロールにアタッチするポリシーは、できるだけ限定する必要があります。ここでは、このコネクションに AWSLambdaSQSQueueExecutionRole を提供して、SQS サービスへのメッセージを受信します。ほとんどの場合、ユースケースに基づいてのみスコープを付与する必要があります。
5. (任意)	オブジェクトのタグ付けを使用している場合は、この IAM ロールの適切なタグを選択します。
6.	この IAM ロールに適切な名前と説明を付与します。ロール名は、URN で推測できないリソース ID を使用することを避け、外部 ID を含めないことをお勧めします。
7.	これで IAM ロールが作成されました。作成したロールの概要ページにロール ARN が表示されます。
8.	このロール ARN を取得し、Workato のコネクションの設定項目に指定します。

HTTP の設定のドキュメント

トリガーとアクションの詳細については、次を参照してください。

• HTTP トリガーの作成
• HTTP アクションの作成