Interactions avec l'API

À chaque tour de conversation, une interaction a lieu. Lors d'une interaction, un utilisateur final envoie une entrée aux agents conversationnels (Dialogflow CX), qui envoient une réponse. Vous disposez de deux options lorsque vous mettez en œuvre votre système pour gérer les interactions : utiliser l'API ou utiliser une intégration.

Lorsque vous utilisez l'API, votre système doit gérer les éléments suivants :

• Créer un agent
• Fournir une interface utilisateur aux utilisateurs finaux
• Appeler l'API Dialogflow pour chaque tour de conversation afin d'envoyer les entrées de l'utilisateur final à l'API.
• À moins que les réponses de l'agent ne soient purement statiques (non courant), vous devez héberger un service de webhook pour gérer le fulfillment compatible avec webhook.

Lorsque vous utilisez une intégration, votre système ne doit gérer que les éléments suivants :

• Créer un agent
• Mettre en œuvre un service de webhook (facultatif)

Le schéma suivant illustre les étapes qui se produisent pour un tour de conversation d'une session.

Remarque : Les communications entre vos systèmes et intégrations, et Dialogflow sont chiffrées en transit. Par ailleurs, Les communications des composants internes Google sont chiffrées Application Layer Transport Security (ALTS).

1. L'utilisateur final saisit ou prononce quelque chose, appelé entrée de l'utilisateur final.
2. Votre système d'interface utilisateur ou d'intégration reçoit l'entrée et la transmet à l'API Dialogflow dans une requête de détection d'intent.
3. L'API Dialogflow reçoit la requête de détection d'intent. Elle correspond à l'entrée d'un intent ou d'un paramètre de formulaire, définit les paramètres nécessaires et met à jour l'état de la session. Si elle doit appeler un fulfillment compatible avec le webhook, elle envoie une requête de webhook à votre service de webhook. Sinon, passez à l'étape 6.
4. Votre service webhook reçoit la requête webhook. Votre service effectue les actions nécessaires, telles que l'appel d'API externes, le questionnement ou la mise à jour d'une base de données, etc.
5. Votre service de webhook génère une réponse et envoie un la réponse du webhook aux agents conversationnels (Dialogflow CX).
6. Les agents conversationnels (Dialogflow CX) créent une réponse de détection d'intent. Si un webhook a été appelé, il utilise la réponse fournie dans la réponse du webhook. Si aucun webhook n'a été appelé, il utilise la réponse statique définie dans l'agent. Les agents conversationnels (Dialogflow CX) envoient une réponse de détection d'intent à votre interface utilisateur ou à votre système d'intégration.
7. Votre système d'interface utilisateur ou d'intégration reçoit la réponse de détection d'intent et transmet la réponse texte ou audio à l'utilisateur final.
8. L'utilisateur final voit ou entend la réponse.

Objectif du guide

Ce guide explique comment appeler l'API pour un tour de conversation d'un agent qui n'utilise pas d'intégration (étape 2 du schéma ci-dessus). Ce guide n'explique pas comment mettre en œuvre une interface utilisateur pour votre utilisateur final.

Avant de commencer

Avant de lire ce guide, procédez comme suit :

1. Consultez les principes de base de Flow.
2. Effectuez la procédure de configuration.
3. Créez un agent ou continuez à utiliser celui que vous avez créé dans la section Créer un agent à l'aide de flux.

Collecter les ID

Les exemples ci-dessous nécessitent plusieurs ID en entrée. Pour rechercher vos ID de projet, de région et d'agent, procédez comme suit :

1. Ouvrez la console Dialogflow CX.
2. Sélectionnez votre projet Google Cloud pour ouvrir le sélecteur d'agent.
3. Cliquez sur le menu Option d'un agent dans la liste.
4. Cliquez sur le bouton de copie de nom .
5. Cela a pour effet de copier le nom complet de votre agent, qui inclut votre ID de projet, votre ID de région et votre ID d'agent au format suivant :
   projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID

