Règle ParseDialogflowRequest

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

Présentation

La règle "ParseDialogflowRequest" facilite l'intégration de Dialogflow à Apigee. Pour en savoir plus, consultez la page Intégrer Apigee à Contact Center AI.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

La règle "ParseDialogflowRequest" traite la requête WebhookRequest à partir d'un agent Dialogflow avant d'envoyer les données de requête à vos systèmes backend. La règle extrait les données de "WebhookRequest" dans les variables de flux qui sont disponibles pour toute la durée de l'appel d'API. Vous pouvez utiliser les variables dans vos appels, recherches ou logiques orchestrée ultérieurs. Cette règle est particulièrement utile si vous souhaitez que l'agent Dialogflow interagisse avec vos anciens systèmes backend. Avant d'envoyer les données de l'agent aux systèmes backend, vous pouvez les analyser et les structurer de manière à ce que vos systèmes backend puissent les utiliser.

Si vous êtes un intégrateur de services de backend, vous n'avez pas besoin de comprendre le format de la requête Webhook Dialogflow. La règle "ParseDialogflowRequest" prête à l'emploi gère le traitement des données de la requête de manière transparente.

Pour accéder à la requête "WebhookRequest" de votre agent Dialogflow dans Apigee, vous devez définir l'URL de webhook (fulfillment) de l'agent sur le point de terminaison du proxy (ProxyEndPoint) que vous avez configuré dans Apigee. Le point de terminaison du proxy doit être accessible au public. Pour en savoir plus, consultez la section Conditions requises pour le service de webhook.

<ParseDialogflowRequest>

Définit une règle "ParseDialogflowRequest".

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Objet complexe
Élément parent N/A
Éléments enfants <DialogflowVersion>
<DisplayName>
<VariablePrefix>

Le tableau suivant fournit une description détaillée des éléments enfants spécifiques à la règle "ParseDialogflowRequest" :

Élément enfant Obligatoire ? Description
<VariablePrefix> Facultatif Spécifie un préfixe personnalisé pour les variables de flux.
<DialogflowVersion> Facultatif Spécifie la version de Dialogflow.

Exemple

L'exemple suivant montre un exemple de requête de webhook, la règle ParseDialogflowRequest correspondante et les variables de flux générées après l'application de la règle :

Syntaxe

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

Requête de webhook

L'exemple suivant montre la requête webhook (au format JSON) d'un agent 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
  }
}

Pour afficher les différents champs que vous pouvez configurer dans la requête, consultez la section WebhookRequest.

Passez à l'exemple suivant pour voir la configuration de la règle "ParseDialogflowRequest".

Règle 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>

Accédez à l'exemple suivant pour afficher les variables de flux créées par la règle.

Variables de flux

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

Toutes les variables de flux générées commencent par google.dialogflow suivi du préfixe (my-prefix), comme spécifié dans l'élément <VariablePrefix>.

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError faux Facultatif Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

Référence d'élément enfant

Cette section décrit les éléments enfants de <ParseDialogflowRequest>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut N/A
Obligatoire ? Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type Chaîne
Élément parent <PolicyElement>
Éléments enfants Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<VariablePrefix>

Spécifie un préfixe personnalisé pour les variables de flux. La valeur spécifiée dans cet élément est précédée de tous les noms de variables générés par la règle ParseDialogflowRequest. Par défaut, toutes les variables générées par la règle sont précédées du préfixe google.dialogflow. Si vous avez spécifié l'élément VariablePrefix, votre préfixe personnalisé est ajouté après google.dialogflow. Par conséquent, le nom de la variable commence par google.dialogflow.CUSTOM_PREFIX.

Si vous ne spécifiez pas l'élément VariablePrefix, le nom de la variable n'est précédé que de google.dialogflow.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent <ParseDialogflowRequest>
Éléments enfants Aucun
L'élément <VariablePrefix> utilise la syntaxe suivante :

Syntaxe

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

Exemple

L'exemple suivant définit "VariablePrefix" sur my-prefix :

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

Conformément à cette configuration, tous les noms de variables commencent par google.dialogflow.my-custom-prefix.

<DialogflowVersion>

Spécifie la version de Dialogflow. La règle ParseDialogflowRequest n'est compatible qu'avec la version CX. Si vous ne spécifiez pas cet élément dans votre règle, la version par défaut est CX.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent N/A
Éléments enfants Aucun
L'élément <DialogflowVersion> utilise la syntaxe suivante :

Syntaxe

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

Exemple

L'exemple suivant définit "DialogflowVersion" sur CX :

<DialogflowVersion>CX</DialogflowVersion>

Codes d'erreur

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause Corrigé
steps.parsedialogflowrequest.InvalidSessionInfo 500 Cette erreur se produit si un champ "sessionInfo.session" est incorrect dans une requête Dialogflow. Un Webhook peut utiliser ce champ pour identifier une session. Pour en savoir plus sur le format de session compatible, consultez la page Classe SessionInfo.
steps.parsedialogflowrequest.MalformedInput 500 Cette erreur se produit lorsque le code JSON fourni à cette stratégie est incorrect ou non valide.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Cause Corrigé
UnsupportedOperation Cette erreur se produit si vous avez spécifié une version de Dialogflow non compatible dans l'élément DialogflowVersion. La règle "ParseDialogflowRequest" n'est compatible qu'avec la version CX.

Variables de panne

Chaque fois qu'une règle comporte des erreurs d'exécution, Apigee génère des messages d'erreur. Vous pouvez afficher ces messages d'erreur dans la réponse d'erreur. Souvent, les messages d'erreur générés par le système peuvent ne pas être pertinents dans le contexte de votre produit. Vous pouvez personnaliser les messages d'erreur en fonction du type d'erreur pour rendre les messages plus significatifs.

Pour personnaliser les messages d'erreur, vous pouvez utiliser des règles d'erreur ou la règle RaiseFault. Pour en savoir plus sur les différences entre les règles d'erreur et la règle RaiseFault, consultez la section Règles d'erreur et règle RaiseFault. Vous devez vérifier les conditions à l'aide de l'élément Condition dans les règles d'erreur et dans la règle RaiseFault. Apigee fournit des variables d'erreur propres à chaque règle et les valeurs des variables d'erreur sont définies lorsqu'une règle déclenche des erreurs d'exécution. En utilisant ces variables, vous pouvez vérifier des conditions d'erreur spécifiques et prendre les mesures appropriées. Pour en savoir plus sur la vérification des conditions d'erreur, consultez la page Conditions de création.

Le tableau suivant décrit les variables d'erreur spécifiques à cette règle.

Variables Lieu Exemple
fault.name="FAULT_NAME" FAULT_NAME est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "UnresolvedVariable"
ParseDialogflowRequest.POLICY_NAME.failed POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true
Pour en savoir plus sur les erreurs de règles, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Articles associés

Les mises en œuvre de référence des proxys Apigee et des flux partagés montrant l'utilisation de la règle "ParseDialogflowRequest" sont disponibles sur Apigee GitHub. Pour en savoir plus, consultez la page Implémentations de référence pour l'IA conversationnelle.