SetDialogflowResponse 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

政策图标

概览

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

在将响应数据作为 WebhookResponse 发送到 Dialogflow 代理之前，SetDialogflowResponse 政策会处理来自后端系统的响应数据并设置其格式。Dialogflow 代理需要以特定格式提供 WebhookResponse，而 SetDialogflowResponse 政策就会以所需的格式构建响应。该政策以 Dialogflow 代理所需的格式构建 WebhookResponse。WebhookResponse 具有自然语言短语和其他 Dialogflow 代理可以理解的参数。

如果您是后端服务集成商，则无需花时间了解 Dialoglfow WebhookResponse 的格式。开箱即用的 SetDialogflowResponse 政策能够无缝处理响应数据。

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

<SetDialogflowResponse>

定义 SetDialogflowResponse 政策。

默认值 不适用
是否必需？ 必需
类型 复杂对象
父元素 不适用
子元素 <DisplayName>
<Source>
<DialogflowVersion>
<NaturalLanguageResponse>
<Parameters>
<IgnoreUnresolvedVariables>

下表简要介绍了 SetDialogflowResponse 元素的所有子元素：

子元素 是否必需？ 说明
<DisplayName> 可选 政策的自定义名称。
<Source> 可选 指定要解析的变量。
<DialogflowVersion> 可选 指定 Dialogflow 版本。
<NaturalLanguageResponse> 可选 封装要作为 WebhookResponse.FulfillmentResponse 对象发送的所有内容。
<Parameters> 可选 <Parameter> 的父元素。定义要在 Webhook 响应中设置的一组参数。
<IgnoreUnresolvedVariables> 可选 指定在遇到无法解析的变量时处理是否停止。
其他子元素
<MergeBehavior> 可选 指定响应消息的合并行为。
<Header> 可选 提取响应标头中指定字段的值。
<JSONPath> 可选 提取指定 JSON 路径的值。
<Parameter> 必需 指定要在 Webhook 响应的 sessionInfo.parameters 对象中设置的参数。
<Phrase> 必需 指定要在 Webhook 响应的 fulfillmentResponse.messages 对象中设置的短语（文本）。
<Phrases> 可选 <Phrase> 的父元素。定义要在网络钩子响应中设置的一组自然语言短语。
<Ref> 可选 提取指定引用变量的值。
<Value> 可选 将自定义文本设置为指定参数。

示例

以下示例展示了发送到 Dialogflow 代理的 SetDialogflowResponse 政策示例和 WebhookResponse：

语法

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetDialogflowResponse continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The message variable from which the policy extracts the required information -->
    <Source>MESSAGE_VARIABLE</Source>
    <!-- The version of Dialogflow for which this response 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>
    <!-- A container object to encapsulate all content needed for a natural
         language response to be returned to Dialogflow from the Southbound API -->
    <NaturalLanguageResponse>
        <!-- Defines the merge behavior for existing responses and new responses.
             Refer here for more details -->
        <MergeBehavior>MERGE_BEHAVIOR</MergeBehavior>
        <!-- An ordered list of natural language phrases to be returned to
             Dialogflow from the Southbound API -->
        <Phrases>
            <!-- A phrase is a natural language phrase that Dialogflow agents
                 can send back to their caller/chatting customer -->
            <Phrase>
                <!-- A phrase can be extracted from the response JSON payload of a
                     service callout -->
                <JSONPath>JSON_PATH</JSONPath>
            </Phrase>
            <Phrase>
                <!-- A phrase can be extracted from the response headers of a
                     service callout -->
                <Header name="HEADER_NAME"/>
            </Phrase>
            <Phrase>
                <!-- A phrase refer to the value of an existing flow variable -->
                <Ref>EXISTING_FLOW_VARIABLE</Ref>
            </Phrase>
            <Phrase>
                <!-- A phrase can be static text -->
                <Value>CUSTOM_TEXT</Value>
            </Phrase>
        </Phrases>
    </NaturalLanguageResponse>
    <!-- A container object defining the parameters to be set as session parameters
         in the Webhook response sent to Dialogflow -->
    <Parameters>
        <!-- Defines a single parameter to be set in sessionInfo.parameters object
             of the WebhookResponse object. The name of the parameter is defined
             as an attribute -->
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be extracted from the response JSON
                 payload of a service callout -->
            <JSONPath>JSON_PATH</JSONPath>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be extracted from the response headers
                 of a service callout -->
            <Header name="HEADER_NAME"/>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be refer to the value of an existing flow
                 variable -->
            <Ref>EXISTING_FLOW_VARIABLE</Ref>
        </Parameter>
        <Parameter name="PARAMETER_NAME">
            <!-- A parameter's value can be static text -->
            <Value>CUSTOM_TEXT</Value>
        </Parameter>
    </Parameters>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
