IBM Cloud Docs
カスタム拡張機能の作成

カスタム拡張機能の作成

REST API を持つ外部サービスとアシスタントを統合する必要がある場合は、OpenAPI 文書をインポートしてカスタム拡張機能を作成します。

カスタム拡張機能を作成した後で、それを統合としてアシスタントにつなげることができます。 その後、アクションで、拡張機能を呼び出すことによって外部サービスと対話するステップを定義できます。

GitHub の watsonx Assistant 拡張スターター・キット リポジトリーには、有効な拡張機能を素早く作成するために使用できるファイルと 拡張使用のヒント が用意されています。 各スターターキットには、サードパーティAPIにアクセスする拡張機能を作成するために使用できるテスト済みの OpenAPI 定義と、拡張機能にアクセスするアシスタントを作成するためにインポートできるダウンロード可能なJSONファイルが含まれています。

概要

OpenAPI (旧称 Swagger) は、REST API を記述および文書化するためのオープン・スタンダードです。 OpenAPI ドキュメントは、リクエストパラメータやレスポンスデータ、サーバーURLや認証方法などの詳細とともに、APIがサポートするリソースと操作を定義する。

OpenAPI 文書は、_パス_および_操作_に関して REST API を記述するものです。 パスは、API を使用してアクセスできる特定のリソース (例えば、ホテルの予約や顧客レコード) を識別します。 操作 は、そのリソースに対して実行できる特定のアクション (リソースの作成、取得、更新、削除など) を定義します。

OpenAPI ドキュメントは、使用される HTTP メソッド、リクエスト・パラメーター、リクエスト・ボディに含まれるデータ、レスポンス・ボディの構造など、各オペレーションのすべての詳細を指定する。

OpenAPI 仕様の詳細については、 OpenAPI 仕様を参照。

カスタム拡張機能を作成する際、外部サービスの REST API を記述した OpenAPI ドキュメントをインポートします。 IBM® watsonx™ Assistant は OpenAPI ドキュメントを解析し、外部サービスでサポートされている操作と、各操作の入力パラメータとレスポンス、サポートされている認証方法に関する情報を特定します。

この処理が完了すると、アシスタントに接続できる新しい統合としてカスタム拡張機能が使用可能になります。 その後、アシスタントはこの拡張機能を使用して、顧客との会話に基づいて外部サービスに要求を送信できます。 サービスからのレスポンスに含まれる値は、アクション変数にマッピングされ、後続のアクションステップでアクセスできる。

(アシスタントにカスタム拡張機能をつなげることについて詳しくは、カスタム拡張機能の追加を参照してください。)

API 定義の準備

カスタム拡張機能を作成するには、統合する REST API を記述する OpenAPI 文書にアクセスする必要があります。 多くのサード・パーティー・サービスは、API を記述する OpenAPI 文書を公開しています。その文書はダウンロードおよびインポートできます。 あなたの会社が保守しているAPIについては、標準的なツールを使って、それを説明する OpenAPI ドキュメントを作成することができる。

SwaggerHub Web サイトには、 OpenAPI 3.0 Tutorialと、 OpenAPI 文書の開発と検証に役立つ ツール が用意されています。 オンラインの Swaggerエディタを使用して、 OpenAPI ドキュメントを正しいフォーマットと OpenAPI バージョンに変換できます。

OpenAPI 文書は、以下の要件と制限を満たさなければなりません。

  • この文書は OpenAPI 3.0 仕様に準拠していなければなりません。 以前のバージョンの仕様を使用する OpenAPI (または Swagger) 文書がある場合は、オンライン Swagger エディターを使用して、それを OpenAPI 3.0 に変換します。

  • 文書は JSON フォーマットになっていなければなりません (YAML はサポートされていません)。 YAML 文書がある場合は、オンライン Swagger エディター を使用して、それを JSON に変換します。

  • JSON スクリプト内の要求本体は、オブジェクトとして提示する必要があります。 以下に例を示します。

    {
    name: "Bob",
    hobbies: ["sleeping", "eating", "walking"]
}

  • watsonx Assistantの プラス 以上のプランがある場合、文書のサイズは 4 MB 以下でなければなりません。 ただし、データ分離を使用する Enteprise プランがある場合、文書のサイズは 8 MB を超えてはなりません。

  • content-type は application/jsonでなければなりません。

  • 拡張機能からストリーミングするには、レスポンスのコンテンツタイプは text/event-stream。

  • 各操作には、明確で簡潔な summary が必要です。 要約テキストはアクションから利用可能な操作を説明するためにUIで使われるので、アシスタントを構築する人にとって短く、意味のあるものでなければなりません。

  • 相対 URL は現在サポートされていません。

  • 基本認証、ベアラー認証、OAuth 2.0認証、および API 鍵認証のみがサポートされます。

  • OAuth 2.0 認証の場合、許可コード、クライアント資格情報、パスワード、および x- で始まるカスタム付与タイプがサポートされます。 注: x- IBM IAM 認証メカニズム および watsonx によって使用されます。

  • anyOf、 oneOf、および allOf を使用して定義されたスキーマは、現在サポートされていません。

