Oracle Digital Assistantには、ビジュアル・ダイアログ・スキルで使用してRESTサービスのエンドポイントにリクエストを送信できる組込みのコールRESTサービス・コンポーネントが用意されています。コールRESTサービス・コンポーネントからリクエストを作成する前に、まず「RESTサービス」タブでエンドポイントを構成する必要があります。

RESTサービスを追加するには:

1. Oracle Digital Assistantで、をクリックしてサイド・メニューを開き、「設定」、「APIサービス」の順に選択して、「RESTサービス」タブをクリックします。

2. 次の一般情報を指定します。

   フィールド	説明
   名前	構成しているエンドポイントを簡単に識別できる一意の名前。たとえば、アポイントメントAPIの場合、RESTサービスにappointmentsUserおよびappointmentsUserEntryという名前を付けることができます。
   エンドポイント	REST操作にアクセスするためのエンドポイント。中カッコを使用して、パス・パラメータを示します。たとえば: https://example.com/appointments/{userId}。 Oracle Cloud Infrastructureエンドポイントの場合は、テナンシのリージョンにエンドポイントを使用していることを確認してください。
   説明	エンドポイントの目的を説明するオプションの説明。例: "ユーザーのアポイントを追加および取得します。"
   認証タイプ	RESTコールの認証方法を選択します。 認証不要:サービスで認証が不要な場合に選択します。 基本認証:サービスが基本認証を使用する場合、これを選択します。次に、ユーザー名とパスワードを入力する必要があります。 APIキー:サービスが認証にAPIキーを使用する場合、これを選択します。次に、キーをパス・パラメータとして渡すか問合せパラメータとして渡すかを指定し、キー名と値を指定する必要があります。 Bearerトークン:サービスが認証にBearerトークンを使用する場合、これを選択します。次に、トークンを指定する必要があります。 OCIリソース・プリンシパル: Oracle Cloud Infrastructure APIにアクセスする場合は、これを選択します。
   プライベート・エンドポイント	アクセスする必要があるサービスにプライベート・エンドポイントが設定されている場合は、このスイッチをオン位置に切り替え、使用しているプライベート・エンドポイントを選択します。 ノート:インターネット上でパブリックに公開されていないサービスのプライベート・エンドポイントを設定できます。プライベート・エンドポイントを参照してください。

3. エンドポイントに対して構成する各メソッドについて、「+ Add Method」をクリックしてメソッドを選択し、次の情報を指定します:

   フィールド	説明
   コンテンツ・タイプ	リクエスト本文に含まれるコンテンツのタイプ。application/jsonおよびtext/plainがサポートされています。
   本文	POST、PUTおよびPATCHリクエストの場合、リクエストとともに送信するリクエスト本文。この値は、コールRESTサービス・コンポーネントで上書きできます。 大規模なリクエスト本文の場合は、「編集ダイアログの使用」をクリックしてエディタを開きます。
   パラメータ	リクエストをテストするためのパスおよび問合せパラメータを追加できます。パスおよび問合せパラメータを追加して、デフォルト値を構成することもできます。スキル開発者は、コールRESTサービス・コンポーネントからこれらのパラメータ値をオーバーライドできます。つまり、コンポーネントにパラメータを追加して、RESTサービスで構成された値をオーバーライドしたり、RESTサービス構成で設定された値を使用するパラメータを追加したりすることはできません。 エンドポイントにあるパス・パラメータに対して、「パス」タイプのパラメータを追加し、パス・パラメータと一致するようにキーを設定し、目的の値を設定します。 RESTリクエストに渡す問合せパラメータの場合は、「問合せ」タイプのパラメータを追加し、問合せパラメータと一致するようにキーを設定し、目的の値を設定します。 認証タイプがAPIキーで、キーが問合せパラメータとして渡される場合は、そのキー値の問合せパラメータをすでに構成されているため、ここでは追加しないでください。 パラメータを編集したら、をクリックして、リストにパラメータを追加します。
   ヘッダー	リクエストに渡すヘッダーを追加します。 認証タイプがAPIキーで、キーがヘッダーで渡される場合、そのキー値のヘッダーはすでに構成されているため、ここでは追加しないでください。
   静的レスポンス	静的レスポンス構成は、エラーが発生するたびにフォールバック・レスポンスが必要な場合に使用できます。これを使用して、開発またはテストの目的でモック・データを設定することもできます。 静的レスポンスを構成するには、リターン・ステータス・コードを選択してからレスポンス本文を定義します。または、必要なパラメータおよびヘッダーを設定し、「テスト・リクエスト」、「静的レスポンスとして保存」の順にクリックして、静的レスポンスの値を保存します。