</SetDialogflowResponse>

SetDialogflowResponse 政策

以下示例展示了 SetDialogflowResponse 政策的定义：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SetDialogflowResponse continueOnError="false" enabled="true"
        name="CCAIDialogflowResponse-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Response Policy</DisplayName>
    <Source>myMessageVar</Source>
    <DialogflowVersion>CX</DialogflowVersion>
    <NaturalLanguageResponse>
        <MergeBehavior>APPEND</MergeBehavior>
        <Phrases>
            <Phrase>
                <JSONPath>$.claim.status.text</JSONPath>
            </Phrase>
            <Phrase>
                <Header name="X-Response-Text"/>
            </Phrase>
            <Phrase>
                <Ref>myVar</Ref>
            </Phrase>
            <Phrase>
                <Value>You call is important to us</Value>
            </Phrase>
        </Phrases>
    </NaturalLanguageResponse>
    <Parameters>
        <Parameter name="claimStatus">
            <JSONPath>$.claim.status.value</JSONPath>
        </Parameter>
        <Parameter name="claimAmount">
            <JSONPath>$.claim.amount</JSONPath>
        </Parameter>
        <Parameter name="timeSpent">
            <Header name="X-Time-Spent"/>
        </Parameter>
        <Parameter name="myVar">
            <Ref>dialogflow.my.var</Ref>
        </Parameter>
        <Parameter name="responder">
            <Value>SYSTEM</Value>
        </Parameter>
    </Parameters>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</SetDialogflowResponse>

转到下一个示例，查看此政策创建的网络钩子响应。

网络钩子响应

以下示例展示了发送到 Dialogflow 代理的 WebhookResponse：

{
    "fulfillmentResponse": {
        "mergeBehavior": "APPEND",
        "messages": [{
            "text": {
                "text": ["Your claim is currently being processed",
                          "Please call back in a couple of days"]
            }
        }]
    },
    "sessionInfo": {
        "parameters": {
            "claimStatus": "PROCESSING",
            "claimAmount": 1000
        }
    }
}

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

属性 默认 是否必需？ 说明
name 无 必需

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError 否 可选 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：
enabled true 可选 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async   否 已弃用 此属性已弃用。

子元素参考

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

<DisplayName>

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

<DisplayName> 元素适用于所有政策。

默认值 不适用
是否必需？ 可选。如果省略 <DisplayName>，则会使用政策的 name 属性的值
类型 字符串
父元素 <PolicyElement>
子元素 无

<DisplayName> 元素使用以下语法：

语法

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

示例

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

<DisplayName> 元素没有属性或子元素。

<Source>

指定要解析的变量。<Source> 的值默认为 message。message 值取与上下文相关。在请求流中，message 解析为请求消息。在响应流中，message 解析为响应消息。

虽然此政策通常用于从请求或响应消息中提取信息，但您也可以用它来从任何变量中提取信息。例如，您可以使用此政策从 AccessEntity 政策创建的实体、ServiceCallout 政策返回的数据或 XML 或 JSON 对象中提取信息。

如果 <Source> 无法解析或解析为非消息类型，则政策将失败，并且您会收到运行时错误。

默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <SetDialogflowResponse>
子元素 无
<Source> 元素使用以下语法：

语法

<Source>MESSAGE_VARIABLE</Source>

示例

以下示例将 Source 设置为 myMessageVar：

<Source>myMessageVar</Source>

<DialogflowVersion>

指定 Dialogflow 版本。SetDialogflowResponse 政策仅支持 CX 版本。如果您未在政策中指定此元素，则版本默认为 CX。

