システム連携ネタでよくブログを書いている日下です。

Questetra から HTTP リクエストを送付することで、他サービスの REST API を呼び出す(API をたたく)、というシステム連携はよくあるケースの1つです。

その場合には Questetra 側では

のいずれかを使って HTTP リクエストを送付します。

そして、その際の認証として OAuth2 を使うことが多いです。
OAuth2 にはいくつか種類があるのですが、grant-type として Authorization code を使う場合、Questetra 側は設定だけで対応ができます。

今回はその OAuth2 の設定方法についてまとめます。

※「サービスタスク定義(Addon-XML)」は、HTTP リクエストを送るものではなく、データを変換するだけのものもあります。また、認証方法として OAuth 以外の手段を使うものもあります。
※OAuth2 の他の grant-type の場合には設定だけで対応できませんが、スクリプトタスクを使うことで対応できるケースがあります。grant-type が client_credentials や password のケースについては以下の記事で対応例があります。
関連記事:最近話題の「マストドン(Mastodon)」や Twitter の API をクラウドワークフローからたたいてみる

 

目次
1: おおまかな流れ
2: 呼び出される相手サービス側での準備
3: 呼び出す側(Questetra)の設定
4: API を呼び出すための Questetra 設定
5: まとめ

 

1: おおまかな流れ

設定のおおまかな流れとしては以下となります。

  • 呼び出される相手サービス側での準備
    Questetra のコールバックURLを使って設定、クライアント ID とシークレットを取得
  • 呼び出す側(Questetra)の設定
    相手サービスのエンドポイント URL と取得したクライアント ID とシークレットを使って設定、トークンを取得
  • API を呼び出すための Questetra 側の設定
    取得した OAuth トークンを使って設定

 

2: 呼び出される相手サービス側での準備

呼び出される相手サービス側では、クライアントの事前登録が必要となります。(「アプリ登録」等と呼ばれたりすることもあり)

その際に Questetra の「コールバック URL」(「リダイレクト URI」と呼ばれることもあり)が必要となります。

  • 有償契約環境の場合
     → https://s.questetra.net/oauth2callback
  • 無償環境(スタータープラン)の場合
     → https://f.questetra.net/oauth2callback
※かなり以前に構築された無償環境の場合、https://fs.questetra.net/oauth2callback となるものもあります。後述の OAuth 設定画面から確認できます。

登録完了すると、「クライアントID」/「クライアントシークレット」(「コンシューマ鍵」「APP ID」等/「クライアント機密コード」「コンシューマの秘密」等と呼ばれることもあり)が表示されるのでメモしておきます。

 

3: 呼び出す側(Questetra)の設定

まず OAuth 設定画面を以下のいずれかから表示します。(どちらから表示しても同じ画面が表示されます)

  • ワークフローアプリの詳細画面の「▼アプリ」ボタンメニューの「OAuth2.0 設定」
  • 「メッセージ送信中間イベント(HTTP)」のプロパティの「セキュリティ/カスタムヘッダ」の「OAuth2.0 で接続する」の「設定はこちらから」ボタン

「追加」ボタンを押して詳細設定画面を開きます。(「コールバック URL」はこの画面の下部で確認できます)

各項目を入力して「保存」ボタンを押します。

名称
名前 (好きな設定名で OK、後で指定する際に使います)
認可エンドポイントURL、トークンエンドポイントURL 相手サービス側のマニュアルを参照して入力します
スコープ 相手サービスや呼び出す API によって変わります、指定なしの場合もある、複数指定の場合は半角スペースで区切ります
クライアントID、クライアントシークレット 前述の相手サービスでの登録時にメモしたものを入力します

設定を保存したら「トークンの取得」ボタンを押下して、正常にトークンが取得できれば OK です。取得できると以下のような表示となります。
もし、ここでエラーになった場合は、設定不備がないかをご確認ください。設定を十分に確認しても不備が見当たらない場合には、そもそも Questetra が対応できていないケースの可能性もありますので、お問い合わせください。(現時点の仕様ではエラー詳細が表示されないこともありますので)

※過去の記事で、相手サービスを特定して OAuth2 の設定方法を記載したものがいくつかあります。参考にしてください。

ちなみに Google 側の設定は Sheets だけでなく、いろいろな API について対応するためのまとまったコンソールになっていて、少しややこしいです。ご注意ください。

また、Questetra 自身が API を呼び出される側になることもできます。詳しくは以下のマニュアルをご覧ください。
関連マニュアル:M317: 外部からの OAuth2 認可アクセスや Basic 認証アクセスを制御する
つまり OAuth を使って、Questetra から Questetra 自身の API を呼び出すこともできます。

※エンドポイント URL は相手サービスの側のバージョンアップ等で変わるケースがあるので注意してください。
現状(Ver.11.8.2 時点)、Questetra の OAuth 詳細設定画面の上部のプルダウンで Google と Force.com についてはエンドポイント URL が自動挿入されるようになっているのですが、現在 Google の方は新しい URL に変わっているようです(古い URL であっても問題なく動きます。また現時点で古い URL の停止予定も未定のようです)

  • 認証エンドポイント URL
    https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force
    → https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&approval_prompt=force
  • トークンエンドポイント URL
    https://accounts.google.com/o/oauth2/token
    → https://www.googleapis.com/oauth2/v4/token

関連記事:Google oAuth 2.0 new authorization and token endpoint (stack overflow)

 

4: API を呼び出すための Questetra 設定

上記で設定した OAuth トークンはそれぞれ以下のように指定して利用します。

  • 「メッセージ送信中間イベント(HTTP)」
    「セキュリティ/カスタムヘッダ」「OAuth2で接続する」で指定します。
  • 「スクリプトタスク」
    以下のようにして利用できます。(マニュアルを確認しつつ、公開されているサービスタスク定義(Addon-XML)のソースを参考にしてもらうといいかと)

    var token = httpClient.getOAuth2Token( XXX_OAuth設定名_XXX )
    httpClient.begin().bearer(token)
  • 「サービスタスク定義(Addon-XML)」
    「OAuth2通信許可設定名」等で指定します。(項目名はサービスタスク定義(Addon-XML)の仕様によりますので一例です)
※OAuth 設定はワークフローアプリごとに必要です。
もしワークフローアプリをコピーした場合、新たに作成されたワークフローアプリでも設定が必要になるので注意してください。ただコールバック URL は同じですので、クライアント ID やシークレットを使い回すこともできます。それで問題ないケースかどうかはご自身で判断してください。

 

5: まとめ

OAuth2 設定方法についてご理解いただけたかと思います。
少し難しい部分もありますが、様々なサービスと接続するために必要となる設定です。ぜひうまく使いこなしてください。

もし、ご質問等がありましたら、お問い合わせフォームからお気軽にご連絡ください。