Certains produits et fonctionnalités sont en cours de changement de nom. Les fonctionnalités de playbook et de flux génératifs sont également en cours de migration vers une console unique. Consultez les détails.

Cette page a été traduite par l'API Cloud Translation.

Implémenter des webhooks

Ce guide fournit différents exemples d'implémentation de webhooks, ainsi que des recommandations de dépannage pour les webhooks.

Définir un paramètre de session

Les exemples suivants montrent comment définir un paramètre de session.

Go

Pour vous authentifier auprès de Dialogflow, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Consultez le guide de démarrage rapide des webhooks.

Java


// TODO: Change class name to Example
// TODO: Uncomment the line below before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import java.io.BufferedWriter;

public class WebhookConfigureSessionParameters implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject orderParameter = new JsonObject();
    orderParameter.addProperty("order_number", "12345");

    JsonObject parameterObject = new JsonObject();
    parameterObject.add("parameters", orderParameter);

    // Creates webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("session_info", parameterObject);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /** { "session_info": { "parameters": { "order_number": "12345" } } } */
    BufferedWriter writer = response.getWriter();
    // Sends the webhookResponseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

const functions = require('@google-cloud/functions-framework');

functions.http('configureSessionParams', (request, response) => {
  // Session parameter configured by the webhook
  const orderNumber = 123;

  const jsonResponse = {
    sessionInfo: {
      parameters: {
        orderNumber: orderNumber,
      },
    },
  };

  response.send(jsonResponse);
});

Python

import functions_framework

# TODO (developer): change entry point to configure_session_params in Cloud Function


@functions_framework.http
def configure_session_params(request):
    """Webhook to validate or configure new session parameters."""

    order_number = 123

    json_response = {
        "sessionInfo": {
            "parameters": {
                "orderNumber": order_number,
            },
        },
    }

    return json_response

Renvoyer une réponse de traitement

Les exemples suivants montrent comment renvoyer une réponse de traitement.

Go

Consultez le guide de démarrage rapide des webhooks.

Java


// TODO: Change class name to Example
// TODO: add GSON dependency to Pom file
// (https://mvnrepository.com/artifact/com.google.code.gson/gson/2.8.5)
// TODO: Uncomment the line bellow before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.BufferedWriter;

public class BasicWebhook implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    Gson gson = new GsonBuilder().create();
    JsonObject parsedRequest = gson.fromJson(request.getReader(), JsonObject.class);

    // For more information on the structure of this object https://cloud.google.com/dialogflow/cx/docs/reference/rest/v3/Fulfillment
    String requestTag = parsedRequest.getAsJsonObject("fulfillmentInfo")
        .getAsJsonPrimitive("tag").toString();
    JsonObject responseObject = null;
    String defaultIntent = "\"Default Welcome Intent\"";
    String secondIntent = "\"get-agent-name\"";
    String responseText = "";

    // Compares the Intent Tag to provide the correct response 
    if (requestTag.equals(defaultIntent)) {
      responseText = "\"Hello from a Java GCF Webhook\"";
    } else if (requestTag.equals(secondIntent)) {
      responseText = "\"My name is Flowhook\"";
    } else {
      responseText = "\"Sorry I didn't get that\"";
    }

    // Constructing the response jsonObject 
    responseObject =
        JsonParser
            .parseString(
                "{ \"fulfillment_response\": { \"messages\": [ { \"text\": { \"text\": ["
                    + responseText
                    + "] } } ] } }")
            .getAsJsonObject();
    BufferedWriter writer = response.getWriter();

    //Sends the responseObject
    writer.write(responseObject.toString());
  }
}

Node.js

const functions = require('@google-cloud/functions-framework');

functions.http('handleWebhook', (request, response) => {
  const tag = request.body.fulfillmentInfo.tag;
  let text = '';

  if (tag === 'Default Welcome Intent') {
    text = 'Hello from a GCF Webhook';
  } else if (tag === 'get-name') {
    text = 'My name is Flowhook';
  } else {
    text = `There are no fulfillment responses defined for "${tag}"" tag`;
  }

  const jsonResponse = {
    fulfillment_response: {
      messages: [
        {
          text: {
            //fulfillment text response to be sent to the agent
            text: [text],
          },
        },
      ],
    },
  };

  response.send(jsonResponse);
});

Python

import functions_framework

# TODO(developer): change entry point to handle_webhook in cloud function


