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

Interactions avec l'API

Pour chaque tour de conversation, une interaction a lieu. Lors d'une interaction, un utilisateur final envoie des données à Dialogflow, qui lui envoie une réponse. Vous disposez de deux options pour mettre 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 traiter les éléments suivants:

  • Créer un agent.
  • Fournissez une interface utilisateur aux utilisateurs finaux.
  • Appelez l'API Dialogflow pour chaque tour de conversation pour envoyer l'entrée 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.

Lors de l'intégration, votre système ne doit gérer que les éléments suivants:

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

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

Schéma de flux de l'API.

  1. L'utilisateur final saisit ou prononce quelque chose, appelé entrée de l'utilisateur final.
  2. Votre interface utilisateur ou votre système 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 crée une réponse et renvoie une réponse de webhook à Dialogflow.
  6. Dialogflow crée 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. Dialogflow envoie une réponse de détection d'intent à votre interface utilisateur ou à votre système d'intégration.
  7. Votre interface utilisateur ou votre système d'intégration reçoit la réponse de détection d'intent et transfère la réponse textuelle 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 une tour de conversation pour un agent qui n'utilise pas d'intégration (étape 2 du diagramme ci-dessus). Ce guide ne vous montre pas comment mettre en œuvre une interface utilisateur pour votre utilisateur final.

Collecter des ID

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

  1. Ouvrez la console Dialogflow CX.
  2. Sélectionnez votre projet GCP pour ouvrir le sélecteur d'agent.
  3. Cliquez sur le menu d'option d'un agent dans la liste.
  4. Cliquez sur le bouton de copie .
  5. Cette commande copie le nom complet de votre agent, qui comprend l'ID du projet, l'ID de la région et l'ID de l'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 Dialogflow 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 tester l'API, vous pouvez utiliser n'importe quel ID de chaîne de 36 octets au maximum, comme test-session-123.

Intent de détection d'appels

Les exemples suivants appellent la méthode detectIntent du type Sessions.

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 session Interface de session
C# Non disponible Non disponible
Go Non disponible Non disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponible Non disponible
Python SessionsClient SessionsClient
Ruby Non disponible Non disponible

API REST et ligne de commande

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

  • PROJECT_ID : votre ID de projet GCP
  • 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 :

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


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
    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.of(projectId, locationId, agentId, sessionId);
      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();

        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

/**
 * 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
  );
  console.info(sessionPath);

  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  console.log(`User Query: ${query}`);
  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

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")

Production

Avant d'exécuter l'agent en production, veillez à mettre en œuvre les bonnes pratiques en matière de production.