Criterio ParseDialogflowRequest

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Il criterio ParseDialogflowRequest facilita l'integrazione di Dialogflow con Apigee. Per ulteriori informazioni, consulta la pagina Integrazione di Apigee con Contact Center AI.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Il criterio ParseDialogflowRequest elabora WebhookRequest da un agente Dialogflow prima di inviare i dati della richiesta ai tuoi sistemi di backend. Il criterio estrae i dati da WebhookRequest nelle variabili di flusso disponibili per tutta la durata della chiamata API. Puoi utilizzare le variabili nei successivi callout, ricerche o logica orchestrata. Questo criterio è particolarmente utile se vuoi che l'agente Dialogflow interagisca con i tuoi sistemi backend legacy. Prima di inviare i dati dell'agente ai sistemi di backend, puoi analizzarli e strutturarli in modo che possano essere utilizzati dai tuoi sistemi di backend.

Se sei un integratore di servizio di backend, non devi perdere tempo a capire il formato di Dialogflow WebhookRequest. Il criterio ParseDialogflowRequest predefinito gestisce l'elaborazione dei dati della richiesta in modo semplice.

Per accedere a WebhookRequest dell'agente Dialogflow in Apigee, devi impostare l'URL webhook (fulfillment) dell'agente su ProxyEndpoint che hai configurato in Apigee. ProxyEndPoint deve essere accessibile pubblicamente. Per maggiori informazioni, consulta Requisiti del servizio webhook.

NOTA: il criterio ParseDialogflowRequest analizza solo gli oggetti fulfillmentInfo.tag, sentimentAnalysisResult e sessionInfo nella richiesta Dialogflow.

<ParseDialogflowRequest>

Definisce una policy ParseDialogflowRequest.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Oggetto complesso
Elemento principale	N/D
Elementi secondari	<DialogflowVersion> <DisplayName> <VariablePrefix>

La tabella seguente fornisce una descrizione di alto livello degli elementi secondari specifici del criterio ParseDialogflowRequest:

Elemento secondario	Obbligatorio?	Descrizione
<VariablePrefix>	Facoltativo	Specifica un prefisso personalizzato per le variabili di flusso.
<DialogflowVersion>	Facoltativo	Specifica la versione di Dialogflow.

Esempio

L'esempio seguente mostra una richiesta webhook di esempio, la policy ParseDialogflowRequest corrispondente e le variabili di flusso generate dopo l'applicazione della policy:

Sintassi

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

Richiesta webhook

L'esempio seguente mostra la richiesta webhook (in formato JSON) da un agente Dialogflow.

{
    "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
  }
}

Per visualizzare i vari campi che puoi configurare nella richiesta, consulta WebhookRequest.

Vai all'esempio successivo per visualizzare la configurazione del criterio ParseDialogflowRequest.

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

Vai all'esempio successivo per visualizzare le variabili di flusso create dalla policy.

Variabili di flusso

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

Tutte le variabili di flusso generate iniziano con google.dialogflow seguito dal prefisso (my-prefix) specificato nell'elemento <VariablePrefix>.

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError	falso	Facoltativo	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente
enabled	true	Facoltativo	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async	falso	Ritirato	Questo attributo è stato ritirato.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <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>

Specifica un prefisso personalizzato per le variabili di flusso. Il valore specificato in questo elemento viene aggiunto come prefisso a tutti i nomi delle variabili generati dal criterio ParseDialogflowRequest. Per impostazione predefinita, tutte le variabili generate dai criteri hanno il prefisso google.dialogflow. Se hai specificato l'elemento VariablePrefix, il prefisso personalizzato viene aggiunto dopo google.dialogflow. Pertanto, il nome della variabile inizia con google.dialogflow.CUSTOM_PREFIX.

Se non specifichi l'elemento VariablePrefix, il nome della variabile ha come prefisso solo google.dialogflow.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<ParseDialogflowRequest>
Elementi secondari	Nessuno

L'elemento <VariablePrefix> utilizza la seguente sintassi:

Sintassi

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

Esempio

L'esempio seguente imposta VariablePrefix su my-prefix:

<VariablePrefix>my-custom-prefix</VariablePrefix>

In base a questa configurazione, tutti i nomi delle variabili iniziano con google.dialogflow.my-custom-prefix.

<DialogflowVersion>

Specifica la versione di Dialogflow. Il criterio ParseDialogflowRequest supporta solo la versione CX. Se non specifichi questo elemento nel criterio, la versione predefinita è CX.

Valore predefinito	N/D
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	N/D
Elementi secondari	Nessuno

L'elemento <DialogflowVersion> utilizza la seguente sintassi:

Sintassi

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

Esempio

L'esempio seguente imposta DialogflowVersion su CX:

<DialogflowVersion>CX</DialogflowVersion>

Codici di errore

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.

Argomenti correlati

Le implementazioni di riferimento dei proxy Apigee e dei flussi condivisi che mostrano l'utilizzo del criterio ParseDialogflowRequest sono disponibili su Apigee GitHub. Per ulteriori informazioni, vedi Implementazioni di riferimento dell'IA conversazionale.