Vous avez également besoin d'un ID de session. Une session représente une conversation entre un agent de conversation (Dialogflow CX) et un utilisateur final. Vous créez un ID de session unique au début d'une conversation et vous l'utilisez pour chaque tour de conversation. Pour essayer l'API, vous pouvez utiliser un ID de chaîne de 36 octets maximum, tel que test-session-123.

Appeler la détection d'intent

Les exemples suivants appellent la méthode Sessions.detectIntent. Accéder à la documentation de référence de l'API Session

Sélectionnez un protocole et une version pour la référence de session :

Protocole	V3	V3beta1
REST	Ressource de session	Ressource de session
RPC	Interface de la session	Interface de session
C++	SessionsClient	Non disponible
C#	SessionsClient	Non disponible
Go	SessionsClient	Non disponible
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Non disponible	Non disponible
Python	SessionsClient	SessionsClient
Ruby	Non disponible	Non disponible

Fermer

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud
• AGENT_ID : votre ID d'agent
• REGION_ID : votre ID de région
• SESSION_ID : votre ID de session
• END_USER_INPUT : entrée de l'utilisateur final

Méthode HTTP et URL :

POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

Corps JSON de la requête :

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "responseId": "38e8f23d-eed2-445e-a3e7-149b242dd669",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Ok, let's start a new order."
          ]
        }
      },
      {
        "text": {
          "text": [
            "I'd like to collect a bit more information from you."
          ]
        }
      },
      {
        "text": {
          "text": [
            "What color would you like?"
          ]
        }
      },
      {}
    ],
    "currentPage": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/flows/00000000-0000-0000-0000-000000000000/pages/ce0b88c4-9292-455c-9c59-ec153dad94cc",
      "displayName": "New Order"
    },
    "intent": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
      "displayName": "order.new"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": { ... },
    "match": {
      "intent": {
        "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
        "displayName": "order.new"
      },
      "resolvedInput": "I want to buy a shirt",
      "matchType": "INTENT",
      "confidence": 1
    }
  }
}

