Política ParseDialogflowRequest

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visão geral

A política ParseDialogflowRequest facilita a integração do Dialogflow com a Apigee. Para mais informações, consulte Como integrar a Apigee ao Contact Center AI.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

A política ParseDialogflowRequest processa a WebhookRequest de um agente do Dialogflow antes de enviar os dados da solicitação para os sistemas de back-end. A política extrai dados da WebhookRequest para as variáveis de fluxo disponíveis para você durante a chamada de API inteira. Use as variáveis nas chamadas, pesquisas ou lógicas orquestradas subsequentes. Essa política é útil principalmente se você quiser que o agente do Dialogflow interaja com os sistemas de back-end legados. Antes de enviar os dados do agente para os sistemas de back-end, analise e estruture os dados de modo que os sistemas de back-end possam consumir.

Se você é um integrador de serviço de back-end, não é necessário gastar tempo entendendo o formato da WebhookRequest do Dialogflow. A política ParseDialogflowRequest pronta para uso lida com o processamento dos dados da solicitação de maneira integrada.

Para acessar a WebhookRequest do agente do Dialogflow na Apigee, é necessário definir o URL do webhook (fulfillment) do agente como o ProxyEndPoint que você configurou na Apigee. O ProxyEndPoint precisa estar acessível publicamente. Para mais informações, consulte Requisitos de serviço do webhook.

OBSERVAÇÃO: a política ParseDialogflowRequest analisa apenas os objetos fulfillmentInfo.tag, sentimentAnalysisResult e sessionInfo na solicitação do Dialogflow.

<ParseDialogflowRequest>

Define uma política ParseDialogflowRequest.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	<DialogflowVersion> <DisplayName> <VariablePrefix>

A tabela a seguir apresenta uma descrição de alto nível dos elementos-filhos específicos da política ParseDialogflowRequest:

Elemento filho	Obrigatório?	Descrição
<VariablePrefix>	Opcional	Especifica um prefixo personalizado para as variáveis de fluxo.
<DialogflowVersion>	Opcional	Especifica a versão do Dialogflow.

Exemplo

O exemplo a seguir mostra uma solicitação de webhook de amostra, a política ParseDialogflowRequest correspondente e as variáveis de fluxo geradas após a aplicação da política:

Sintaxe

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

Solicitação de webhook

O exemplo a seguir mostra a solicitação de webhook (no formato JSON) de um agente do 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
  }
}

Para visualizar os vários campos que podem ser configurados na solicitação, consulte WebhookRequest.

Vá para a próxima amostra para ver a configuração da política ParseDialogflowRequest.

Política 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>

Vá para a próxima amostra para ver as variáveis de fluxo criadas pela política.

Variáveis de fluxo

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

Todas as variáveis de fluxo geradas começam com google.dialogflow seguido do prefixo (my-prefix), conforme especificado no elemento <VariablePrefix>.

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <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>

Especifica um prefixo personalizado para as variáveis de fluxo. O valor especificado nesse elemento é prefixado para todos os nomes de variáveis gerados pela política ParseDialogflowRequest. Por padrão, todas as variáveis geradas pela política são prefixadas com google.dialogflow. Se você tiver especificado o elemento VariablePrefix, o prefixo personalizado será adicionado depois de google.dialogflow. Portanto, o nome da variável começa com google.dialogflow.CUSTOM_PREFIX.

Se você não especificar o elemento VariablePrefix, o nome da variável será prefixado apenas com google.dialogflow.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	<ParseDialogflowRequest>
Elemento filho	Nenhuma

O elemento <VariablePrefix> usa a seguinte sintaxe:

Sintaxe

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

Exemplo

O exemplo a seguir define a VariablePrefix como my-prefix:

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

De acordo com essa configuração, todos os nomes de variáveis começam com google.dialogflow.my-custom-prefix.

<DialogflowVersion>

Especifica a versão do Dialogflow. A política ParseDialogflowRequest é compatível apenas com a versão CX. Se você não especificar esse elemento na sua política, a versão padrão será CX.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	N/A
Elemento filho	Nenhuma

O elemento <DialogflowVersion> usa a seguinte sintaxe:

Sintaxe

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

Exemplo

O exemplo a seguir define a DialogflowVersion como CX:

<DialogflowVersion>CX</DialogflowVersion>

Códigos de erro

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.

Temas relacionados

As implementações de referência de proxies da Apigee e fluxos compartilhados que mostram o uso da política ParseDialogflowRequest estão disponíveis no GitHub da Apigee. Para mais informações, consulte Implementações de referências do Conversation AI.