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>

定義 ParseDialogflowRequest 政策。

預設值 不適用
是否必要？ 必填
類型 複雜物件
上層元素 N/A
子元素 <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> 元素中指定的前置字串 (my-prefix)。

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

屬性 預設 是否必要？ 說明
name 不適用 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
enabled 是 選用 設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 此屬性已淘汰。

子元素參照

本節將說明 <ParseDialogflowRequest> 的子元素。

<DisplayName>

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

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

預設值 不適用
是否必要？ 選用
類型 字串
上層元素 N/A
子元素 無
<DialogflowVersion> 元素使用以下語法：

語法

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

範例

以下範例會將 DialogflowVersion 設為 CX：

<DialogflowVersion>CX</DialogflowVersion>

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
steps.parsedialogflowrequest.InvalidSessionInfo 500 如果 Dialogflow 要求中含有無效的 sessionInfo.session 欄位，就會發生這個錯誤。Webhook 可以使用這個欄位來識別工作階段。如要瞭解支援的工作階段格式，請參閱 SessionInfo 類別。
steps.parsedialogflowrequest.MalformedInput 500 如果您向這項政策提供的 JSON 無效或格式不正確，就會發生這個錯誤。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
UnsupportedOperation 如果您在 DialogflowVersion 元素中指定不支援的 Dialogflow 版本，就會發生這項錯誤。ParseDialogflowRequest 政策僅支援 CX 版本。

錯誤變數

每當政策發生執行錯誤時，Apigee 就會產生錯誤訊息。您可以在錯誤回應中查看這些錯誤訊息。很多時候，系統產生的錯誤訊息可能與產品情境無關。您可能會根據錯誤類型自訂錯誤訊息，讓訊息更有意義。

如要自訂錯誤訊息，您可以使用錯誤規則或 RaiseFault 政策。如要瞭解錯誤規則和 RaiseFault 政策的差異，請參閱 FaultRules 與 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
如要進一步瞭解政策錯誤，請參閱「關於政策錯誤的相關資訊」。

相關主題

Apigee GitHub 上提供 Apigee 代理程式和共用流程的參考實作項目，可供您瞭解如何使用 ParseDialogflowRequest 政策。詳情請參閱「對話式 AI 參考實作」。