概要
こちらのガイドラインでは、BizRobo!で OAuth認証を使用して Management Consoleで接続できるアプリケーションのAPIを経由して、データのアクセスロボットの開発から実行までを案内します。
OAuth は、Twitter および Facebook など人気のある多くの API で使用されている認証のオープン標準です。ユーザーのログイン資格情報（IDとパスワード）を使用せずに、ユーザーの代わりにアプリケーションに対してロボットがアクションを実行できる手段となります。
Management Console(MC)で生成されたアクセス トークンはMC のキーストアに安全に格納されます。アクセス トークンは、スケジュールにおけるロボットやKappletsの入力として渡すことができます。通常通り、実際の API 呼び出しを行い、返されたデータを処理するロボットは Design Studio に作成されます。
作業手順
今回の例は 11.4.0.2で紹介します。
| 目次 | セクション |
| 1. サポートされているアプリケーションのサービス プロバイダ | |
| 2. OAuthアプリケーションとユーザーの追加 | |
| 3. ロボットの作成 | |
| 4. MCスケジュールやKappletsで実行する場合 | |
| 5. アウト オブ バウンド アプリケーション (Out-of-band もしくは OOB) |
1. サポートされているアプリケーションのサービス プロバイダ
| Type / Ver | 10.4 | 10.7 | 11.1 | 11.3 | 11.4 |
| Dropbox | 〇 | 〇 | 〇 | 〇 | 〇 |
| 〇 | 〇 | 〇 | 〇 | 〇 | |
| 〇 | 〇 | 〇 | 〇 | 〇 | |
| 〇 | 〇 | 〇 | 〇 | 〇 | |
| Salesforce | 〇 | 〇 | 〇 | 〇 | 〇 |
| 〇 | 〇 | 〇 | 〇 | 〇 | |
| Microsoft Azure AD 2.0 | ✖ | 〇 | 〇 | 〇 | 〇 |
| Kintone | ✖ | ✖ | ✖ | ✖ |
△※ |
※ 11.4では kintoneのドメインのみ適用できます。 cybozuのドメインはまだ実装されておりません。
OK → https://{テナント}.kintone.com
未実装 → https://{テナント}.cybozu.com
2. OAuthアプリケーションとユーザーの追加
サービス プロバイダーの API にアクセスするには、MCにてそのサービス プロバイダーでアプリケーションを作成する必要があります。アプリケーションを作成すると、コンシューマー キー (API キーまたはアプリケーション キーとしても知られる) およびコンシューマー シークレット (API シークレットまたはアプリケーション シークレットとしても知られる) が生成されます。
アプリケーションの作成は該当サービスプロバイダでOAuth認証系のアプリケーションとMCのアプリケーションの作成が必要となります。MCで OAuthアプリケーションを作成した後に、OAuthユーザーを追加します。
詳細の手順は以下の(※)注意点を確認してから、Microsoft OutlookのメールAPIをアクセスする例をご参照ください。
|
※ セクション１の⑧のコンシューマシークレットをメモしてください。ロボットをDesign Studioで作成する時に利用します。 ※ 上記のナレッジのセクション２の④と⑤はメールトリガロボットの操作のための権限設定の例となります。関連する権限を設定ください。今回の例では「offline_access Mail.ReadBasic Mail.Read Mail.ReadWrite」の４つの権限を設定します。そして、セクション3の②の(7)でスコープを「offline_access Mail.ReadBasic Mail.Read Mail.ReadWrite」で設定します。 ※ 上記のナレッジのセクション4の⑦アクセストークン情報まで設定できたらこちらの設定は完了です。 「tenantId」「アクセストークン」と「リフレッシュトークン (トークンを更新）」をメモしてください。ロボットをDesign Studioで作成する時に利用します。 |
3. ロボットの作成
以下の手順では、認証メカニズムとして OAuth を使用する REST API にアクセスするロボットを書き込みます。今回は、Microsoft Graphs REST API を使用して、メールの情報を取得します。
Design Studio を開始し、ベーシックエンジンロボットを新規作成します。
ウィザードには、URL を入力しないでください。認証するまでは、REST API にアクセスすることはできません。
まずは「OAuthCredentials」タイプの変数を作成します。(パラメータとして使用のチェックをONにしてください。)
変数の名前は任意のものを設定してください。今回は例として「azureOauthCre」
・serviceProviderは 1. サポートされているアプリケーションのサービス プロバイダで羅列されたプロバイダ名をご指定ください。今回の例では「Microsoft Azure AD 2.0」を利用します。
・accessTokenは2.OAuthアプリケーションとユーザーの追加でメモしたアクセストークンを指定します。
・accessTokenSecretは特にプロバイダーシステムから情報がなければ入力する必要はありません。
・refreshTokenは2.OAuthアプリケーションとユーザーの追加でメモしたリフレッシュトークン(トークンを更新)を指定します。
・consumerKeyは2.OAuthアプリケーションとユーザーの追加で作成した OAuthアプリケーションのコンシューマーキーを指定します。
・consumerSecretは2.OAuthアプリケーションとユーザーの追加でメモしたコンシューマーシークレットを指定します
・tenantIdはある場合指定します。今回のMicrosoft Azure AD 2.0は2.OAuthアプリケーションとユーザーの追加でユーザーを追加する時に設定した tenantIdを指定します。
今回利用するAPIは以下エンドポイントとなります。（メールの送信元の情報とメッセージ件名）
https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject
利用するステップは「Load Page (ページ読込)」もしくは「Call REST Web Service（REST Webサービス呼出)」になります。
■ 3.1) 「Load Page (ページ読込)」を利用する場合以下の設定を行います。
3.1.1) ステップのURL箇所に上記のAPIのエンドポイントを指定します。
3.1.2) ステップのオプションの設定から、「すべてのローディング」タブにて：
クレデンシャルを「OAuth」に設定します
変数をはじめ定義した「azureOauthCre」を選択します。
3.1.3) ステップを実行すると、Outlookの受信トレイの10個のメールがJSON形式で表示します。
■ 3.2) 「Call REST Web Service（REST Webサービス呼出)」を利用する場合以下の設定を行います。
3.2.1) ステップのURL箇所に上記のAPIのエンドポイントのパラメータ指定の前の部分まで指定します。
https://graph.microsoft.com/v1.0/me/messages
3.2.2) ステップのパラメータに以下を追加します。
パラメータ名：$select
値 ：sender,subject
3.2.3) ステップのアクションの下部にある「オプション」の「クレデンシャル」を「OAuth」に変更し、変数の所を「azureOauthCre」変数に設定します。
これでステップの実行ができます。実行結果は上記の「Load Page (ページ読込)」と同様です。
4. MCスケジュールやKappletsで実行する場合
MCスケジュールは以下のようにロボットの「入力値を設定」でOAuthユーザーを選択します。
Kappletsのテンプレートの設定については以下の手順を従ってください。
v11.4 の Kapplet 入力変数としての OAuth クレデンシャルの廃止の影響によりご利用のバージョンに応じて以下の二つのパターンに分けられます。
11.3以前のケース、OAuthCredentials情報を再度入力します。
ただし、tenantIdが設定できませんですので、SaasアプリのOAuth認証にtenantIdが求められるとKappletで運用する場合、11.4以降のバージョンをご利用ください。
11.4以降の場合、ロボットの入力値にてOAuthユーザーを選びます。
もしくはKapplet実行の際に、OAuthユーザーの再指定もできます。
5. アウト オブ バウンド アプリケーション (Out-of-band もしくは OOB)
一部のサービス プロバイダーは、コールバックを使用せずに OAuth アプリケーションを認証するためのメカニズムを提供しています。こちらのメカニズムはアウトオブバンドになります。Management Consoleはアウトオブバンド認証をサポートしています。アウトオブバンド認証タイプのOAuthアプリケーションを登録するためには、コールバック URL フィールドを空白のままにする必要があります。
SalesforceとTwitterはこちらのメカニズムを提供しています。
詳細な案内はこちらをURLご参照ください。
注意事項
バージョン 11.4からは「OAuth入力は選択式 」の仕様になりました。