Kurzanleitung: Interaktionen mit der API

Wenn Sie keine Einbindung verwenden, müssen Sie Code schreiben, um mit Endnutzern zu interagieren. Für jede Konversationsrunde ruft Ihr Code die Dialogflow API auf, um Ihren Agent abzufragen. In diesem Leitfaden erfahren Sie, wie Sie mit einem Agent interagieren, indem Sie die REST API über die Befehlszeile sowie die Clientbibliotheken verwenden.

Hinweise

Wenn Sie nicht vorhaben, die API zu verwenden, können Sie diese Kurzanleitung überspringen.

Bevor Sie diese Anleitung lesen, sollten Sie mit Folgendem vertraut sein:

Grundlagen von Dialogflow
Einrichtungsschritte ausführen
Die Schritte in der Kurzanleitung Agent erstellen ausführen. Führen Sie die folgenden Schritte aus, um den Agent weiter zu bearbeiten, mit dem Sie in diesem Leitfaden begonnen haben. Wenn Sie diesen Agent nicht mehr haben, können Sie build-agent-quickstart.zip herunterladen und die Datei importieren.

Sessions

Der Begriff Sitzung steht für eine Unterhaltung zwischen einem Dialogflow-Agent und einem Endnutzer. Zu Beginn einer Unterhaltung erstellen Sie eine Sitzung und verwenden diese für jede Unterhaltungsrunde. Sobald die Unterhaltung zu Ende ist, beenden Sie die Sitzung.

Für gleichzeitige Unterhaltungen mit verschiedenen Endnutzern sollten Sie nicht dieselbe Sitzung verwenden. Dialogflow erhält für jede aktive Sitzung die aktuell aktiven Kontexte aufrecht. Sitzungsdaten speichert Dialogflow 20 Minuten lang.

Jeder Sitzung wird von Ihrem System eine eindeutige Sitzungs-ID zugewiesen. Sie erstellen eine neue Sitzung, indem Sie in einer Anfrage zur Intent-Erkennung eine neue Sitzungs-ID bereitstellen. Eine Sitzungs-ID besteht aus einem String mit höchstens 36 Byte. Die Verantwortung für die Generierung eindeutiger Sitzungs-IDs liegt bei Ihrem System. Dabei kann es sich um Zufallszahlen, um gehashte Endnutzer-IDs oder um alle erdenklichen anderen Werte handeln, die Sie bequem generieren können.

Intent erkennen

Wenn Sie die API für Interaktionen verwenden, interagiert der Dienst direkt mit dem Endnutzer. Für jede Unterhaltungsrunde ruft der Dienst die Methode detectIntent oder streamingDetectIntent des Sessions-Typs auf und sendet so Endnutzerausdrücke an Dialogflow. Dialogflow antwortet mit Informationen zum zugeordneten Intent, zur Aktion, zu den Parametern und zu der für den Intent definierten Antwort. Bei Bedarf führt Ihr Dienst Aktionen aus (z. B. Datenbankabfragen oder Aufrufe an externe APIs) und sendet eine Nachricht an den Endnutzer. Dieser Vorgang wird fortgesetzt, bis die Unterhaltung beendet ist.

In den folgenden Beispielen wird veranschaulicht, wie der Intent erkannt wird. Für jedes Beispiel wird ein Teil der folgenden Eingaben akzeptiert:

Projekt-ID: Verwenden Sie die Projekt-ID für das Projekt, das Sie in den Einrichtungsschritten erstellt haben.
Session-ID: Zum Testen des Agents können Sie eine beliebige ID verwenden. In Beispielen wird häufig "123456789" verwendet.
Text oder Texte: Ein einzelner Endnutzerausdruck oder eine Liste von Endnutzerausdrücken. Wenn mehrere Ausdrücke angegeben werden, werden durch die Aufrufe in den Codebeispielen Intents für jeden Ausdruck erkannt. Verwenden Sie "I know french".
Sprachcode: Der Sprachcode für den Endnutzerausdruck. Verwenden Sie für diesen Beispiel-Agent "en-US".

REST

Rufen Sie zur Intent-Erkennung die Methode detectIntent für die Ressource Sessions auf.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

PROJECT_ID: Ihre Google Cloud-Projekt-ID
SESSION_ID: eine Sitzungs-ID

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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)

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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 (Browser)

Kopieren Sie den Anfragetext und öffnen Sie die Referenzseite für Methoden. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Fügen Sie den Anfragetext in dieses Tool ein, füllen Sie alle Pflichtfelder aus und klicken Sie auf Ausführen.

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Beachten Sie für die Antwort Folgendes:

Das Feld queryResult.intent enthält den zugeordneten Intent.
Der Wert des Felds queryResult.fulfillmentMessages enthält die Intent-Antwort. Das ist die Antwort, die Ihr System an den Endnutzer weiterleiten soll.
Der Wert des Felds queryResult.parameters enthält die aus dem Endnutzerausdruck extrahierten Parameter.
Das Feld queryResult.outputContext enthält den aktiven Kontext.

Go

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Auf GitHub ansehen Feedback

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

Auf GitHub ansehen Feedback


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

Auf GitHub ansehen Feedback


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

Auf GitHub ansehen Feedback

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

Weitere Sprachen

C#: Folgen Sie der Anleitung zur Einrichtung von C# auf der Seite der Clientbibliotheken und rufen Sie dann die Dialogflow-Referenzdokumentation für .NET auf.

PHP: Folgen Sie der Anleitung zur Einrichtung von PHP auf der Seite der Clientbibliotheken und rufen Sie dann die Dialogflow-Referenzdokumentation für PHP auf.

Ruby: Folgen Sie der Anleitung zur Einrichtung von Ruby auf der Seite der Clientbibliotheken und rufen Sie dann die Dialogflow-Referenzdokumentation für Ruby auf.

Produktion

Bevor Sie den Agent in der Produktion ausführen, sollten Sie die Best Practices für die Produktion implementieren.

Zurück

Interaktionen mit einer Integration

Weiter

Dialogflow-Konsole – Übersicht