アシスタントに拡張機能を追加

オンラインで編集する

カスタム拡張機能を作成した後は、アクションでアシスタントにアクセスできるように、その拡張機能をアシスタントに追加する必要があります。

アシスタントにエクステンションを追加することで、エクステンションを特定の環境で使えるように設定し、アクションから呼び出せるようにします。

環境ごとに異なる構成の詳細を使用できます。 例えば、ドラフト環境ではテスト・サーバーの URL を使用し、稼働環境では実動サーバーの URL を使用できます。

カスタム拡張機能の作成方法については、カスタム拡張機能の作成を参照してください。

ドラフト環境に拡張機能を追加

カスタム拡張機能をアシスタントに追加するには、以下の手順を実行します。

  1. ページ 統合アイコン連携機能 上で、セクション 拡張機能 までスクロールし、追加したいカスタム拡張機能のタイルを探してください。

  2. 追加 をクリックします。 拡張機能の概要を確認し、「確認」をクリックして、拡張機能をアシスタント用に構成します。

拡張機能をアシスタントに初めて追加したときは、指定した構成設定はドラフト環境にのみ適用されます。 稼働環境に拡張機能を追加する前に、ドラフト環境の構成を完了しておく必要があります。 ライブ環境用の拡張機能の設定セクションを読んで、カスタム拡張機能をライブまたは他の環境に追加する方法を学んでください。

  1. 「はじめに」ステップにある情報を読み、「次へ」をクリックします。

  2. Authenticationステップでは、アシスタントがサービスを呼び出すときに使用する認証とサーバー情報を指定します。

    • Authentication typeフィールドで、使用する認証の種類を選択します（APIが認証されていない場合はNo authentication）。 利用可能な認証タイプは、OpenAPIドキュメントで定義されているセキュリティスキームによって決定される。

    • 選択した認証タイプに必要な追加情報（ユーザー名とパスワード、APIキー、ベアラートークン、または OAuth 2.0 の詳細など）を指定してください。

OAuth 2.0 の認証設定に関する詳細については、 OAuth 2.0 を参照してください。

  • 「サーバー」フィールドで、使用するサーバー URL を選択します。

選択した URL に変数が含まれている場合は、使用する値も指定します。 OpenAPI 文書で各変数が定義される方法に応じて、有効な値のリストから選択するか、またはフィールドで使用する値を入力します。

Generated URL メッセージは、変数値を含む、アシスタントが使用する完全な URL を表示します。

次へ をクリックします。

  1. レビュー操作の表は、アシスタントがアクションステップから呼び出せる操作を示しています。 「操作」とは、特定のリソースに対して、 HTTP の特定のメソッド（例： GET `POST`や`GET` POSTなど）を使用して行われるリクエストのことです。

オペレーション表の見直し

操作ごとに、テーブルの行には以下の情報が示されます。

  • 操作: 操作の説明。これは、OpenAPI ファイル内の summary (存在する場合) または description のいずれかから得られます。

  • メソッド: 操作の API 要求を送信するために使用される HTTP メソッド。

  • リソース: 操作の対象となるリソースへのパス。

操作の詳細を確認するには、テーブル内のその行の横にあるアイコン ラベル をクリックしてください。 以下の詳細が示されます。

  • 要求パラメーター: 操作に対して定義された入力パラメーターのリスト。各パラメーターのタイプも示されます。また、パラメーターが必須かオプションかも示されます。

  • レスポンスのプロパティ：アシスタントがアクセスできる変数にマッピングされたレスポンスボディのプロパティ。

  1. 「完了 (Finish)」 をクリックします。

  2. 「閉じる」をクリックして、「統合」ページに戻ります。

これで、拡張機能がアシスタントにつなげられて、ドラフト環境においてアクションで使用できるようになりました。

エクステンションの管理

カスタム拡張モジュールを環境に追加したら、そのOpenAPIドキュメントを見直したり置き換えたりして、認証タイプを更新します。

  1. 拡張機能で「開く」をクリックする。

  2. カスタム拡張機能を管理する環境を選択し、［確認］をクリックします。

  3. Manage extensionステップでは、インポートされたOpenAPIドキュメントを確認し、必要に応じて置き換えることができます。 OpenAPIドキュメントの置き換えについては、 OpenAPIドキュメントの置き換えを参照してください。

  4. Authenticationタブには、OpenAPIドキュメントで定義されている認証方法についての情報が表示されます。 について 表 認証」タブのフィールド表には、「認証」タブのフィールドの詳細が示されている：

フィールド名

説明

値

認証タイプ

OpenAPIスクリプトで設定されている認証の種類。

