מדריך למתחילים: אינטראקציות עם ה-API

אם אתם לא משתמשים בשילוב, אתם צריכים לכתוב קוד כדי ליצור אינטראקציה עם משתמשי הקצה. בכל שלב בשיחה, הקוד שלכם שולח קריאה ל-Dialogflow API כדי לשלוח שאילתה לנציג. במדריך הזה נסביר איך ליצור אינטראקציה עם נציג באמצעות API בארכיטקטורת REST בשורת הפקודה ובאמצעות ספריות הלקוח.

לפני שמתחילים

אם אתם לא מתכננים להשתמש ב-API, אתם יכולים לדלג על המדריך הזה למתחילים.

לפני שתקראו את המדריך הזה:

1. להבין את היסודות של Dialogflow.
2. לבצע את השלבים להגדרה.
3. מבצעים את השלבים במדריך למתחילים יצירת נציג. השלבים הבאים ממשיכים את העבודה על הנציג שהתחלתם במדריך הזה. אם הסוכן הזה כבר לא קיים, אתם יכולים להוריד את build-agent-quickstart.zip ולייבא את הקובץ.

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לביצוע המשימות שבמדריך הזה, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד לקוח Dialogflow API (roles/dialogflow.client) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

סשנים

סשן מייצג שיחה בין נציג Dialogflow לבין משתמש קצה. אתם יוצרים סשן בתחילת השיחה ומשתמשים בו בכל שלב בשיחה. כשהשיחה מסתיימת, אתם מפסיקים להשתמש בסשן.

אין להשתמש באותו סשן לשיחות בו-זמניות עם משתמשי קצה שונים. ב-Dialogflow נשמרים ההקשרים הפעילים כרגע לכל סשן פעיל. נתוני הסשן נשמרים ב-Dialogflow למשך 20 דקות.

כל סשן מזוהה כייחודי באמצעות מזהה סשן שנוצר על ידי המערכת שלכם. כדי ליצור סשן חדש, צריך לספק מזהה סשן חדש בבקשה לזיהוי כוונה. מזהה סשן הוא מחרוזת בגודל של עד 36 בייטים. המערכת שלכם אחראית ליצירת מזהי סשן ייחודיים. הם יכולים להיות מספרים אקראיים, מזהי משתמש מגובבים של משתמשי קצה או כל ערך אחר שנוח לכם ליצור.

זיהוי כוונה

כשמשתמשים ב-API לאינטראקציות, השירות יוצר אינטראקציה ישירה עם משתמש הקצה. בכל שלב בשיחה, השירות שולח את הביטויים של משתמש הקצה ל-Dialogflow באמצעות קריאה ל-method‏ detectIntent או streamingDetectIntent של הסוג Sessions. ‫Dialogflow מגיב עם מידע על ה-intent התואמת, הפעולה, הפרמטרים והתגובה שהוגדרה ל-intent. השירות מבצע פעולות לפי הצורך (לדוגמה, שאילתות במסד נתונים או קריאות ל-API חיצוני) ושולח הודעה למשתמש הקצה. התהליך הזה נמשך עד שהשיחה מסתיימת.

בדוגמאות הבאות מוסבר איך לזהות כוונה. כל דוגמה מקבלת קבוצת משנה של הקלטים הבאים:

• ‫Project ID: מזהה הפרויקט שיצרתם בשלבי ההגדרה.
• מזהה סשן: כדי לבדוק נציג, אפשר להשתמש בכל דבר. לדוגמה, המספר "123456789" מופיע לעיתים קרובות בדוגמאות.
• טקסט או טקסטים: זהו הביטוי היחיד של משתמש הקצה או רשימת הביטויים של משתמש הקצה. אם מספקים כמה ביטויים, הקוד לדוגמה קורא לזיהוי כוונה לכל ביטוי. אפשר לנסות להגיד "אני יודע צרפתית".
• קוד שפה: קוד השפה של הביטוי של משתמש הקצה. בסוכן לדוגמה הזה, משתמשים ב-"en-US".

REST

כדי לזהות כוונה, צריך להפעיל את ה-method‏ detectIntent במשאב Sessions.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud
• ‫SESSION_ID: מזהה סשן

ה-method של ה-HTTP וכתובת ה-URL:

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

תוכן בקשת JSON:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

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)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$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 (דפדפן)

מעתיקים את גוף הבקשה ופותחים את דף העזר של השיטה. החלונית של APIs Explorer תיפתח בצד ימין של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. מדביקים את גוף הבקשה בכלי הזה, ממלאים את כל שדות החובה ולוחצים על Execute.

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

שימו לב לפרטים הבאים לגבי התשובה:

• השדה queryResult.intent מכיל את ה-Intent התואם.
• הערך של השדה queryResult.fulfillmentMessages מכיל את התגובה ל-Intent. זו התשובה שהמערכת שלכם צריכה להעביר למשתמש הקצה.
• הערך של השדה queryResult.parameters מכיל את הפרמטרים שחולצו מהביטוי של משתמש הקצה.
• השדה queryResult.outputContext מכיל את ההקשר הפעיל.

Go

כדי לבצע אימות ב-Dialogflow CX, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

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

כדי לבצע אימות ב-Dialogflow CX, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

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

כדי לבצע אימות ב-Dialogflow CX, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

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

כדי לבצע אימות ב-Dialogflow CX, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

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

שפות נוספות

‫C#‎: פעלו לפי הוראות ההגדרה של C# ‎ בדף ספריות הלקוח, ואז עיינו במאמרי העזרה של Dialogflow CX ל-‎ .NET.

‫PHP: פועלים לפי הוראות ההגדרה של PHP בדף ספריות הלקוח, ואז נכנסים למאמרי העזרה של Dialogflow CX ל-PHP.

‫Ruby: פועלים לפי הוראות ההגדרה של Ruby בדף ספריות הלקוח, ואז נכנסים למאמרי העזרה של Dialogflow CX ל-Ruby.

העברה לסביבת ייצור

לפני שתפעילו את הנציג בסביבת הייצור, חשוב להטמיע את השיטות המומלצות להעברה לייצור.