Panduan memulai: Interaksi dengan API

Jika tidak menggunakan integrasi, Anda harus menulis kode untuk berinteraksi dengan pengguna akhir. Untuk setiap giliran percakapan, kode Anda 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 tidak berencana menggunakan API, Anda dapat melewati 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 melanjutkan pengerjaan agen yang Anda mulai dalam panduan tersebut. Jika Anda tidak lagi memiliki agen tersebut, Anda dapat mendownload build-agent-quickstart.zip dan mengimpor file.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menyelesaikan tugas dalam panduan ini, minta administrator untuk memberi Anda peran IAM Dialogflow API Client (roles/dialogflow.client) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

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 berhenti menggunakan sesi tersebut.

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 unik oleh ID sesi yang dibuat oleh sistem Anda. Anda membuat sesi baru dengan memberikan ID sesi baru dalam permintaan deteksi intent. ID sesi adalah string dengan ukuran maksimal 36 byte. Sistem Anda bertanggung jawab untuk membuat ID sesi yang unik. ID ini 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 akan 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 tersebut. Layanan Anda melakukan tindakan sesuai kebutuhan (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 contoh menerima subset input berikut:

  • Project ID: Gunakan project ID untuk project yang Anda buat di langkah-langkah penyiapan.
  • ID Sesi: Untuk tujuan pengujian 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, kode contoh akan memanggil deteksi intent untuk setiap ekspresi. Coba gunakan "Saya bisa bahasa Prancis".
  • Kode bahasa: Kode bahasa untuk ekspresi pengguna akhir. Gunakan "en-US" untuk contoh agen 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:

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 terkait respons:

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

Go

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 "", 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

Untuk melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 melakukan autentikasi ke Dialogflow CX, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 buka dokumentasi referensi Dialogflow CX untuk .NET.

PHP: Ikuti petunjuk penyiapan PHP di halaman library klien, lalu lihat dokumentasi referensi Dialogflow CX untuk PHP.

Ruby: Ikuti petunjuk penyiapan Ruby di halaman library klien, lalu lihat dokumentasi referensi Dialogflow CX untuk Ruby.

Produksionalisasi

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

Sebelumnya
Interaksi dengan integrasi
Berikutnya
Ringkasan Konsol Dialogflow