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

Guide de démarrage rapide : Interagir avec l'API

Si vous n'utilisez pas d'intégration, vous devez écrire du code pour interagir avec les utilisateurs finaux. Pour chaque tour de conversation, votre code appelle l'API Dialogflow pour interroger votre agent. Ce guide vous explique comment interagir avec un agent en utilisant l'API REST sur la ligne de commande et en utilisant les bibliothèques clientes.

Avant de commencer

Si vous ne prévoyez pas d'utiliser l'API, vous pouvez ignorer ce guide de démarrage rapide.

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

Apprenez les principes de base de Dialogflow.
Effectuez la procédure de configuration.
Suivez la procédure décrite dans le guide de démarrage rapide Créer un agent. Les étapes ci-dessous continuent d'utiliser l'agent que vous avez lancé dans ce guide. Si vous n'avez plus cet agent, vous pouvez télécharger build-agent-quickstart.zip et importer le fichier.

Sessions

Une session représente une conversation entre un agent Dialogflow et un utilisateur final. Vous créez une session au début d'une conversation et vous l'utilisez pour chaque tour de conversation. Une fois la conversation terminée, vous arrêtez d'utiliser cette session.

N'utilisez pas la même session pour des conversations simultanées avec différents utilisateurs finaux. Dialogflow gère les contextes actifs pour chaque session active. Les données de session sont stockées par Dialogflow pendant 20 minutes.

Chaque session est déterminée de manière unique par un ID de session généré par votre système. Vous créez une session en transmettant un nouvel ID de session dans une requête de détection d'intent. Un ID de session est une chaîne de caractères d'une taille maximale de 36 octets. Votre système est chargé de générer des ID de session uniques. Il peut s'agir de nombres aléatoires, d'ID d'utilisateurs finaux hachés ou de toute autre valeur que vous pouvez facilement générer.

Détecter un intent

Lorsque vous gérez les interactions à l'aide de l'API, votre service interagit directement avec l'utilisateur final. Pour chaque tour de conversation, votre service envoie les expressions de l'utilisateur final à Dialogflow en appelant la méthode detectIntent ou streamingDetectIntent du type Sessions. Dialogflow répond en envoyant des informations sur l'intent correspondant, l'action, les paramètres et la réponse définie pour l'intent. Votre service effectue les actions requises (par exemple des requêtes de base de données ou des appels d'API externes) et envoie un message à l'utilisateur final. Ce processus se poursuit jusqu'à la fin de la conversation.

Les exemples suivants montrent comment détecter un intent. Chaque exemple accepte un sous-ensemble des entrées suivantes :

ID du projet : utilisez l'ID de projet créé dans la procédure de configuration.
ID de session : pour tester un agent, vous pouvez utiliser n'importe quel élément. "123456789" est fréquemment utilisé dans les exemples.
Texte ou données textuelles : il s'agit de l'expression ou de la liste d'expressions de l'utilisateur final. Si plusieurs expressions sont fournies, les appels de l'exemple de code détectent l'intent pour chaque expression. Essayez "Je connais le français".
Code de langue : code de langue de l'expression de l'utilisateur final. Utilisez "en-US" "pour cet exemple d'agent.

REST

Pour détecter l'intent, appelez la méthode detectIntent sur la ressource Sessions.

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

PROJECT_ID : ID de votre projet Google Cloud
SESSION_ID : un ID de session

Méthode HTTP et URL :

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/agent/sessions/SESSION_ID:detectIntent

Corps JSON de la requête :

{
  "query_input": {
    "text": {
      "text": "I know french",
      "language_code": "en-US"
    }
  }
}

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://dialogflow.googleapis.com/v2/projects/PROJECT_ID/agent/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://dialogflow.googleapis.com/v2/projects/PROJECT_ID/agent/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

APIs Explorer (navigateur)

Copiez le corps de la requête et ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Collez le corps de la requête dans cet outil, renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

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

{
  "responseId": "856510ca-f617-4e25-b0bb-a26c0a59e030-19db3199",
  "queryResult": {
    "queryText": "I know french",
    "parameters": {
      "language": "French",
      "language-programming": ""
    },
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Wow! I didn't know you knew French. How long have you known French?",
    "fulfillmentMessages": [
      {
        "text": {
          "text": [
            "Wow! I didn't know you knew French. How long have you known French?"
          ]
        }
      }
    ],
    "outputContexts": [
      {
        "name": "projects/PROJECT_ID/agent/sessions/123456789/contexts/set-language-followup",
        "lifespanCount": 2,
        "parameters": {
          "language": "French",
          "language.original": "french",
          "language-programming": "",
          "language-programming.original": ""
        }
      }
    ],
    "intent": {
      "name": "projects/PROJECT_ID/agent/intents/fe45022f-e58a-484f-96e8-1cbd6628f648",
      "displayName": "set-language"
    },
    "intentDetectionConfidence": 1,
    "languageCode": "en"
  }
}

Tenez compte des points suivants concernant la réponse :

