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>

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> 元素中所指定的。

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

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

子元素参考

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

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<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 政策

概览

<ParseDialogflowRequest>

示例

语法

Webhook 请求

ParseDialogflowRequest 政策

流变量

子元素参考

<DisplayName>

语法

示例

<VariablePrefix>

语法

示例

<DialogflowVersion>

语法

示例

错误代码

运行时错误

部署错误

故障变量

相关主题

`<ParseDialogflowRequest>`

`<DisplayName>`

`<VariablePrefix>`

`<DialogflowVersion>`