SetDialogflowResponse 政策

可擴充的政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

SetDialogflowResponse 政策可協助您將 Dialogflow 與 Apigee 整合。詳情請參閱「將 Apigee 與 Contact Center AI 整合」。

SetDialogflowResponse 政策會處理後端系統的回應資料並設定格式，然後將資料做為 WebhookResponse 傳送至 Dialogflow 代理程式。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> 的父項元素。定義要在 Webhook 回應中設定的一組自然語言片語。
<Ref>	選用	擷取指定參照變數的值。
<Value>	選用	為指定參數設定自訂文字。

範例

以下範例顯示 SetDialogflowResponse 政策範例，以及傳送至 Dialogflow 代理程式的 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 policy

以下範例顯示 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>

請參閱下一個範例，瞭解這項政策建立的 Webhook 回應。

Webhook 回應

以下範例顯示傳送至 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> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async	false	已淘汰	此屬性已淘汰。

子元素參照

本節說明 <SetDialogflowResponse> 的子元素。

<DisplayName>

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

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

範例

以下範例會將來源設為 myMessageVar：

<Source>myMessageVar</Source>

<DialogflowVersion>

指定 Dialogflow 版本。SetDialogflowResponse 政策僅支援 CX 版本。如未在政策中指定這個元素，版本預設為 CX。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<SetDialogflowResponse>
子元素	無

<DialogflowVersion> 元素使用下列語法：

語法

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

範例

以下範例會將 DialogflowVersion 設為 CX：

<DialogflowVersion>CX</DialogflowVersion>

<IgnoreUnresolvedVariables>

判斷遇到無法解析的變數時，是否停止處理。

預設值	是
必填與否	選用
類型	布林值
父項元素	<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>
       

設定自訂文字

本範例會將 responder 參數的值設為 SYSTEM。

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

<Phrases>

<Phrase> 的父項元素。定義要在 Webhook 回應中設定的自然語言片語排序清單。

預設值	不適用
必填與否	選用
類型	複雜物件
父項元素	<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> 元素的屬性如下：

屬性	說明	是否必填？	類型
名稱	指定要從哪個回應標頭擷取值。	必填	字串

<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 Proxy 和共用流程的參考實作，瞭解如何使用 SetDialogflowResponse 政策，請前往 Apigee GitHub。詳情請參閱「對話式 AI 參考實作」。