Java

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.cx.v3beta1.QueryInput;
import com.google.cloud.dialogflow.cx.v3beta1.QueryResult;
import com.google.cloud.dialogflow.cx.v3beta1.SessionName;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsClient;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsSettings;
import com.google.cloud.dialogflow.cx.v3beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntent {

  // DialogFlow API Detect Intent sample with text inputs.
  public static Map<String, QueryResult> detectIntent(
      String projectId,
      String locationId,
      String agentId,
      String sessionId,
      List<String> texts,
      String languageCode)
      throws IOException, ApiException {
    SessionsSettings.Builder sessionsSettingsBuilder = SessionsSettings.newBuilder();
    if (locationId.equals("global")) {
      sessionsSettingsBuilder.setEndpoint("dialogflow.googleapis.com:443");
    } else {
      sessionsSettingsBuilder.setEndpoint(locationId + "-dialogflow.googleapis.com:443");
    }
    SessionsSettings sessionsSettings = sessionsSettingsBuilder.build();

    Map<String, QueryResult> queryResults = Maps.newHashMap();
    // Instantiates a client.

    // Note: close() needs to be called on the SessionsClient object to clean up resources
    // such as threads. In the example below, try-with-resources is used,
    // which automatically calls close().
    try (SessionsClient sessionsClient = SessionsClient.create(sessionsSettings)) {
      // Set the session name using the projectID (my-project-id), locationID (global), agentID
      // (UUID), and sessionId (UUID).
      SessionName session =
          SessionName.ofProjectLocationAgentSessionName(projectId, locationId, agentId, sessionId);

      // TODO : Uncomment if you want to print session path
      // System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input.
      for (String text : texts) {
        // Set the text (hello) for the query.
        TextInput.Builder textInput = TextInput.newBuilder().setText(text);

        // Build the query with the TextInput and language code (en-US).
        QueryInput queryInput =
            QueryInput.newBuilder().setText(textInput).setLanguageCode(languageCode).build();

        // Build the DetectIntentRequest with the SessionName and QueryInput.
        DetectIntentRequest request =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .build();

        // Performs the detect intent request.
        DetectIntentResponse response = sessionsClient.detectIntent(request);

        // Display the query result.
        QueryResult queryResult = response.getQueryResult();

        // TODO : Uncomment if you want to print queryResult
        // System.out.println("====================");
        // System.out.format("Query Text: '%s'\n", queryResult.getText());
        // System.out.format(
        //     "Detected Intent: %s (confidence: %f)\n",
        //     queryResult.getIntent().getDisplayName(),
        //         queryResult.getIntentDetectionConfidence());

        queryResults.put(text, queryResult);
      }
    }
    return queryResults;
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const location = 'global';
// const agentId = 'my-agent';
// const query = 'Hello';
// const languageCode = 'en'

// Imports the Google Cloud Some API library
const {SessionsClient} = require('@google-cloud/dialogflow-cx');
/**
 * Example for regional endpoint:
 *   const location = 'us-central1'
 *   const client = new SessionsClient({apiEndpoint: 'us-central1-dialogflow.googleapis.com'})
 */
const client = new SessionsClient();

async function detectIntentText() {
  const sessionId = Math.random().toString(36).substring(7);
  const sessionPath = client.projectLocationAgentSessionPath(
    projectId,
    location,
    agentId,
    sessionId
  );
  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  for (const message of response.queryResult.responseMessages) {
    if (message.text) {
      console.log(`Agent Response: ${message.text.text}`);
    }
  }
  if (response.queryResult.match.intent) {
    console.log(
      `Matched Intent: ${response.queryResult.match.intent.displayName}`
    );
  }
  console.log(
    `Current Page: ${response.queryResult.currentPage.displayName}`
  );
}

detectIntentText();

Python

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.

def run_sample():
    # TODO(developer): Replace these values when running the function
    project_id = "YOUR-PROJECT-ID"
    # For more information about regionalization see https://cloud.google.com/dialogflow/cx/docs/how/region
    location_id = "YOUR-LOCATION-ID"
    # For more info on agents see https://cloud.google.com/dialogflow/cx/docs/concept/agent
    agent_id = "YOUR-AGENT-ID"
    agent = f"projects/{project_id}/locations/{location_id}/agents/{agent_id}"
    # For more information on sessions see https://cloud.google.com/dialogflow/cx/docs/concept/session
    session_id = uuid.uuid4()
    texts = ["Hello"]
    # For more supported languages see https://cloud.google.com/dialogflow/es/docs/reference/language
    language_code = "en-us"

    detect_intent_texts(agent, session_id, texts, language_code)


def detect_intent_texts(agent, session_id, texts, language_code):
    """Returns the result of detect intent with texts as inputs.

    Using the same `session_id` between requests allows continuation
    of the conversation."""
    session_path = f"{agent}/sessions/{session_id}"
    print(f"Session path: {session_path}\n")
    client_options = None
    agent_components = AgentsClient.parse_agent_path(agent)
    location_id = agent_components["location"]
    if location_id != "global":
        api_endpoint = f"{location_id}-dialogflow.googleapis.com:443"
        print(f"API Endpoint: {api_endpoint}\n")
        client_options = {"api_endpoint": api_endpoint}
    session_client = SessionsClient(client_options=client_options)

    for text in texts:
        text_input = session.TextInput(text=text)
        query_input = session.QueryInput(text=text_input, language_code=language_code)
        request = session.DetectIntentRequest(
            session=session_path, query_input=query_input
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print(f"Query text: {response.query_result.text}")
        response_messages = [
            " ".join(msg.text.text) for msg in response.query_result.response_messages
        ]
        print(f"Response text: {' '.join(response_messages)}\n")

Passage en production

Avant d'exécuter votre agent en production, veillez à mettre en œuvre les bonnes pratiques pour le passage en production.