ParseDialogflowRequest ポリシー

このページは ApigeeApigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

ポリシー アイコン

概要

ParseDialogflowRequest ポリシーを使用すると、Dialogflow と Apigee を簡単に統合できます。詳細については、Apigee と Contact Center AI の統合をご覧ください。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

ParseDialogflowRequest ポリシーは、バックエンド システムにリクエスト データを送信する前に、Dialogflow エージェントからの WebhookRequest を処理します。このポリシーは WebhookRequest から API 呼び出し全体で使用できるフロー変数にデータを抽出します。この変数は、後続のコールアウト、ルックアップ、またはオーケストレーションされたロジックで使用できます。このポリシーは、Dialogflow エージェントが従来のバックエンド システムとやり取りする場合に特に便利です。エージェントのデータをバックエンド システムに送信する前に、データを解析して、バックエンド システムが使用できるようにそのデータを構造化できます。

バックエンド サービス インテグレータは、Dialogflow WebhookRequest の形式を理解することに時間を費やす必要はありません。すぐに使用できる ParseDialogflowRequest ポリシーで、リクエスト データをシームレスに処理します。

Apigee で Dialogflow エージェントの WebhookRequest にアクセスするには、エージェントの Webhook URL(フルフィルメント)を Apigee で構成した ProxyEndPoint に設定する必要があります。ProxyEndPoint は一般公開されている必要があります。詳しくは、Webhook サービスの要件をご覧ください。

<ParseDialogflowRequest>

ParseDialogflowRequest ポリシーを定義します。

デフォルト値 なし
必須かどうか 必須
複合オブジェクト
親要素 なし
子要素 <DialogflowVersion>
<DisplayName>
<VariablePrefix>

次の表に、ParseDialogflowRequest ポリシーに固有の子要素の概要を示します。

子要素 必須かどうか 説明
<VariablePrefix> 省略可 フロー変数のカスタム接頭辞を指定します。
<DialogflowVersion> 省略可 Dialogflow のバージョンを指定します。

次の例は、サンプル Webhook リクエスト、対応する ParseDialogflowRequest ポリシー、ポリシーの適用後に生成されたフロー変数を示しています。

構文

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The optional prefix to be added to all variables created from the
         Dialogflow Webhook request. Note that all variables created from the
         WebhookRequest object will be within a container named
         "google.dialogflow" -->
    <VariablePrefix>CUSTOM_PREFIX</VariablePrefix>
    <!-- The version of Dialogflow for which this request policy is written up.
         This policy supports only the CX version. This element is optional and
         defaults to CX if unspecified -->
    <DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>
</ParseDialogflowRequest>

Webhook リクエスト

次の例は、Dialogflow エージェントからの Webhook リクエスト(JSON 形式)を示しています。

{
    "fulfillmentInfo": {
        "tag": "check-claim-status"
    },
    "sessionInfo": {
        "session": "projects/apigee-test/locations/global/agents/ea45003d-3f5c-46ba-ac6b-f4c6dc8db707/sessions/5ea2e8-7c1-cf4-2cf-8e4d89e72",
        "parameters": {
            "claimId": "1234",
            "policyId": "abcd"
        }
    },
    "sentimentAnalysisResult": {
      "score": -0.7,
      "magnitude": 0.7
  }
}

リクエストで構成できるさまざまなフィールドについては、WebhookRequest をご覧ください。

次のサンプルに移動して、ParseDialogflowRequest ポリシーの構成を確認します。

ParseDialogflowRequest ポリシー

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="DialogflowRequest-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Request Policy</DisplayName>
    <VariablePrefix>my-prefix</VariablePrefix>
    <DialogflowVersion>CX</DialogflowVersion>
</ParseDialogflowRequest>

次のサンプルに移動して、ポリシーによって作成されたフロー変数を確認します。

フロー変数

