Panduan memulai: Interaksi dengan API

Jika tidak menggunakan integrasi, Anda harus menulis kode untuk berinteraksi dengan pengguna akhir. Untuk setiap giliran percakapan, kode Anda akan memanggil Dialogflow API untuk mengkueri agen Anda. Panduan ini menunjukkan cara berinteraksi dengan agen menggunakan REST API di command line dan menggunakan library klien.

Sebelum memulai

Jika Anda tidak berencana menggunakan API, lewati panduan memulai ini.

Anda harus melakukan hal berikut sebelum membaca panduan ini:

1. Memahami dasar-dasar Dialogflow.
2. Lakukan langkah-langkah penyiapan.
3. Lakukan langkah-langkah dalam panduan memulai Membangun agen. Langkah-langkah di bawah ini akan terus memproses agen yang Anda mulai dalam panduan tersebut. Jika tidak lagi memiliki agen tersebut, Anda dapat mendownload build-agent-quickstart.zip dan mengimpor file.

Sesi

Sesi mewakili percakapan antara agen Dialogflow dan pengguna akhir. Anda membuat sesi di awal percakapan dan menggunakannya untuk setiap giliran percakapan. Setelah percakapan berakhir, Anda menghentikan penggunaan sesi.

Anda tidak boleh menggunakan sesi yang sama untuk percakapan serentak dengan pengguna akhir yang berbeda. Dialogflow mempertahankan konteks yang saat ini aktif untuk setiap sesi aktif. Data sesi disimpan oleh Dialogflow selama 20 menit.

Setiap sesi ditentukan secara unik oleh ID sesi yang dibuat oleh sistem Anda. Buat sesi baru dengan memberikan ID sesi baru dalam permintaan intent deteksi. ID sesi adalah string berukuran maksimal 36 byte. Sistem Anda bertanggung jawab untuk membuat ID sesi yang unik. ID dapat berupa angka acak, ID pengguna akhir yang di-hash, atau nilai lain yang mudah Anda buat.

Mendeteksi intent

Saat Anda menggunakan API untuk interaksi, layanan Anda berinteraksi langsung dengan pengguna akhir. Untuk setiap giliran percakapan, layanan Anda mengirimkan ekspresi pengguna akhir ke Dialogflow dengan memanggil metode detectIntent atau streamingDetectIntent dari jenis Sessions. Dialogflow merespons dengan informasi tentang intent yang cocok, tindakan, parameter, dan respons yang ditentukan untuk intent. Layanan Anda akan melakukan tindakan yang diperlukan (misalnya, kueri database atau panggilan API eksternal) dan mengirim pesan kepada pengguna akhir. Proses ini berlanjut hingga percakapan berakhir.

Contoh berikut menunjukkan cara mendeteksi intent. Setiap sampel menerima subset input berikut:

• Project ID: Gunakan project ID untuk project yang Anda buat dalam langkah penyiapan.
• ID sesi: Untuk menguji agen, Anda dapat menggunakan apa saja. Misalnya, "123456789" sering digunakan oleh sampel.
• Teks atau teks: Ini adalah ekspresi pengguna akhir tunggal atau daftar ekspresi pengguna akhir. Jika beberapa ekspresi diberikan, panggilan kode contoh akan mendeteksi intent untuk setiap ekspresi. Coba gunakan "Saya tahu bahasa Prancis".
• Kode bahasa: Kode bahasa untuk ekspresi pengguna akhir. Gunakan "en-US" untuk agen contoh ini.

REST

Untuk mendeteksi intent, panggil metode detectIntent pada resource Sessions.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• PROJECT_ID: project ID Google Cloud Anda
• SESSION_ID: ID sesi

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Anda akan melihat respons JSON seperti berikut:

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

Perhatikan hal-hal berikut tentang responsnya:

• Kolom queryResult.intent berisi intent yang cocok.
• Nilai kolom queryResult.fulfillmentMessages berisi respons intent. Ini adalah respons yang harus diteruskan sistem Anda ke pengguna akhir.
• Nilai kolom queryResult.parameters berisi parameter yang diekstrak dari ekspresi pengguna akhir.
• Kolom queryResult.outputContext berisi konteks aktif.

Go

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mengautentikasi ke Dialogflow, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Bahasa tambahan

C#: Ikuti Petunjuk penyiapan C# di halaman library klien lalu kunjungi Dokumentasi referensi Dialogflow untuk .NET.

PHP: Ikuti petunjuk penyiapan PHP di halaman library klien lalu kunjungi Dokumentasi referensi Dialogflow untuk PHP.

Ruby: Ikuti petunjuk penyiapan Ruby di halaman library klien, lalu buka Dokumentasi referensi Dialogflow untuk Ruby.

Produksi

Sebelum menjalankan agen dalam produksi, pastikan untuk menerapkan praktik terbaik produksi.