ParseDialogflowRequest ポリシー

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

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 ポリシーは、Dialogflow リクエスト内の fulfillmentInfo.tag、sentimentAnalysisResult、sessionInfo オブジェクトのみを解析します。

`<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` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`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>

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
`steps.parsedialogflowrequest.InvalidSessionInfo`	`500`	This error occurs if there is an invalid sessionInfo.session field in a Dialogflow request. A Webhook can use this field to identify a session. For information about the supported session format, see Class SessionInfo.
`steps.parsedialogflowrequest.MalformedInput`	`500`	This error occurs when the JSON provided to this policy is invalid or malformed.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`UnsupportedOperation`	This error occurs if you have specified unsupported Dialogflow version in the `DialogflowVersion` element. The ParseDialogflowRequest policy supports only `CX` version.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables	Where	Example
`fault.name="FAULT_NAME"`	`FAULT_NAME` is the name of the fault, as listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`ParseDialogflowRequest.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true`

For more information about policy errors, see What you need to know about policy errors.

ParseDialogflowRequest ポリシー

概要

<ParseDialogflowRequest>

例

構文

Webhook リクエスト

ParseDialogflowRequest ポリシー

フロー変数

子要素のリファレンス

<DisplayName>

構文

例

<VariablePrefix>

構文

例

<DialogflowVersion>

構文

例

エラーコード

Runtime errors

Deployment errors

Fault variables

関連トピック

`<ParseDialogflowRequest>`

`<DisplayName>`

`<VariablePrefix>`

`<DialogflowVersion>`