@functions_framework.http
def handle_webhook(request):
    req = request.get_json()

    tag = req["fulfillmentInfo"]["tag"]

    if tag == "Default Welcome Intent":
        text = "Hello from a GCF Webhook"
    elif tag == "get-name":
        text = "My name is Flowhook"
    else:
        text = f"There are no fulfillment responses defined for {tag} tag"

    # You can also use the google.cloud.dialogflowcx_v3.types.WebhookRequest protos instead of manually writing the json object
    # Please see https://googleapis.dev/python/dialogflow/latest/dialogflow_v2/types.html?highlight=webhookresponse#google.cloud.dialogflow_v2.types.WebhookResponse for an overview
    res = {"fulfillment_response": {"messages": [{"text": {"text": [text]}}]}}

    # Returns json
    return res

Définir les paramètres du formulaire si nécessaire

Les exemples suivants montrent comment marquer un paramètre comme obligatoire.

Java


// TODO: Change class name to Example
// TODO: Uncomment the line below before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.io.BufferedWriter;

public class ConfigureWebhookToSetFormParametersAsOptionalOrRequired implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject parameterObject = new JsonObject();
    parameterObject.addProperty("display_name", "order_number");
    parameterObject.addProperty("required", "true");
    parameterObject.addProperty("state", "VALID");

    JsonArray parameterInfoList = new JsonArray();
    parameterInfoList.add(parameterObject);

    JsonObject parameterInfoObject = new JsonObject();
    parameterInfoObject.add("parameter_info", parameterInfoList);

    JsonObject formInfo = new JsonObject();
    formInfo.add("form_info", parameterInfoObject);

    // Constructs the webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("page_info", formInfo);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /* {
     *   "page_info": {
     *     "form_info": {
     *       "parameter_info": [
     *         {
     *           "display_name": "order_number",
     *           "required": "true",
     *           "state": "VALID"
     *         }
     *       ]
     *     }
     *   }
     * }
     */

    BufferedWriter writer = response.getWriter();

    // Sends the responseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

const functions = require('@google-cloud/functions-framework');

functions.http('configureOptionalFormParam', (request, response) => {
  // The value of the parameter that the webhook will set as optional or required.
  // Note that the webhook cannot add or remove any form parameter

  const jsonResponse = {
    pageInfo: {
      formInfo: {
        parameterInfo: [
          {
            displayName: 'order-number',
            // if required: false, the agent will not reprompt for this parameter, even if the state is 'INVALID'
            required: true,
            state: 'VALID',
          },
        ],
      },
    },
  };

  // Info about form parameter that is sent in the webhook response:
  console.log(
    'Parameter Info: \n',
    jsonResponse.pageInfo.formInfo.parameterInfo[0]
  );

  response.send(jsonResponse);
});

Valider un paramètre de formulaire

Les exemples suivants montrent comment valider un paramètre de formulaire.

Java


// TODO: Change class name to Example
// TODO: Uncomment the line below before running cloud function
// package com.example;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.io.BufferedWriter;

public class WebhookValidateFormParameter implements HttpFunction {
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject sessionInfo = new JsonObject();
    JsonObject sessionParameter = new JsonObject();

    sessionParameter.addProperty("order_number", "null");
    sessionInfo.add("parameters", sessionParameter);

    JsonObject parameterObject = new JsonObject();
    parameterObject.addProperty("display_name", "order_number");
    parameterObject.addProperty("required", "true");
    parameterObject.addProperty("state", "INVALID");
    parameterObject.addProperty("value", "123");

    JsonArray parameterInfoList = new JsonArray();
    parameterInfoList.add(parameterObject);

    JsonObject parameterInfoObject = new JsonObject();
    parameterInfoObject.add("parameter_info", parameterInfoList);

    JsonObject pageInfo = new JsonObject();
    pageInfo.add("form_info", parameterInfoObject);

    // Constructs the webhook response object
    JsonObject webhookResponse = new JsonObject();
    webhookResponse.add("page_info", pageInfo);
    webhookResponse.add("session_info", sessionInfo);

    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String jsonResponseObject = gson.toJson(webhookResponse);

    /**
     * { "page_info": { "form_info": { "parameter_info": [ { "display_name": "order_number",
     * "required": "true", "state": "INVALID", "value": "123" } ] } }, "session_info": {
     * "parameters": { "order_number": "null" } } }
     */
    BufferedWriter writer = response.getWriter();

