Início rápido: interações com a API

Se não estiver a usar uma integração, tem de escrever código para interagir com os utilizadores finais. Para cada interação de conversa, o seu código chama a API Dialogflow para consultar o seu agente. Este guia mostra como interagir com um agente através da API REST na linha de comandos e através das bibliotecas de cliente.

Antes de começar

Se não planeia usar a API, pode ignorar este início rápido.

Antes de ler este guia, deve fazer o seguinte:

  1. Compreenda as noções básicas do Dialogflow.
  2. Realize os passos de configuração.
  3. Execute os passos no guia de início rápido Crie um agente. Os passos abaixo continuam a trabalhar no agente que iniciou nesse guia. Se já não tiver esse agente, pode transferir build-agent-quickstart.zip e importar o ficheiro.

Sessões

Uma sessão representa uma conversa entre um agente do Dialogflow e um utilizador final. Cria uma sessão no início de uma conversa e usa-a para cada interação da conversa. Quando a conversa terminar, deixa de usar a sessão.

Não deve usar a mesma sessão para conversas simultâneas com diferentes utilizadores finais. O Dialogflow mantém os contextos atualmente ativos para cada sessão ativa. Os dados da sessão são armazenados pelo Dialogflow durante 20 minutos.

Cada sessão é determinada como única por um ID da sessão gerado pelo seu sistema. Cria uma nova sessão fornecendo um novo ID da sessão num pedido de deteção de intenção. Um ID da sessão é uma string com um tamanho máximo de 36 bytes. O seu sistema é responsável por gerar IDs de sessão exclusivos. Podem ser números aleatórios, identificadores do utilizador final com hash ou quaisquer outros valores que seja conveniente gerar.

Detetar intenção

Quando usa a API para interações, o seu serviço interage diretamente com o utilizador final. Para cada interação de conversa, o seu serviço envia expressões do utilizador final para o Dialogflow chamando o método detectIntent ou streamingDetectIntent do tipo Sessions. O Dialogflow responde com informações sobre a intenção correspondente, a ação, os parâmetros e a resposta definidos para a intenção. O seu serviço realiza as ações necessárias (por exemplo, consultas de base de dados ou chamadas de API externas) e envia uma mensagem ao utilizador final. Este processo continua até a conversa terminar.

Os exemplos seguintes mostram como detetar a intenção. Cada exemplo aceita um subconjunto das seguintes entradas:

  • ID do projeto: Use o ID do projeto que criou nos passos de configuração.
  • ID da sessão: Para fins de teste de um agente, pode usar qualquer coisa. Por exemplo, "123456789" é usado frequentemente por exemplos.
  • Texto ou textos: Esta é a expressão única do utilizador final ou a lista de expressões do utilizador final. Se forem fornecidas várias expressões, o exemplo de código chama a intenção de deteção para cada expressão. Experimente usar "I know french" (Sei francês).
  • Código do idioma: O código do idioma para a expressão do utilizador final. Use "en-US" para este agente de exemplo.

REST

Para detetar a intenção, chame o método detectIntent no recurso Sessions.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto do Google Cloud
  • SESSION_ID: um ID da sessão

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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"
  }
}

Tenha em atenção o seguinte acerca da resposta:

  • O campo queryResult.intent contém a intenção correspondente.
  • O valor do campo queryResult.fulfillmentMessages contém a resposta de intenção. Esta é a resposta que o seu sistema deve encaminhar para o utilizador final.
  • O valor do campo queryResult.parameters contém os parâmetros extraídos da expressão do utilizador final.
  • O campo queryResult.outputContext contém o contexto ativo.

Go

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento 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 "", fmt.Errorf("detect.DetectIntentText 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

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


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

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


/**
 * 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

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 

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

Idiomas adicionais

C#: Siga as instruções de configuração do C# na página das bibliotecas cliente e, em seguida, visite a documentação de referência do Dialogflow para .NET.

PHP: Siga as instruções de configuração do PHP na página das bibliotecas cliente e, em seguida, visite a documentação de referência do Dialogflow para PHP.

Ruby: Siga as instruções de configuração do Ruby na página das bibliotecas cliente e, em seguida, visite a documentação de referência do Dialogflow para Ruby.

Produção

Antes de executar o seu agente em produção, certifique-se de que implementa as práticas recomendadas de produção.

Anterior
Interações com uma integração
Avançar
Vista geral da consola do Dialogflow