Le champ queryResult.intent contient l'intent correspondant.
La valeur du champ queryResult.fulfillmentMessages contient la réponse de l'intent. Il s'agit de la réponse que votre système doit transmettre à l'utilisateur final.
La valeur du champ queryResult.parameters contient les paramètres extraits de l'expression de l'utilisateur final.
Le champ queryResult.outputContext contient le contexte actif.

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.

func DetectIntentText(projectID, sessionID, text, languageCode string) (string, error) {
	ctx := context.Background()

	sessionClient, err := dialogflow.NewSessionsClient(ctx)
	if err != nil {
		return "", err
	}
	defer sessionClient.Close()

	if projectID == "" || sessionID == "" {
		return "", errors.New(fmt.Sprintf("Received empty project (%s) or session (%s)", projectID, sessionID))
	}

	sessionPath := fmt.Sprintf("projects/%s/agent/sessions/%s", projectID, sessionID)
	textInput := dialogflowpb.TextInput{Text: text, LanguageCode: languageCode}
	queryTextInput := dialogflowpb.QueryInput_Text{Text: &textInput}
	queryInput := dialogflowpb.QueryInput{Input: &queryTextInput}
	request := dialogflowpb.DetectIntentRequest{Session: sessionPath, QueryInput: &queryInput}

	response, err := sessionClient.DetectIntent(ctx, &request)
	if err != nil {
		return "", err
	}

	queryResult := response.GetQueryResult()
	fulfillmentText := queryResult.GetFulfillmentText()
	return fulfillmentText, nil
}

Java


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

public class DetectIntentTexts {

  // DialogFlow API Detect Intent sample with text inputs.
  public static Map<String, QueryResult> detectIntentTexts(
      String projectId, List<String> texts, String sessionId, String languageCode)
      throws IOException, ApiException {
    Map<String, QueryResult> queryResults = Maps.newHashMap();
    // Instantiates a client
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text (hello) and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);

        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

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

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

        System.out.println("====================");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");

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

Node.js


/**
 * TODO(developer): UPDATE these variables before running the sample.
 */
// projectId: ID of the GCP project where Dialogflow agent is deployed
// const projectId = 'PROJECT_ID';
// sessionId: String representing a random number or hashed user identifier
// const sessionId = '123456';
// queries: A set of sequential queries to be send to Dialogflow agent for Intent Detection
// const queries = [
//   'Reserve a meeting room in Toronto office, there will be 5 of us',
//   'Next monday at 3pm for 1 hour, please', // Tell the bot when the meeting is taking place
//   'B'  // Rooms are defined on the Dialogflow agent, default options are A, B, or C
// ]
// languageCode: Indicates the language Dialogflow agent should use to detect intents
// const languageCode = 'en';

// Imports the Dialogflow library
const dialogflow = require('@google-cloud/dialogflow');

// Instantiates a session client
const sessionClient = new dialogflow.SessionsClient();

async function detectIntent(
  projectId,
  sessionId,
  query,
  contexts,
  languageCode
) {
  // The path to identify the agent that owns the created intent.
  const sessionPath = sessionClient.projectAgentSessionPath(
    projectId,
    sessionId
  );

  // The text query request.
  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
        languageCode: languageCode,
      },
    },
  };

  if (contexts && contexts.length > 0) {
    request.queryParams = {
      contexts: contexts,
    };
  }

  const responses = await sessionClient.detectIntent(request);
  return responses[0];
}

async function executeQueries(projectId, sessionId, queries, languageCode) {
  // Keeping the context across queries let's us simulate an ongoing conversation with the bot
  let context;
  let intentResponse;
  for (const query of queries) {
    try {
      console.log(`Sending Query: ${query}`);
      intentResponse = await detectIntent(
        projectId,
        sessionId,
        query,
        context,
        languageCode
      );
      console.log('Detected intent');
      console.log(
        `Fulfillment Text: ${intentResponse.queryResult.fulfillmentText}`
      );
      // Use the context from this response for next queries
      context = intentResponse.queryResult.outputContexts;
    } catch (error) {
      console.log(error);
    }
  }
}
executeQueries(projectId, sessionId, queries, languageCode);

Python

def detect_intent_texts(project_id, 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."""
    from google.cloud import dialogflow

    session_client = dialogflow.SessionsClient()

    session = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

        response = session_client.detect_intent(
            request={"session": session, "query_input": query_input}
        )

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))

Langues supplémentaires

C# : Veuillez suivre les instructions de configuration de C# sur la page des bibliothèques clientes, puis consultez la documentation de référence sur Dialogflow pour .NET.

PHP : Veuillez suivre les instructions de configuration pour PHP sur la page des bibliothèques clientes, puis consultez la documentation de référence sur Dialogflow pour PHP.

Ruby : Veuillez suivre les instructions de configuration pour Ruby sur la page des bibliothèques clientes, puis consultez la documentation de référence sur Dialogflow pour Ruby.

Passage en production

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

Interactions avec une intégration

Présentation de la console Dialogflow