ParseDialogflowRequest 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

ParseDialogflowRequest 政策有助于将 Dialogflow 与 Apigee 集成。如需了解详情，请参阅将 Apigee 与 Contact Center AI 集成。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

ParseDialogflowRequest 政策会先处理来自 Dialogflow 代理的 WebhookRequest，然后再将请求数据发送到您的后端系统。该政策会将 WebhookRequest 中的数据提取到整个 API 调用期间可供您使用的流变量。您可以在后续宣传信息、查询或编排逻辑中使用这些变量。如果您希望 Dialogflow 代理与您的旧后端系统进行交互，则此政策特别有用。在将代理的数据发送到后端系统之前，您可以解析数据并以后端系统可以使用的方式对其进行构建。

如果您是后端服务集成商，则无需花时间了解 Dialogflow WebhookRequest 的格式。开箱即用的 ParseDialogflowRequest 政策可无缝处理请求数据。

如需在 Apigee 中访问 Dialogflow 代理的 WebhookRequest，您必须将代理的 Webhook 网址 (fulfillment 网址) 设置为您在 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>

网络钩子请求

以下示例显示了来自 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> 元素中所指定的。

此元素具有所有政策中常见的以下属性：

属性	默认	是否必需？	说明
name	无	必需	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError	false	可选	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障
enabled	true	可选	设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async	false	已弃用	此属性已弃用。

子元素参考

本部分介绍 <ParseDialogflowRequest> 的子元素。

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<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.

相关主题

Apigee GitHub 上提供了 Apigee 代理和共享流的参考实现，其中展示了 ParseDialogflowRequest 政策的用法。如需了解详情，请参阅对话式 AI 参考实现。