默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <SetDialogflowResponse>
子元素 无
<DialogflowVersion> 元素使用以下语法：

语法

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

示例

以下示例将 DialogflowVersion 设置为 CX：

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

确定在遇到无法解析的变量时处理是否停止。

默认值 True
是否必需？ 可选
类型 布尔值
父元素 <SetDialogflowResponse>
子元素 无

设置为 true 可忽略无法解析的变量并继续处理；否则设置为 false。默认值为 true。

将 <IgnoreUnresolvedVariables> 设置为 true 与将 <SetDialogflowResponse> 的 continueOnError 设置为 true 不同。如果将 continueOnError 设置为 true，Apigee 会忽略所有错误，而不仅仅是变量中的错误。

<IgnoreUnresolvedVariables> 元素使用以下语法：

语法

 <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

示例

以下示例将 <IgnoreUnresolvedVariables> 设置为 false：

       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<MergeBehavior>

定义响应消息的合并行为。您可以指定以下任一值：

  • APPEND：将消息附加到等待发送给用户的消息列表中。
  • REPLACE：将旧消息替换为等待发送给用户的消息列表中的较新消息。
如果您未指定元素，行为将默认为 APPEND。
默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <NaturalLanguageResponse>
子元素 无
<MergeBehavior> 元素使用以下语法：

语法

<MergeBehavior>BEHAVIOR</MergeBehavior>

示例

以下示例将合并行为设置为 APPEND：

<MergeBehavior>APPEND</MergeBehavior>

<NaturalLanguageResponse>

封装您要发送到 Dialogflow 代理的所有自然语言响应。

默认值 不适用
是否必需？ 可选
类型 复杂对象
父元素 <SetDialogflowResponse>
子元素 <MergeBehavior>
<Phrases>

<Parameters>

定义要在 Webhook 响应中设置的一组参数。该参数的名称是 <Parameter> 元素的属性。

默认值 不适用
是否必需？ 可选
类型 复杂对象
父元素 <SetDialogflowResponse>
子元素 <Parameter>

<Parameter>

指定要在 Webhook 响应的 sessionInfo.parameters 对象中设置的参数。

您可以将静态文本指定为参数值，或从响应中的以下任何字段提取值：

  • 响应标头字段
  • JSON 载荷
  • 流变量

您必须为要提取的每个值定义单独的 <Parameter> 元素。

默认值 不适用
是否必需？ 必需
类型 复杂对象
父元素 <Parameters>
子元素 <Header>
<JSONPath>
<Ref>
<Value>
<Parameter> 元素具有以下特性：
属性 说明 是否必需？ 类型
name 使用此参数创建的变量的名称。 是 字符串

<Parameter> 元素使用以下语法：

语法

<Parameters>
  <Parameter name="PARAMETER_NAME">
  <Header name="HEADER_NAME"/>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <JSONPath>JSON_PATH</JSONPath>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <Ref>EXISTING_FLOW_VARIABLE</Ref>
</Parameter>
<Parameter name="PARAMETER_NAME">
  <Value>CUSTOM_TEXT</Value>
</Parameter>
</Parameters>

提取标头字段值

此示例将 timeSpent 参数设置为 X-Time-Spent 标头字段的值。

<Parameter name="timeSpent">
     <Header name="X-Time-Spent"/>
</Parameter>

提取 JSON 路径值

此示例将 claimAmount 参数设置为 JSON 载荷中 claim.amount 字段的值。

<Parameter name="claimAmount">
   <JSONPath>$.claim.amount</JSONPath>
</Parameter>

提取流变量值

此示例将 myVar 参数设置为 dialogflow.my.var 流变量的值。

<Parameter name="myVar">
   <Ref>dialogflow.my.var</Ref>
</Parameter>

设置自定义文本

此示例将 responseer 参数的值设置为 SYSTEM。

<Parameter name="responder">
   <Value>SYSTEM</Value>
</Parameter>

<Phrases>

<Phrase> 的父元素。定义要在网络钩子响应中设置的自然语言短语的有序列表。

默认值 不适用
是否必需？ 可选
类型 复杂对象
父元素 <NaturalLanguageResponse>
子元素 <Phrase>

<Phrase>

指定要在 Webhook 响应的 fulfillmentResponse.messages 对象中设置的短语（文本）。