応答タイムアウト制限への準拠

外部APIを呼び出している間は、レスポンスのタイムアウト制限（48秒）を守らなければならない。 カスタム拡張のタイムアウト値は構成できません。

カスタム拡張機能の作成

API 定義に基づいてカスタム拡張機能を作成するには、以下の手順を実行します。

  1. 「統合」アイコン **「統合」**ページに移動します。

  2. **「拡張機能」セクションまでスクロールし、「カスタム拡張機能の作成 (Build custom extension)」**をクリックします。

  3. **「はじめに」情報を読み、「次へ」**をクリックして続行します。

  4. **「基本情報」**ステップで、作成する拡張機能に関する以下の情報を指定します。

    • 拡張機能名 (Extension name): 拡張機能の短い記述名 (例えば、CRM system や Weather service)。 この名前は Integrations ページのエクステンションのタイルに表示され、アクションエディタの利用可能なエクステンションのリストに表示されます。
    • 拡張の説明 (Extension description): 拡張機能とその機能の概要。 この説明は、 「統合 (Integrations)」 ページから使用できます。

    次へ をクリックします。

  5. Import OpenAPI ステップで、統合したい REST API を記述した OpenAPI ドキュメントをクリックまたはドラッグして追加します。

    JSONファイルをインポートしようとしたときにエラーが発生した場合は、そのファイルが API定義の準備に 記載されているすべての要件を満たしていることを確認してください。 そのファイルを編集してエラーを訂正するか、またはサポート対象外の機能を削除してください。 X をクリックしてエラー・メッセージを消去し、インポートを再試行してください。

    ファイルのインポートに成功したら、「 次へ 」をクリックします。

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

  7. 「認証」 タブには、 OpenAPI 文書で定義されている認証方式に関する情報が表示されます。 表。 「認証」タブのフィールド には、「認証」タブのフィールドに関する詳細が表示されます。

    フィールド名 説明 値
    認証タイプ OpenAPI スクリプトでセットアップされた認証のタイプ。 - OAuth 2.0
    - Basic Auth
    - API key auth
    - Bearer auth
    ユーザー名 OpenAPI スクリプト内のユーザー名の資格情報。 例: user
    パスワード OpenAPI スクリプトでセットアップされたパスワード資格情報。 例: Password@123
    servers 接続する Open API 文書で定義されているサーバーへのリンク。 API 拡張に追加します。 例: https://custom-extension-server.xyz

  8. レビュー操作の表は、アシスタントがアクションステップから呼び出せる操作を示しています。 操作とは、特定のリソースに対して、 GET や POST のような特定の HTTP メソッドを使用するリクエストのことである。

    「操作の確認」テーブル

     For each operation, a row in the table shows the following information:
    • 操作: 操作の説明。これは、OpenAPI ファイル内の summary (存在する場合) または description のいずれかから得られます。
    • メソッド: 操作の API 要求を送信するために使用される HTTP メソッド。
    • リソース: 操作の対象となるリソースへのパス。

    操作に関する詳細を表示するには、表内の行の横にあるラベル・アイコンをクリックします。 詳細は以下の通り：

    • 要求パラメーター: 操作に対して定義された入力パラメーターのリスト。各パラメーターのタイプも示されます。また、パラメーターが必須かオプションかも示されます。
    • レスポンスのプロパティ ：アシスタントがアクセスできる変数にマッピングされたレスポンスボディのプロパティ。

  9. 拡張機能に問題がなければ、**「終了」**をクリックします。

    何かを変更する場合は、対象の拡張機能を削除し、JSON ファイルを編集して変更を行い、インポート・プロセスを繰り返します。

この新しい拡張機能が統合カタログの**「拡張機能」**セクションでタイルとして使用できるようになりました。この拡張機能をアシスタントに追加できます。

OpenAPIドキュメントを置き換える

既存の OpenAPI ドキュメントを置き換えるには、以下の手順を実行します：

  1. 統合 (統合アイコン) > 拡張機能に進みます。

  2. OpenAPI ドキュメントを変更したいカスタム拡張カードの Open ボタンをクリックします。

  3. カスタム拡張機能を開くダイアログで、確認をクリックし、拡張機能の管理タブに移動します。

  4. Replace ボタンをクリックして、システムから新しい OpenAPI ドキュメントを選択し、Open をクリックします。

  5. 拡張機能の管理タブの操作の確認セクションで、オペレータを確認できます。

  6. OpenAPI ドキュメントを置き換えた後、Authentication タブの Authentication 情報を確認して更新します。

  7. アクションページに移動し、OpenAPIドキュメントを置き換えたために壊れたアクションスキルを修復します。