Guide sur le développement de webhooks Dialogflow CX

Les webhooks Dialogflow CX peuvent être développés à l’aide des fonctions Google Cloud ou d’un point de terminaison d’API REST. La fonction Google Cloud Function est la mise en œuvre par Google des fonctions sans serveur disponibles dans GCP. Google recommande d’utiliser les fonctions Google Cloud Function pour le développement de Dialogflow CX.

Dans cet article, nous allons implémenter un agent Dialogflow CX en utilisant Golang, Protobuf et Google Cloud Functions. Ce projet est essentiellement un « Hello, World! » Exemple.

Ce message contient des matériaux de différentes ressources qui peuvent être vus dans la section des ressources.

Conditions préalables

Voici les technologies utilisées dans ce projet :

Compte Google Cloud
API Dialogflow activée
interface de ligne de commande gcloud
Interface de ligne de commande Dialogflow CX
Golang v1.19 ou supérieur
Code Visual Studio
Dialogflow CX pour Golang (version >=1.23.0)
jupe

L’interface de ligne de commande Google Cloud (gcloud CLI) est un outil qui vous permet de gérer vos fonctions sans serveur Google Cloud et les ressources associées. cxcli L’interface de ligne de commande vous permet de gérer les agents Dialogflow CX par programmation à partir de la ligne de commande. Nous utiliserons ces outils puissants pour créer, construire, déployer et gérer notre agent Hello World Dialogflow CX. Commençons!

Créer l’agent Dialogflow CX avec la console

Pour créer l’agent Dialogflow CX, vous devez accéder à la console Dialogflow CX et créer un agent. Une fois que vous avez créé votre agent, vous verrez la vue de conception :

Et c’est tout! Avec ces étapes, vous avez créé votre premier agent Dialogflow CX. Vous n’avez qu’à déployer vos modifications locales. Nous allons l’expliquer dans les prochaines étapes.

Fichiers de projet

Voici les principaux fichiers du projet :

├── cmd
│   └── main.go
├── function.go
├── go.mod
└── go.sum

cmd: Le dossier qui contient tout ce dont nous avons besoin pour démarrer un serveur local pour le débogage
- main.go: Fichier contenant un main() méthode et exécute un serveur local écoutant dans le port 8080
function.go: Le point d’entrée principal de Google Cloud Function
go.mod: Ce fichier est au cœur de l’écosystème Golang et constitue un élément de base pour comprendre et travailler avec Golang.
go.sum: Ce fichier répertorie la somme de contrôle des dépendances directes et indirectes requises avec la version.

Fonction Google Cloud dans Golang

Le SDK Dialogflow CX pour Golang vous permet de créer plus facilement des conversations Dialogflow CX très engageantes en vous permettant de passer plus de temps à mettre en œuvre des fonctionnalités et moins de temps à écrire du code passe-partout.

Vous pouvez trouver de la documentation, des exemples et des liens utiles dans leur référentiel GitHub officiel lié dans la section Ressources à la fin de cet article.

Le fichier Golang principal de notre projet Google Cloud Function est function.go situé dans le dossier racine. Ce fichier contient tous les gestionnaires.

Les HandleWebhookRequest La fonction est exécutée chaque fois que Dialogflow CX appelle le webhook.


// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
    var request cx.WebhookRequest
    var response cx.WebhookResponse
    var err error

    // Read input JSON
    body, err := ioutil.ReadAll(r.Body)
    if err != nil {
        handleError(w, err)
        return
    }

    unmarshal := protojson.UnmarshalOptions{
        AllowPartial:   true,
        DiscardUnknown: true,
    }

    // Unmarshal from the protobuf struct
    if err = unmarshal.Unmarshal(body, &request); err != nil {
        handleError(w, err)
        return
    }

    log.Printf("Request: %+v", request)

    // Execute the response
    response, err = webhookResponse(request)

    if err != nil {
        handleError(w, err)
        return
    }
    log.Printf("Response: %+v", response)

    marshal := protojson.MarshalOptions{
        AllowPartial: true,
    }

    // Marshal from the protobuf struct
    bytes, err := marshal.Marshal(&response)
    if err != nil {
        handleError(w, err)
        return
    }

    // Send response
    if _, err = w.Write(bytes); err != nil {
        handleError(w, err)
        return
    }

}

Il est important de noter ici que pour avoir une meilleure expérience de développement, nous utilisons protobuf structs du SDK Dialogflow CX. C’est pourquoi nous organisons et désorganisons en utilisant le protojson une bibliothèque.

Déployer votre webhook Dialogflow CX

Une fois le code prêt à l’emploi, nous devons le déployer sur Google Cloud afin qu’il puisse être connecté à l’agent.

Avant de continuer, assurez-vous que vous avez activé l’API Cloud Functions :

gcloud services enable cloudfunctions.googleapis.com

Nous pouvons maintenant déployer notre webhook avec gcloud CLI sur le dossier racine :

gcloud functions deploy my-agent-function --runtime go119 --trigger-http --entry-point HandleWebhookRequest

Le point de terminaison public de cette fonction va avoir ce format :

https://<region>-<project-id>.cloudfunctions.net/<function-name>

Imaginons donc que nous ayons déployé cette fonction dans us-central1 et le projet test-cx-346408l’URL ressemblera à ceci :

https://us-central1-test-cx-346408.cloudfunctions.net/my-agent-function