    // Sends the responseObject
    writer.write(jsonResponseObject.toString());
  }
}

Node.js

const functions = require('@google-cloud/functions-framework');

functions.http('validateParameter', (request, response) => {
  // Webhook will validate or invalidate parameter based on logic configured by the user.
  // Access parameter values through the webhook request via `request.body.pageInfo.formInfo.parameterInfo[]`
  const jsonResponse = {
    page_info: {
      form_info: {
        parameter_info: [
          {
            displayName: 'orderNumber',
            required: true,
            state: 'INVALID',
            value: 123,
          },
        ],
      },
    },
    sessionInfo: {
      parameters: {
        // Set session parameter to null if the form parameter is 'INVALID' and your agent needs to reprompt the user
        orderNumber: null,
      },
    },
  };

  response.send(jsonResponse);
});

Python

import functions_framework


@functions_framework.http
def validate_parameter(request):
    """Webhook will validate or invalidate parameter based on logic configured by the user."""
    return {
        "page_info": {
            "form_info": {
                "parameter_info": [
                    {
                        "displayName": "orderNumber",
                        "required": True,
                        "state": "INVALID",
                        "value": 123,
                    },
                ],
            },
        },
        "sessionInfo": {
            "parameters": {
                # Set session parameter to None if the form parameter is 'INVALID' and your agent needs to reprompt the user
                "orderNumber": None,
            },
        },
    }

ID de session du journal

L'exemple suivant montre comment consigner le session ID à partir d'une requête webhook.

Python


import re

import functions_framework


@functions_framework.http
def log_session_id_for_troubleshooting(request):
    """Webhook will log session id corresponding to request."""

    req = request.get_json()
    # You can read more about SessionInfo at https://cloud.google.com/dialogflow/cx/docs/reference/rest/v3/SessionInfo
    # Use a regex pattern to get the session ID
    session_id_regex = r".+\/sessions\/(.+)"
    session = req["sessionInfo"]["session"]
    regex_match = re.search(session_id_regex, session)
    session_id = regex_match.group(1)

    # Instead of printing, use the logging tools available to you
    print(f"Debug Node: session ID = {session_id}")

    # Return a generic response
    res = {
        "fulfillment_response": {
            "messages": [{"text": {"text": [f"Request Session ID: {session_id}"]}}]
        }
    }

    # Returns json
    return res

Dépannage

Cycle de vie d'un appel webhook

Les appels de webhook sont toujours lancés par des agents de conversation (Dialogflow CX) et sont redirigés vers un serveur Web via HTTPS. Les appels de webhooks de service Web génériques proviennent d'une adresse IP Internet appartenant à Google et peuvent atteindre les serveurs Web (serveurs webhook) disponibles sur l'Internet public. En revanche, les webhooks de l'Annuaire des services commencent toujours à partir d'une adresse Google Cloud interne et ne peuvent atteindre que les serveurs webhook sur des réseaux privés dans Google Cloud.

Journaux utiles pour le débogage des webhooks

Le débogage des problèmes de webhook implique généralement de collecter les journaux Dialogflow Cloud Logging et les journaux du serveur webhook. Si le serveur webhook est implémenté à l'aide de fonctions Cloud Run, ses journaux se trouvent dans Cloud Logging. Sinon, les journaux se trouvent généralement là où le serveur webhook s'exécute.

Les journaux webhook standards contiennent un champ detectIntentResponseId avec un UUID, qui peut être utile pour suivre un appel particulier dans les serveurs webhook. Ce journal existe dans les journaux Cloud Logging de Dialogflow lorsque la journalisation Cloud est activée.

Problèmes courants liés aux webhooks

Voici quelques erreurs que vous pouvez trouver dans les journaux Dialogflow pour les appels de webhooks:

Erreur de résolution du nom d'hôte du serveur webhook

Dialogflow a recherché le nom d'hôte d'un webhook générique, et ce nom d'hôte n'existe pas dans le DNS. Assurez-vous que le nom d'hôte est enregistré dans le DNS public. Si le nom d'hôte est nouveau, la propagation de l'enregistrement peut prendre un certain temps. Message Cloud Logging : State: URL_ERROR, Reason: ERROR_DNS.

Le serveur webhook renvoie une erreur côté client

À l'exception de ERROR_DNS, cet état indique une réponse 4xx du serveur de webhook. Il peut s'agir d'un état non autorisé (401 – ERROR_AUTHENTICATION) ou de l'absence de l'URL sur le serveur webhook (404 – ERROR_NOT_FOUND). Message de journalisation Cloud: State: URL_ERROR.

