Política ParseDialogflowRequest

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

Confira a documentação da Apigee Edge.

Ícone da política

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.

<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:
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 além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão N/A
Obrigatório? Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo String
Elemento pai <PolicyElement>
Elemento filho Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

O elemento <DisplayName> não tem atributos ou elementos filhos.

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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Causa Corrigir
steps.parsedialogflowrequest.InvalidSessionInfo 500 Esse erro ocorrerá se houver um campo sessionInfo.session inválido em uma solicitação do Dialogflow. Um webhook pode usar esse campo para identificar uma sessão. Para informações sobre o formato de sessão compatível, consulte Class SessionInfo.
steps.parsedialogflowrequest.MalformedInput 500 Este erro ocorre quando o JSON fornecido para esta política é inválido ou está incorreto.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Nome do erro Causa Corrigir
UnsupportedOperation Este erro ocorrerá se você tiver especificado a versão incompatível do Dialogflow no elemento DialogflowVersion. A política ParseDialogflowRequest é compatível apenas com a versão CX.

Variáveis de falha

Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.

Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte FaultRules vs. a política RaiseFault. Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault. A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução. Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de erro, consulte Como criar condições.

A tabela a seguir descreve as variáveis de falha específicas da política.

Variáveis Onde Exemplo
fault.name="FAULT_NAME" FAULT_NAME é o nome da falha, conforme listado na tabela Erros do ambiente de execução. O nome da falha é a última parte do código de falha. fault.name Matches "UnresolvedVariable"
ParseDialogflowRequest.POLICY_NAME.failed POLICY_NAME é o nome da política especificada pelo usuário que gerou a falha. ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true
Para mais informações sobre erros de política, consulte O que você precisa saber sobre erros de política.

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.