Le code est maintenant prêt à être testé sur la console !

Console d’expérience client Dialogflow

Tester votre agent Dialogflow CX

Une fois que vous avez déployé vos modifications, vous pouvez accéder à votre agent Dialogflow CX sur la console et créer un webhook :

Une fois que vous avez ajouté votre webhook dans votre agent, vous pouvez accéder à n’importe quel flux et le définir là où vous en avez besoin. Ensuite, il vous suffit de le tester dans le simulateur !

Local

Construire le webhook Dialoglfow CX

À l’intérieur go.mod, on trouvera presque toujours des métadonnées spécifiques au projet. Ces métadonnées aident à identifier le projet et servent de base aux utilisateurs et aux contributeurs pour obtenir des informations sur le projet.

Voici à quoi ressemble ce fichier :


module dialogflow.cx/cloudfunction

go 1.16

require (
    cloud.google.com/go/dialogflow v1.26.0
    google.golang.org/protobuf v1.28.1
)

Pour télécharger nos dépendances webhook, nous pouvons exécuter la commande suivante :


go mod tidy

Cette commande installe un package et tous les packages dont il dépend. Si le colis contient un aller.somme fichier, l’installation des dépendances sera pilotée par cela.

Pour créer le webhook, exécutez simplement :


go build -o webhook .

Exécuter le webhook Dialogflow CX

Les launch.json déposer dans .vscode dossier a la configuration pour Visual Studio Code qui nous permet d’exécuter notre lambda localement :


{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run function",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/cmd/main.go",
            "env": {
                "ENV": "development"
            }
        }
    ]
}

Ce fichier de configuration exécutera la commande suivante :


dlv dap --listen=127.0.0.1:52462 --log-dest=3 from /Users/xavierportillaedo/Documents/personal/repos/dialogflow-cx-webhook-go/cmd

Pour une nouvelle requête entrante, un nouveau serveur est en cours d’exécution à l’écoute du port 8080. À partir des données reçues sur le serveur, le corps de la requête est extrait, analysé en JSON et transmis au gestionnaire de fonctions sans serveur de l’invocateur du webhook. La réponse de la fonction sans serveur lambda est analysée au format Dialogflow CX Protobuf, comme spécifié ici. La réponse est écrite sur le serveur et renvoyée.

Après avoir configuré notre lancement.json fichier et comprendre le fonctionnement du débogueur local, il est temps de cliquer sur le bouton de lecture :

Après l’avoir exécuté, vous pouvez envoyer des requêtes POST Dialogflow CX à http://localhost:8080.

Tester les requêtes localement

Je suis sûr que vous connaissez déjà le célèbre outil appelé Postman. Les API REST sont devenues la nouvelle norme pour fournir une interface publique et sécurisée pour votre service. Bien que REST soit devenu omniprésent, il n’est pas toujours facile de le tester. Postman facilite le test et la gestion des API REST HTTP. Postman nous offre plusieurs fonctionnalités pour importer, tester et partager des API, ce qui vous aidera, vous et votre équipe, à être plus productifs à long terme.

Après avoir exécuté votre application, vous aurez un point de terminaison disponible sur http://localhost:8080. Avec Postman, vous pouvez émuler n’importe quelle requête Dialogflow CX.

Par exemple, vous pouvez tester cette requête :


{
   "detectIntentResponseId":"dsfsdaf-c5c9-46ce-bf2c-935396c08926",
   "intentInfo":{
      "lastMatchedIntent":"projects/my-project-123/locations/us-central1/agents/sddadsa-576c-4bbb-bc27-34c276bfecd5/intents/00000000-0000-0000-0000-000000000000",
      "displayName":"Default Welcome Intent",
      "confidence":0.6684057
   },
   "pageInfo":{
      "currentPage":"projects/my-project-123/locations/us-central1/agents/sadasd-d5fc-4eb7-88fc-c25169027aee/flows/68f7790d-5c1f-4546-bb53-8d641f8288b4/pages/21939010-3336-450d-ae8b-0c9926aec791",
      "formInfo":{
         "parameterInfo":[
            {
               "displayName":"pokemon",
               "required":true,
               "state":"FILLED",
               "value":"pikachu"
            }
         ]
      }
   },
   "sessionInfo":{
      "session":"projects/my-project-123/locations/us-central1/agents/sadasd-d5fc-4eb7-88fc-c25169027aee/sessions/7fab78-aac-10e-989-d99313ca4",
      "parameters":{
         "pokemon":"pikachu"
      }
   },
   "fulfillmentInfo":{
      "tag":"test"
   },
   "text":"Hi!",
   "languageCode":"en"
}

La réponse de cet exemple de webhook sera celle-ci :

{
  "fulfillmentResponse": {
    "messages": [
      {
        "text": {
          "text": [
            "hi from the webhook!"
          ]
        }
      }
    ],
    "mergeBehavior": "REPLACE"
  },
  "sessionInfo": {
    "parameters": {
      "key": "value"
    }
  }
}

Déboguer le webhook Dialogflow CX

En suivant les étapes précédentes, vous pouvez maintenant configurer des points d’arrêt où vous voulez dans tous les fichiers Golang afin de déboguer votre webhook :

Hybride

Demandes de transfert de port directement depuis la console Dialogflow CX vers votre ordinateur portable

ngrok est un outil très cool et léger…