Guida rapida: interazioni con l'API

Se non utilizzi un'integrazione, devi scrivere il codice per interagire con gli utenti finali. Per ogni turno di conversazione, il tuo codice chiama l'API Dialogflow per eseguire query sull'agente. Questa guida mostra come interagire con un agente utilizzando l'API REST dalla riga di comando e le librerie client.

Prima di iniziare

Se non prevedi di utilizzare l'API, puoi saltare questa guida rapida.

Prima di leggere questa guida, devi:

  1. Comprendere le nozioni di base di Dialogflow.
  2. Esegui i passaggi di configurazione.
  3. Segui i passaggi della guida rapida Crea un agente. I passaggi seguenti continuano a lavorare sull'agente che hai avviato in quella guida. Se non hai più l'agente, puoi scaricare build-agent-quickstart.zip e importare il file.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività di questa guida, chiedi all'amministratore di concederti il ruolo IAM Client API Dialogflow (roles/dialogflow.client) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Sessioni

Una sessione rappresenta una conversazione tra un agente Dialogflow e un utente finale. Puoi creare una sessione all'inizio di una conversazione e utilizzarla per ogni turno della conversazione. Una volta terminata la conversazione, interrompi l'utilizzo della sessione.

Non devi utilizzare la stessa sessione per conversazioni simultanee con utenti finali diversi. Dialogflow mantiene i contesti attualmente attivi per ogni sessione attiva. I dati della sessione vengono archiviati da Dialogflow per 20 minuti.

Ogni sessione è determinata in modo univoco da un ID sessione generato dal tuo sistema. Per creare una nuova sessione, fornisci un nuovo ID sessione in una richiesta di rilevamento intent. Un ID sessione è una stringa di dimensioni massime pari a 36 byte. Il tuo sistema è responsabile della generazione di ID sessione univoci. Possono essere numeri casuali, identificatori degli utenti finali sottoposti ad hashing o qualsiasi altro valore che ti sia comodo generare.

Rileva l'intent

Quando utilizzi l'API per le interazioni, il tuo servizio interagisce direttamente con l'utente finale. Per ogni turno di conversazione, il tuo servizio invia le espressioni dell'utente finale a Dialogflow chiamando il metodo detectIntent o streamingDetectIntent del tipo Sessions. Dialogflow risponde con informazioni sull'intent corrispondente, sull'azione, sui parametri e sulla risposta definita per l'intent. Il tuo servizio esegue le azioni necessarie (ad esempio query di database o chiamate API esterne) e invia un messaggio all'utente finale. Questo processo continua fino al termine della conversazione.

I seguenti esempi mostrano come rilevare l'intent. Ogni esempio accetta un sottoinsieme dei seguenti input:

  • ID progetto: utilizza l'ID progetto per il progetto che hai creato nei passaggi di configurazione.
  • ID sessione: per testare un agente, puoi utilizzare qualsiasi valore. Ad esempio, "123456789" viene spesso utilizzato dai sample.
  • Testo o testi: si tratta della singola espressione dell'utente finale o dell'elenco di espressioni dell'utente finale. Se vengono fornite più espressioni, il codice campione chiama l'intent di rilevamento per ogni espressione. Prova a dire "Conosco il francese".
  • Codice lingua: il codice lingua per l'espressione dell'utente finale. Utilizza "en-US" per questo agente di esempio.

REST

Per rilevare l'intent, chiama il metodo detectIntent sulla risorsa Sessions.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • SESSION_ID: un ID sessione

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Tieni presente quanto segue in merito alla risposta:

  • Il campo queryResult.intent contiene l'intent corrispondente.
  • Il valore del campo queryResult.fulfillmentMessages contiene la risposta dell'intent. Questa è la risposta che il tuo sistema deve inoltrare all'utente finale.
  • Il valore del campo queryResult.parameters contiene i parametri estratti dall'espressione dell'utente finale.
  • Il campo queryResult.outputContext contiene il contesto attivo.

Go

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Linguaggi aggiuntivi

C#: segui le istruzioni di configurazione di C# nella pagina delle librerie client, poi consulta la documentazione di riferimento di Dialogflow CX per .NET.

PHP: segui le istruzioni di configurazione di PHP nella pagina delle librerie client, poi consulta la documentazione di riferimento di Dialogflow CX per PHP.

Ruby: segui le istruzioni di configurazione di Ruby nella pagina delle librerie client, poi consulta la documentazione di riferimento di Dialogflow CX per Ruby.

Industrializzazione

Prima di eseguire l'agente in produzione, assicurati di implementare le best practice per la produzione.

Indietro
Interazioni con un'integrazione
Avanti
Panoramica della console di Dialogflow