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	可选	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障
enabled	true	可选	设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async	false	已弃用	此属性已弃用。

子元素参考

本部分介绍 <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>

<Header>

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

• 要将标头值提取为自然语言响应，请在 <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。

错误代码

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
steps.setdialogflowresponse.ExecutionFailed	500	This error occurs when the execution of the policy failed because of a generic exception. The fault message has the details of the exception.
steps.setdialogflowresponse.InvalidSourceType	500	This error occurs if the variable specified in the <Source> element is not of message type.
steps.setdialogflowresponse.MalformedInput	500	This error occurs when the JSON provided to this policy is invalid or malformed.
steps.setdialogflowresponse.SourceMessageNotAvailable	500	This error occurs if the message variable specified in the Source element of the policy is either: Out of scope (not available in the specific flow where the policy is executed) or Can't be resolved (is not defined)
steps.setdialogflowresponse.UnresolvedHeader	500	This error occurs if the Header element has an invalid header. For example, if the Header element has the value X-Response-Text, and there is no X-Response-Text in the response header, you will get this error.
steps.setdialogflowresponse.UnresolvedJSONPath	500	This error occurs if the JSONPath element has an invalid path. For example, if the JSONPath element has the value {claim.status.value}, and there is no status object in the JSON payload, you will get this error.
steps.setdialogflowresponse.UnresolvedVariable	500	This error occurs if a variable specified in the SetDialogflowResponse policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)

Deployment errors

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

Error name	Cause
UnsupportedOperation	This error occurs if you have specified unsupported Dialogflow version in the DialogflowVersion element. The SetDialogflowResponse policy supports only the 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"
setdialogflowresponse.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	setdialogflowresponse.My-Set-Dialogflow-Response.failed = true

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

相关主题

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