您可以将静态文本指定为短语值，或从响应中的以下任何字段提取值：

  • 响应标头字段
  • JSON 载荷
  • 流变量

您必须为每个要提取的值定义单独的 <Phrase> 元素。

默认值 不适用
是否必需？ 必需
类型 复杂对象
父元素 <Phrases>
子元素 <Header>
<JSONPath>
<Ref>
<Value>

<Phrase> 元素使用以下语法：

语法

<Phrases>
  <Phrase>
    <Header name="HEADER_NAME"/>
  </Phrase>
  <Phrase>
    <JSONPath>JSON_PATH</JSONPath>
  </Phrase>
  <Phrase>
    <Ref>EXISTING_FLOW_VARIABLE</Ref>
  </Phrase>
  <Phrase>
    <Value>CUSTOM_TEXT</Value>
  </Phrase>
</Phrases>

提取标头字段值

此示例会在 X-Response-Text 标头字段的值中设置自然语言文本。

<Phrase>
     <Header name="X-Response-Text"/>
</Phrase>

提取 JSON 路径值

此示例会在 JSON 载荷中 claim.status.text 字段的值的响应中设置自然语言文本。

<Phrase>
   <JSONPath>$.claim.status.text</JSONPath>
</Phrase>

提取流变量值

此示例设置自然语言文本，以响应 myVar 流变量的值。

<Phrase>
   <Ref>myVar</Ref>
</Phrase>

设置自定义文本

此示例会将文本 You call is important to us 添加到响应的自然语言文本中。

<Phrase>
   <Value>You call is important to us</Value>
</Phrase>

从响应标头的指定字段中提取值。您可以使用标头值来设置自然语言文本或响应参数。

  • 要将标头值提取为自然语言响应，请在 <Phrase> 元素中指定 <Header> 元素。
  • 要提取标头值作为响应参数，请在 <Parameter> 元素中指定 <Header> 元素。
默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <Phrase>
<Parameter>
子元素 无
<Header> 元素使用以下语法：

语法

<Header name="HEADER_FIELD"/>

示例 1

以下示例获取自然语言响应中的 X-Response-Text 标头字段的值：

<Phrase>
  <Header name="X-Response-Text"/>
<Phrase/>

示例 2

以下示例获取 X-Response-Text 标头字段的值作为响应参数：

<Parameter name="timeSpent">
  <Header name="X-Response-Text"/>
<Parameter/>

timeSpent 流变量设置为 X-Response-Text 标头字段的值。

<Header> 元素具有以下特性：

属性 说明 必填？ 类型
name 指定从中提取值的响应标头的名称。 必需 字符串

<JSONPath>

提取服务标注的 JSON 载荷中的 JSON 路径值。您可以使用该值设置自然语言文本或响应参数。

  • 要将 JSON 值提取为自然语言文本，请在 <Phrase> 元素中指定 <JSONPath> 元素。
  • 要提取 JSON 值作为响应参数，请在 <Parameter> 元素中指定 <JSONPath> 元素。
默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <Phrase>
<Parameter>
子元素 无
<JSONPath> 元素使用以下语法：

语法

<JSONPath>JSON_PATH</JSONPath>

示例 1

以下示例获取自然语言响应中的 claim.status.text JSON 字段的值：

<Phrase>
  <JSONPath>$.claim.status.text</JSONPath>
<Phrase/>

示例 2

以下示例获取 claim.amount JSON 字段的值作为响应参数：

<Parameter name="claimAmount">
  <JSONPath>$.claim.amount.</JSONPath>
<Parameter/>

claimAmount 流变量设置为 {claim.amount} JSON 字段的值。

<Ref>

提取现有流变量的值。您可以使用该值设置自然语言文本或响应参数。

  • 要将变量的值提取为自然语言文本，请在 <Phrase> 元素中指定 <Ref> 元素。
  • 如需提取变量值作为响应参数，请在 <Parameter> 元素中指定 <Ref> 元素。
默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <Phrase>
<Parameter>
子元素 无
<Ref> 元素使用以下语法：

语法

<Ref>EXISTING_FLOW_VARIABLE</Ref>

示例 1

以下示例获取 myVar 流变量的值作为自然语言响应：

