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 網址 (執行要求) 設為您在 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 policy

<?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> 元素中指定的前置字串 (my-prefix)。

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
name	不適用	必要	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 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 Proxy 和共用流程的參考實作，說明如何使用 ParseDialogflowRequest 政策。詳情請參閱對話式 AI 參考實作。