watsonx OrchestrateからMicrosoft Graph APIを呼んでみる

watsonx OrchestrateはIBMのAiAssitant構築のためのプラットフォームです。ユーザーはチャットにやりたいことを入力することで様々な「スキル」を呼び出すことが可能です。製品にはあらかじめ1500以上のスキルが付属し、カタログから選択することですぐに利用が可能です。
また、製品に付属しないスキルについては、OpenAPI定義を読み込むことでスキルとして取り込むことが可能です。この記事ではMicrosoftのGraphAPIを例に、スキルの取り込み方法について解説します。

アプリケーションの定義

まず、watsonx OrchestrateがMicrosoftのアカウントに接続できるように、Microsoftのアカウント側にアプリケーションを定義する必要があります。
Entra管理センターにアクセスし、アプリケーション＞アプリの登録からアプリケーションを登録します。

リダイレクトURIとしては、以下の値を設定します。（環境によって異なる可能性があります。）
https://dl.watson-orchestrate.ibm.com/mfe_connectors/api/v1/oauth/_callback

シークレットの作成

「証明書とシークレット」からシークレットを作成します。シークレットの値はこのタイミングでしかコピーできないため、忘れずにコピーしておきましょう。

以上で、アプリケーションの定義は完了です。次に、GraphAPIを呼び出すためのAPI定義を作成します。

OpenAPI BuilderによるOpenAPI定義の作成

スキルを定義する際には、IBMのワークフロー製品や、UiPathのボットの取り込み、もしくはOpenAPI定義ファイルからインポートすることが可能です。APIによってはjson形式やyamlファイル形式で提供されているものもありますが、残念ながらGraphAPIでは提供されていません。そこで今回は、watsonx OrchestrateのOpenAPI Builderという機能を用いてOpenAPI定義を作成してみようと思います。この機能は、APIに関する情報が記述されているWebサイトのURLを指定すると生成AIを用いて定義を生成してくれるものです。

今回は以下のURLを指定し、GraphAPIのユーザーの取得APIをスキルとして登録してみることにします。
https://learn.microsoft.com/ja-jp/graph/api/user-get?view=graph-rest-1.0&tabs=http
使い方は簡単で以下の様にURLを指定してボタンをクリックし、生成するメソッドを選択するだけです。

※この機能は現状Beta版となり、利用するタイミングや、読み込むWebサイトによっては、上手く動作しないケースなどがあります。

しばらく待つと、OpenAPI定義が出力されるため、必要に応じて修正します。

今回のケースでは、セキュリティ設定が基本認証として定義されていたため、oauthを使用するようにAPIのsecurity設定とsecuirtySchemesを変更します。
なお、GraphAPIはスコープにoffline_accessを含めないとトークン・リクエストの応答にリフレッシュ・トークンが含まれないため、APIに必要なスコープに加えて、offline_accessをスコープに追加してください。以下にsecuritySchemesの例を示します。

 "components": {
        "securitySchemes": {
            "oauth": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://login.microsoftonline.com/oauth2/v2.0/authorize",
                        "tokenUrl": "https://login.microsoftonline.com/oauth2/v2.0/token",
                        "scopes": {
                            "offline_access": "required for reflesh token",
                            "User.Read": "read user info"
                        }
                    }
                }
            }
        }
    }

また、エンドポイントには、テナントのIDが含まれるケースがあるため、前述のアプリケーション設定画面でエンドポイントを確認してください。

OpenAPI定義の読み込み

watsonx Orchestrateのスキル・スタジオから作成したOpenAPIファイルを読み込みます。

OpenAPI定義に問題が無ければスキルのインポートが可能になります。（今回はOperationIDにスペースが含まれており、検証に失敗したため、ファイルを修正して再インポートしました。）

スキルが読み込まれるので、スキルの拡張＞Publishを行います。その後カタログからスキルを追加し、接続を行います。
ClientSecretとして先ほどコピーしたシークレットを、ClientIDとしてアプリケーションIDを指定してください。（シークレットIDでないことに注意）

テナントへのログイン画面が表示され、アクセス許可への同意ダイアログが表示されます。先ほどのスコープ定義で定義した権限が表示されていることを確認し、承諾ボタンをクリックします。

スキルの呼び出し

チャット画面より、先ほど定義したスキルを呼び出し、正しく動作することを確認します。
今回は、OpenAPIBuilderが生成した戻りのデータ型が正しく定義できていなかったために、一部のデータのみ返されましたが呼び出し自体は正しく動作しました。

まとめ

今回は、watsonx OrchestrateでMicrosoft Graph APIを呼び出す手順について説明しました。まだBeta機能のためか、OpenAPI定義を生成AIを用いて生成する部分に関しては完全なものができませんでしたが、APIの呼び出しは無事に成功しました。スコープ設定周りで躓くケースが多そうですが、そのあたりに注意すればスムーズに実装できるはずです。
戻りの型の修正については、手作業で修正したり、戻りの一部を生成AIに渡して型定義を生成したりすることも可能ですが、公開されているものもあり、こちらを用いることも可能でしょう。

watsonx Orchestrateに関する最新情報についてはこちらでも発信中ですので是非ご覧ください。