google.dialogflow.my-prefix.fulfillment.tag = "check-claim-status"
google.dialogflow.my-prefix.session.id = "5ea2e8-7c1-cf4-2cf-8e4d89e72"
google.dialogflow.my-prefix.session.project.id = "apigee-test"
google.dialogflow.my-prefix.session.agent.id = "ea45003d-3f5c-46ba-ac6b-f4c6dc8db707"
google.dialogflow.my-prefix.session.parameters.claimId = "1234"
google.dialogflow.my-prefix.session.parameters.policyId = "abcd"
google.dialogflow.my-prefix.sentimentAnalysisResultScore = -0.7
google.dialogflow.my-prefix.sentimentAnalysisResultMagnitude = 0.7

生成されたフロー変数はすべて、google.dialogflow で始まり、その後に <VariablePrefix> 要素で指定された接頭辞(my-prefix)が続きます。

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<ParseDialogflowRequest> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値 なし
必須かどうか 省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<VariablePrefix>

フロー変数のカスタム接頭辞を指定します。この要素で指定された値は、ParseDialogflowRequest ポリシーによって生成されたすべての変数名の前に付けられます。デフォルトでは、ポリシーによって生成されたすべての変数の先頭に google.dialogflow が付きます。VariablePrefix 要素を指定した場合、google.dialogflow の後にカスタム接頭辞が追加されます。そのため、変数名は google.dialogflow.CUSTOM_PREFIX で始まります。

VariablePrefix 要素を指定しない場合、変数名の先頭には google.dialogflow のみが付きます。

デフォルト値 なし
必須かどうか 省略可
文字列
親要素 <ParseDialogflowRequest>
子要素 なし
<VariablePrefix> 要素の構文は次のとおりです。

構文

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

次の例では、VariablePrefix を my-prefix に設定しています。

<VariablePrefix>my-custom-prefix</VariablePrefix>

この構成により、すべての変数名は google.dialogflow.my-custom-prefix で始まります。

<DialogflowVersion>

Dialogflow のバージョンを指定します。ParseDialogflowRequest ポリシーは CX バージョンのみをサポートしています。ポリシーでこの要素を指定しないと、バージョンはデフォルトで CX になります。

デフォルト値 なし
必須かどうか 省略可
文字列
親要素 なし
子要素 なし
<DialogflowVersion> 要素の構文は次のとおりです。

構文

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

次の例では、DialogflowVersion を CX に設定します。

<DialogflowVersion>CX</DialogflowVersion>

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 修正
steps.parsedialogflowrequest.InvalidSessionInfo 500 このエラーは、Dialogflow リクエストに無効な sessionInfo.session フィールドがある場合に発生します。Webhook は、このフィールドを使用してセッションを識別します。サポートされているセッション形式については、SessionInfo クラスをご覧ください。
steps.parsedialogflowrequest.MalformedInput 500 このエラーは、このポリシーに提供された JSON が無効であるか、形式が正しくない場合に発生します。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因 修正
UnsupportedOperation このエラーは、DialogflowVersion 要素でサポートされていない Dialogflow バージョンを指定した場合に発生します。ParseDialogflowRequest ポリシーは CX バージョンのみをサポートしています。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラー メッセージが生成されます。これらのエラー メッセージはエラー レスポンスで確認できます。多くの場合、システムによって生成されたエラー メッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラー メッセージをカスタマイズして、より有用なメッセージにすることができます。

エラー メッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイム エラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

次の表に、このポリシーに固有の障害変数を示します。

変数 説明
fault.name="FAULT_NAME" FAULT_NAME は、ランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "UnresolvedVariable"
ParseDialogflowRequest.POLICY_NAME.failed POLICY_NAME は、障害が発生したポリシーのユーザー指定の名前です。 ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true
ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

関連トピック

ParseDialogflowRequest ポリシーの使用状況を示す Apigee プロキシと共有フローのリファレンス実装は、Apigee GitHub で入手できます。詳細については、会話型 AI リファレンス実装をご覧ください。