- OAuth 2.0 - Basic Auth - API key auth - Bearer auth

ユーザー名

OpenAPIスクリプトのユーザー名クレデンシャル。

例: user

パスワード

OpenAPIスクリプトで設定されたパスワードクレデンシャル。

例: Password@123

サーバー

API エクステンションに接続するための、Open API ドキュメントで定義されているサーバーへのリンク。

例: https://custom-extension-server.xyz

OAuth 2.0 認証

OAuth 2.0 の認証を設定する場合、入力が必要な情報はグラントの種類によって異なります。

OAuth （ 2.0 ）に関する詳細については、 OAuth （ 2.0 ）をご覧ください。

OAuth の認証設定を完了するには、以下の手順に従ってください：

  1. まだの場合は、アクセスしたい外部APIにアプリケーションを登録する。 外部APIから提供されるクライアントIDとクライアント・シークレットをコピーする。

  2. 補助金の種類フィールドで、使用する補助金の種類を選択します。 利用可能なグラント・タイプは、OpenAPIドキュメントの'securitySchemesオブジェクトに定義されているフローによって決定される。 認証コード、クライアント資格情報、パスワード、および「x-」で始まるカスタムグラントタイプがサポートされています。

「 OAuth2 」カスタムグラントタイプは、 IBMx-<any custom name> のIAM認証メカニズムおよび watsonx で使用されます。

  1. アプリケーションの登録時に外部APIから提供された必須値を指定します。 必要な値は、補助金の種類によって異なります：

表 1. 助成金の種類

付与タイプ

必須値

許可コード

- クライアントID \n - クライアントシークレット

クライアント資格情報

- クライアントID \n - クライアントシークレット

パスワード

- クライアントID \n - クライアントシークレット \n - ユーザー名 \n - パスワード

x-<any custom name>

- 「 openAPI 」仕様書に記載されている秘密フィールドの一覧

  1. 認証コード・グラント・タイプを使用している場合は、以下の手順に従ってください：

    1. AIアシスタントビルダー 拡張機能の設定ページからリダイレクトURL（ URL ）をコピーし、外部APIのアプリケーション登録ページの該当するフィールドに貼り付けてください。 （ URL へのリダイレクトは、_コールバック URL_と呼ばれることもあります。）

    2. アクセスを許可」をクリックします。 外部サービスのウェブサイトの認証ページにリダイレクトされます。 正しいアクセス権が付与されていることを確認し、承認をクリックします。 その後、リダイレクト URL を使用して、拡張機能の設定ページにリダイレクトされます。

  2. クライアント認証フィールドで、認証情報を HTTP ヘッダーで送信するか、リクエストボディの一部として送信するかを指定します。 (リクエストボディで送信されるクレデンシャルは、「x-www-form-urlencodedコンテンツタイプを使用する) 外部サービスが期待するオプションを選択します。

  3. ヘッダープレフィックスフィールドには、「Authorizationヘッダのアクセストークンの前に付けるプレフィックスを指定します。 (デフォルトの接頭辞は'Bearerで、ほとんどのアプリケーションで一般的です)

  4. カスタム・グラント・タイプ「x-<any custom name>（例：x-apikey）を使用している場合は、以下の手順に従ってください：

    1. シークレットフィールドに関連するシークレット値を追加する。

    2. オプションのパラメータ値があれば、それを追加する。

外部サービスが「リフレッシュトークン」グラントタイプに対応している場合、 AIアシスタントビルダーは、 古いアクセストークンの有効期限が切れると、自動的に新しいアクセストークンを取得します。 OpenAPI ドキュメントで 属性 refreshUrl が定義されている場合は、指定された URL が使用されます。そうでない場合は、 tokenUrlURL が使用されます。

稼働環境用に拡張機能を構成

稼働環境用に拡張機能を構成するには、以下の手順を実行します。

  1. ページ 統合アイコン連携機能 上で、セクション 拡張機能 までスクロールし、追加したいカスタム拡張機能のタイルを探してください。

  2. 「開く」をクリックします。 「カスタム拡張機能を開く (Open custom extension)」ウィンドウが開きます。

  3. 「環境」フィールドで「稼働中」を選択します。 「確認」 をクリックしてください。

  4. 本番環境で使用する値を指定して、設定プロセスを繰り返す。

複数の環境を使用している場合は、同じ手順に従って各環境で拡張機能を設定してください。 詳しくは、複数環境の追加と使用を参照してください。

エクステンションは設定した環境で利用できるようになり、アシスタントから呼び出すことができます。 アクションから拡張機能を呼び出す方法について詳しくは、カスタム拡張機能の呼び出しを参照してください。