L'agent Dialogflow expire avant que le serveur webhook ne renvoie une réponse

Dialogflow a atteint la limite de délai avant expiration du webhook avant la fin du serveur Web. Les deux approches possibles ici sont de réduire le temps de traitement du serveur webhook ou d'augmenter le temps d'attente de Dialogflow pour le webhook. Réduire le temps de traitement permet généralement d'obtenir de meilleurs résultats, bien que ce ne soit pas toujours simple. N'oubliez pas qu'il existe une limite de délai avant expiration maximale pour les webhooks et que les appelants ou utilisateurs finaux devront attendre plus longtemps pour obtenir une réponse de l'agent avant d'augmenter ce paramètre. Message Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB.

Le délai avant expiration de gRPC est dépassé avant que le serveur de webhook ne renvoie une réponse

La limite de temps définie par gRPC dans l'appel de l'API Dialogflow a été atteinte avant la fin de l'appel du webhook. Cette limite est généralement définie au niveau de l'intégration et est indépendante des paramètres Dialogflow et des limites de délai avant expiration du webhook. Pour en savoir plus sur les délais gRPC, consultez la page https://grpc.io/docs/guides/deadlines/. Message Cloud Logging: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.

Dialogflow n'a pas pu contacter le serveur webhook

Le serveur webhook n'a pas pu être atteint en raison d'une erreur réseau ou la connexion a été établie et le serveur webhook a renvoyé le code d'état HTTP 5xx, indiquant un problème lors du traitement de la requête. Assurez-vous que Dialogflow peut atteindre l'adresse du serveur webhook au niveau de la mise en réseau. Si la requête apparaît dans les journaux du serveur webhook, déterminez pourquoi l'appel a renvoyé une erreur 5xx. Message Cloud Logging : State: URL_UNREACHABLE.

Traçage des appels de webhook

Un appel webhook standard peut être mis en corrélation entre Dialogflow et un serveur webhook à l'aide de l'ID de session, de l'ID detectIntentResponse, de l'ID de trace pour les fonctions Cloud Run et d'un code temporel de l'appel. Vous pouvez effectuer un traçage flexible des webhooks à l'aide du code temporel de l'appel et des valeurs des paramètres de session spécifiées dans la définition du webhook au moment de la conception. Pour en savoir plus sur les requêtes de webhooks standards et flexibles, consultez la section Webhooks.

L'ID de session s'affiche dans le champ sessionInfo.session de WebhookRequest. Cet ID de session doit être unique pour chaque conversation. Il peut vous aider à comparer les journaux des agents aux journaux des webhooks pour les requêtes utilisant le même ID de session. La section précédente Enregistrer l'ID de session explique comment enregistrer l'ID de session à partir d'un webhook.

De plus, si vous hébergez votre webhook sur des fonctions Cloud Run ou une option sans serveur Google Cloud similaire, vous pouvez utiliser le champ trace des entrées de journal comme filtre de journal. Une seule exécution d'une fonction génère plusieurs entrées de journal avec la même valeur de trace.

L'exemple suivant utilise à la fois l'ID de session et la valeur de trace pour associer un journal d'erreurs d'agent Dialogflow particulier aux entrées de journal du webhook des fonctions Cloud Run correspondantes. L'exemple utilise des filtres Cloud Logging pour un agent ayant activé Cloud Logging.

1. Filtrer les journaux Dialogflow pour les journaux d'erreurs d'un agent spécifique

Utilisez le filtre Cloud Logging suivant pour filtrer vos journaux Dialogflow en fonction des journaux d'erreurs d'un agent particulier:

labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR

Une entrée de journal d'erreur de webhook ressemble à ceci:

{
  "insertId": "-j4gkkre31e2o",
  "jsonPayload": {
    "code": 14,
    "message": "Error calling webhook 'https://us-central1-PROJECT_ID.cloudfunctions.net/function-webhook': State: URL_UNREACHABLE, Reason: UNREACHABLE_5xx, HTTP status code: 500"
  },
  "labels": {
    "agent_id": "e9e01392-1351-42dc-9b15-b583fb2d2881",
    "environment_id": "",
    "location_id": "global",
    "session_id": "07c899-a86-78b-a77-569625b37"
  },
  "logName": "projects/PROJECT_ID/logs/dialogflow-runtime.googleapis.com%2Frequests",
  "receiveTimestamp": "2024-10-28T21:49:04.288439054Z",
  "resource": {
    "labels": {
      "project_id": "PROJECT_ID"
    },
    "type": "global",
  },
  "severity": "ERROR",
  "timestamp": "2024-10-28T21:49:04.132548Z"
}