4. メソッドをテストする場合は、パスに使用するパスおよび問合せパラメータを設定し、必要なヘッダーを設定し、必要に応じてリクエスト本文を指定し、「リクエストのテスト」をクリックします。「レスポンス・ステータス」ダイアログに、レスポンスのステータスと本文が表示されます。

   ヒント:

   「静的レスポンスとして保存」をクリックすると、静的レスポンス・フィールドにステータス・コードと本文を保存できます。

スキルがバックエンド・サービスを介して一部のデータを取得または更新する必要がある場合、コールRESTサービス・コンポーネントを使用する状態を追加します。このコンポーネントの使用方法を次に示します。

1. 「設定」→「APIサービス」→「RESTサービス」ページで、「エンドポイントのRESTサービスの追加」の説明に従ってエンドポイントを構成します。ここでは、エンドポイント、認証タイプ、サポートされているメソッド、リクエスト本文、パスおよび問合せパラメータ、ヘッダーおよびオプションの静的レスポンスを定義します。

2. スキルのフロー・デザイナの目的のフローで、状態を追加し、「サービス統合」→「Restサービスの呼出し」を選択して名前を指定し、「挿入」をクリックします。

3. 「RESTサービス」ページで構成したRESTサービスを選択します。

4. メソッドを選択します。

5. POST、PUTおよびPATCHリクエストの場合、通常、リクエスト本文を指定する必要があります。

   ヒント:

   本文にFreeMarker式が含まれている場合は、「式」を「オン」に切り替えて、FreeMarker構文の色付けを確認できます。ただし、これを行うと、JSON構文検証はオフになります。

6. 「パラメータ」セクションで、リクエストとともに送信するパスおよび問合せパラメータを構成します。

   コンポーネントで設定したパラメータは、RESTサービス構成で設定されたパラメータを上書きします。逆に、コンポーネントにパラメータを設定しない場合、リクエストではRESTサービス構成のパラメータ値が使用されます。

   RESTサービス構成で定義された問合せパラメータに対して、その問合せパラメータを渡さない場合は、その値を${r""}に設定します。

7. リクエストとともに送信するヘッダーを設定します。

   コンポーネントで設定したヘッダーは、RESTサービス構成で設定されたヘッダーを上書きします。逆に、コンポーネントにヘッダーを設定しない場合、リクエストではRESTサービス構成のヘッダー値が使用されます。

8. コール完了後に返すレスポンスを指定します。

   • 実際のREST APIレスポンスの使用: RESTサービスからの実際のレスポンスを返します。

   • 常に静的RESTレスポンスを使用:これにより、「RESTサービス」タブで構成された静的レスポンスが返されます。このレスポンスは、開発フェーズやテスト・フェーズなどで役立ちます。

   • 静的レスポンスを使用したフォールバック: RESTリクエストが成功すると、RESTレスポンスが返されます。それ以外の場合は、「RESTサービス」タブで構成された静的レスポンスが返されます。

   RESTサービス構成に静的レスポンスがない場合、選択肢は「実際のレスポンスの使用」のみです。

9. 結果変数の場合は、レスポンス・データを格納するマップ変数を選択します。まだ存在しない場合は、「作成」をクリックして作成します。

   リクエストが完了すると、マップにはレスポンス本文のresponsePayloadプロパティとステータス・コードのstatusCodeプロパティが含まれます。レスポンス本文を変数に格納する方法は、レスポンスがJSONオブジェクト、JSON配列またはプレーン・テキスト(文字列)のいずれであるかによって異なります:

   • JSONオブジェクト:オブジェクトはresponsePayloadプロパティに格納されます。

   • JSON配列:配列はresponsePayload.responseItemsプロパティに格納されます。

   • プレーン・テキスト:テキストはresponsePayload.messageプロパティに格納されます。

10. 「遷移」タブで、次の遷移と、成功および失敗アクションの遷移を指定します。

    • successアクションは、statusCodeが100から299の間にある場合に発生します。

    • failureアクションは、statusCodeが300以上の場合に発生します。

このコンポーネントの詳細は、RESTサービスのコールを参照してください。