<Phrase>
  <Ref>myVar</Ref>
<Phrase/>

示例 2

以下示例获取 dialogflow.my.var 流变量的值作为响应参数：

<Parameter name="customVar">
  <Ref>dialogflow.my.var</Ref>
<Parameter/>

customVar 流变量设置为 dialogflow.my.var 变量的值。

<Value>

将字面量值设置为自然语言文本或响应参数。

  • 要将字面量值设置为自然语言文本，请在 <Phrase> 元素中指定 <Value> 元素。
  • 如需将字面量值设为响应参数，请在 <Parameter> 元素内指定 <Value> 元素。
默认值 不适用
是否必需？ 可选
类型 字符串
父元素 <Phrase>
<Parameter>
子元素 无
<Value> 元素使用以下语法：

语法

<Value>CUSTOM_TEXT</Value>

示例 1

以下示例将文本文本 You call is important to us 设置为自然语言响应：

<Phrase>
  <Value>You call is important to us</Value>
<Phrase/>

示例 2

以下示例将文本文本 SYSTEM 设置为响应参数：

<Parameter name="responder">
  <Value>SYSTEM</Value>
<Parameter/>

responder 流变量设置为 SYSTEM。

错误代码

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因
steps.setdialogflowresponse.ExecutionFailed 500 当政策执行因常规异常而失败时，会发生此错误。故障消息包含异常的详细信息。
steps.setdialogflowresponse.InvalidSourceType 500 如果 <Source> 元素中指定的变量不是消息类型，则会出现此错误。
steps.setdialogflowresponse.MalformedInput 500 当提供给此政策的 JSON 无效或格式错误时，就会出现此错误。
steps.setdialogflowresponse.SourceMessageNotAvailable 500 如果政策的 Source 元素中指定的 message 变量为以下任意一项，就会出现此错误：
  • 超出范围（在执行政策的特定流中不可用）
    • 或
  • 无法解析（未定义）
steps.setdialogflowresponse.UnresolvedHeader 500 如果 Header 元素包含无效的标头，则会出现此错误。例如，如果 Header 元素的值为 X-Response-Text，并且响应标头中没有 X-Response-Text，您会收到此错误。
steps.setdialogflowresponse.UnresolvedJSONPath 500 如果 JSONPath 元素包含无效路径，则会出现此错误。例如，如果 JSONPath 元素的值为 {claim.status.value}，并且 JSON 载荷中没有 status 对象，则会出现此错误。
steps.setdialogflowresponse.UnresolvedVariable 500

如果 SetDialogflowResponse 政策中指定的变量为以下任一情况，就会出现此错误：

  • 超出范围（在执行政策的特定流中不可用）
    • 或
  • 无法解析（未定义）

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因
UnsupportedOperation 如果您在 DialogflowVersion 元素中指定了不受支持的 Dialogflow 版本，则会发生此错误。SetDialogflowResponse 政策仅支持 CX 版本。

故障变量

只要政策中存在执行错误，Apigee 就会生成错误消息。您可以在错误响应中查看这些错误消息。很多时候，系统生成的错误消息可能与您的产品上下文无关。您可能希望根据错误类型自定义错误消息，以使消息更有意义。

如需自定义错误消息，可以使用故障规则或 RaiseFault 政策。如需了解故障规则与 RaiseFault 政策之间的差异，请参阅 FaultRule 与 RaiseFault 政策。您必须使用故障规则和 RaiseFault 政策中的 Condition 元素来检查条件。Apigee 提供每个政策独有的故障变量，并在政策触发运行时错误时设置故障变量的值。通过使用这些变量，您可以检查特定的错误情况并采取适当的操作。如需详细了解如何检查错误条件，请参阅构建条件。

下表介绍了特定于此政策的故障变量。

变量 地点 示例
fault.name="FAULT_NAME" FAULT_NAME 是故障名称，如运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "UnresolvedVariable"
setdialogflowresponse.POLICY_NAME.failed POLICY_NAME 是抛出故障的政策的用户指定名称。 setdialogflowresponse.My-Set-Dialogflow-Response.failed = true
如需详细了解政策错误，请参阅您需要了解的政策错误相关信息。

相关主题

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