Notez le champ labels.session_id, qui contient l'ID de session. Vous utiliserez l'ID de session à l'étape suivante.

2. Filtrer les journaux des fonctions Cloud Run par ID de session

Utilisez le filtre Cloud Logging suivant pour filtrer les journaux de vos fonctions Cloud Run par ID de session:

resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
textPayload="Debug Node: session ID = SESSION_ID"

Les journaux générés correspondent aux journaux de webhook créés au cours de la session fournie. Exemple :

{
  "insertId": "671c42940007ebebdbb1d56e",
  "labels": {
    "execution_id": "pgy8jvvblovs",
    "goog-managed-by": "cloudfunctions",
    "instance_id": "004940b3b8e3d975a4b11a4ed7d1ded4ce3ed37467ffc5e2a8f13a1908db928f8200b01cc554a5eda66ffc9d23d76dd75cec1619a07cb5751fa2e8a93bc6cfc3df86dfa0650a"
  },
  "logName": "projects/PROJECT_ID/logs/run.googleapis.com%2Fstdout",
  "receiveTimestamp": "2024-10-26T01:15:00.523313187Z",
  "resource": {
    "labels": {
      "configuration_name": "function-webhook",
      "location": "us-central1",
      "project_id": "PROJECT_ID",
      "revision_name": "function-webhook-00001-jiv",
      "service_name": "function-webhook",
    },
    "type": "cloud_run_revision"
  },
  "spanId": "6938366936362981595",
  "trace": "d1b54fbc8945dd59bdcaed37d7d5e185",
  "textPayload": "Debug Node: session ID = 07c899-a86-78b-a77-569625b37",
  "timestamp": "2024-10-26T01:15:00.519147Z"
}

Notez le champ trace, qui sera utilisé à l'étape suivante.

3. Filtrer les journaux Cloud Functions pour une trace spécifique

Utilisez le filtre Cloud Logging suivant pour filtrer les journaux Cloud Functions pour une trace spécifique:

resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
trace="projects/PROJECT_ID/traces/TRACE_ID"

où TRACE_ID est le dernier segment de la trace. Par exemple, TRACE_ID pour projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e est e41eefc1fac48665b442bfa400cc2f5e.

Le résultat est le journal du serveur webhook généré lors de l'exécution de la requête webhook associée à l'ID de session de l'étape 1 et à la trace de l'étape 2. Le journal se présente comme suit :

{
  "insertId": "671c42940008465e29f5faf0",
  "httpRequest": {
    "requestMethod": "POST",
    "requestUrl": "https://us-central1-TEST_PROJECT.cloudfunctions.net/function-webhook",
    "requestSize": "2410",
    "status": 200,
    "responseSize": "263",
    "userAgent": "Google-Dialogflow",
    "remoteIp": "8.34.210.1",
    "serverIp": "216.239.36.1",
    "latency": "0.166482342s",
    "protocol": "HTTP/1.1"
  },
  "resource": {
    "type": "cloud_run_revision",
    "labels": {
      "project_id": "PROJECT_ID",
      "service_name": "function-webhook",
      "location": "us-central1",
      "revision_name": "function-webhook-00001-jiv",
      "configuration_name": "function-webhook"
    }
  },
  "timestamp": "2024-10-26T01:15:00.352197Z",
  "severity": "INFO",
  "labels": {
    "instanceId": "004940b3b813af8a656c92aac1bd07ffad5165f1353e1e346b6161c14bcde225f68f4a88ceedc08aa9020f387b1b59471f73de45f2882a710ced37dea921f05ad962347690be",
    "goog-managed-by": "cloudfunctions"
  },
  "logName": "projects/test-project-12837/logs/run.googleapis.com%2Frequests",
  "trace": "projects/test-project-12837/traces/d1b54fbc8945dd59bdcaed37d7d5e185",
  "receiveTimestamp": "2024-10-26T01:15:00.548931586Z",
  "spanId": "604a07f7b33b18db",
  "traceSampled": true
}

Détecter un intent

Gérer les agents avec l'API