クイックスタート: API の操作

会話ターンごとに、操作が行われます。インタラクション中に、エンドユーザーが Dialogflow CX に入力を送信し、Dialogflow CX がレスポンスを送信します。システムを実装して操作を処理する際には、API を使用する方法と統合を使用する方法の 2 つの選択肢が存在します。

API の使用時には、システム側で以下の処理を行う必要があります。

エージェントをビルドする。
エンドユーザー向けのユーザーインターフェースを用意する。
会話ターンごとに Dialogflow API を呼び出して、エンドユーザー入力を API に送信します。
エージェントのレスポンスが純粋に静的な（一般的でない）場合を除き、webhook サービスをホストして、Webhook 対応フルフィルメントを処理する必要があります。

統合を使用する場合、システムでは次の処理のみを行う必要があります。

エージェントをビルドする。
必要に応じて Webhook サービスを実装します。

次の図は、セッションの 1 回の対話ターンで実行される手順を示しています。

API フロー図。

エンドユーザーが、エンドユーザー入力と呼ばれる何かしらの情報を入力または発声します。
ユーザーインターフェースまたは統合システムが入力を受信し、インテント検出リクエストで Dialogflow API に転送します。
Dialogflow API がインテント検出リクエストを受信します。入力とインテントまたはフォームパラメータを照合し、必要に応じてパラメータを設定し、セッションの状態を更新します。Webhook 対応フルフィルメントを呼び出す必要がある場合、Webhook サービスに Webhook リクエストを送信します。それ以外の場合は、手順 6 に進みます。
Webhook サービスが Webhook リクエストを受け取ります。サービスは、外部 API の呼び出し、データベースのクエリや更新など、必要なアクションを実行します。
Webhook サービスがレスポンスをビルドし、Webhook レスポンスを Dialogflow CX に返します。
Dialogflow CX がインテント検出レスポンスを作成します。Webhook が呼び出された場合、Webhook レスポンスで提供されたレスポンスが使用されます。Webhook が呼び出されなかった場合は、エージェントで定義された静的レスポンスが使用されます。Dialogflow CX は、ユーザーインターフェースまたは統合システムにインテント検出レスポンスを送信します。
ユーザーインターフェースまたは統合システムがインテント検出レスポンスを受信し、テキストまたは音声のレスポンスをエンドユーザーに転送します。
エンドユーザーがレスポンスを確認または聞き取ります。

ガイドの目的

このガイドでは、統合を使用していないエージェントが 1 回の会話ターンで API を呼び出す方法について説明します（上の図の手順 2）。このガイドでは、お客様のエンドユーザーがユーザーインターフェースを実装する方法はご紹介していません。

始める前に

このガイドを読む前に、次の手順を行ってください。

Dialogflow CX の基本をご覧ください。
手順に沿って設定してください。
新しいエージェントを作成するか、エージェントをビルドするで作成したエージェントを引き続き使用します。

ID を収集する

次のサンプルでは、入力として複数の ID が必要です。プロジェクト ID、リージョン ID、エージェント ID は次の手順で確認できます。

Dialogflow CX Console を開きます。
Google Cloud プロジェクトを選択して、エージェントセレクタを開きます。
リスト内のエージェントのオプションメニューをクリックします。
コピー名ボタンをクリックします。
これにより、エージェントの完全な識別名がコピーされます。これには、
projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID の形式のプロジェクト ID、リージョン ID、エージェント ID が含まれます。

セッション ID も必要です。セッションは、Dialogflow CX エージェントとエンドユーザー間の会話を表します。会話の開始時に一意のセッション ID を作成し、会話のターンごとにそれを使用します。API を試す場合、test-session-123 のように、最大 36 バイトの任意の文字列 ID を使用できます。

detectIntent を呼び出す

次のサンプルでは、Sessions.detectIntent メソッドを呼び出します。

セッションリファレンスのプロトコルとバージョンを選択:

プロトコル	V3	V3beta1
REST	セッションリソース	セッションリソース
RPC	セッションインターフェース	セッションインターフェース
C++	SessionsClient	利用できません
C#	SessionsClient	利用できません
Go	SessionsClient	利用できません
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	利用不可	利用できません
Python	SessionsClient	SessionsClient
Ruby	利用不可	利用できません

REST

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
AGENT_ID: エージェント ID
REGION_ID: リージョン ID
SESSION_ID: セッション ID
END_USER_INPUT: エンドユーザーの入力

HTTP メソッドと URL:

POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

リクエストの本文（JSON）:

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。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://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。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://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "responseId": "38e8f23d-eed2-445e-a3e7-149b242dd669",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Ok, let's start a new order."
          ]
        }
      },
      {
        "text": {
          "text": [
            "I'd like to collect a bit more information from you."
          ]
        }
      },
      {
        "text": {
          "text": [
            "What color would you like?"
          ]
        }
      },
      {}
    ],
    "currentPage": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/flows/00000000-0000-0000-0000-000000000000/pages/ce0b88c4-9292-455c-9c59-ec153dad94cc",
      "displayName": "New Order"
    },
    "intent": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
      "displayName": "order.new"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": { ... },
    "match": {
      "intent": {
        "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
        "displayName": "order.new"
      },
      "resolvedInput": "I want to buy a shirt",
      "matchType": "INTENT",
      "confidence": 1
    }
  }
}

Java

Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.cx.v3beta1.QueryInput;
import com.google.cloud.dialogflow.cx.v3beta1.QueryResult;
import com.google.cloud.dialogflow.cx.v3beta1.SessionName;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsClient;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsSettings;
import com.google.cloud.dialogflow.cx.v3beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntent {

  // DialogFlow API Detect Intent sample with text inputs.
  public static Map<String, QueryResult> detectIntent(
      String projectId,
      String locationId,
      String agentId,
      String sessionId,
      List<String> texts,
      String languageCode)
      throws IOException, ApiException {
    SessionsSettings.Builder sessionsSettingsBuilder = SessionsSettings.newBuilder();
    if (locationId.equals("global")) {
      sessionsSettingsBuilder.setEndpoint("dialogflow.googleapis.com:443");
    } else {
      sessionsSettingsBuilder.setEndpoint(locationId + "-dialogflow.googleapis.com:443");
    }
    SessionsSettings sessionsSettings = sessionsSettingsBuilder.build();

    Map<String, QueryResult> queryResults = Maps.newHashMap();
    // Instantiates a client.

    // Note: close() needs to be called on the SessionsClient object to clean up resources
    // such as threads. In the example below, try-with-resources is used,
    // which automatically calls close().
    try (SessionsClient sessionsClient = SessionsClient.create(sessionsSettings)) {
      // Set the session name using the projectID (my-project-id), locationID (global), agentID
      // (UUID), and sessionId (UUID).
      SessionName session =
          SessionName.ofProjectLocationAgentSessionName(projectId, locationId, agentId, sessionId);

      // TODO : Uncomment if you want to print session path
      // System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input.
      for (String text : texts) {
        // Set the text (hello) for the query.
        TextInput.Builder textInput = TextInput.newBuilder().setText(text);

        // Build the query with the TextInput and language code (en-US).
        QueryInput queryInput =
            QueryInput.newBuilder().setText(textInput).setLanguageCode(languageCode).build();

        // Build the DetectIntentRequest with the SessionName and QueryInput.
        DetectIntentRequest request =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .build();

        // Performs the detect intent request.
        DetectIntentResponse response = sessionsClient.detectIntent(request);

        // Display the query result.
        QueryResult queryResult = response.getQueryResult();

        // TODO : Uncomment if you want to print queryResult
        // System.out.println("====================");
        // System.out.format("Query Text: '%s'\n", queryResult.getText());
        // System.out.format(
        //     "Detected Intent: %s (confidence: %f)\n",
        //     queryResult.getIntent().getDisplayName(),
        //         queryResult.getIntentDetectionConfidence());

        queryResults.put(text, queryResult);
      }
    }
    return queryResults;
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const location = 'global';
// const agentId = 'my-agent';
// const query = 'Hello';
// const languageCode = 'en'

// Imports the Google Cloud Some API library
const {SessionsClient} = require('@google-cloud/dialogflow-cx');
/**
 * Example for regional endpoint:
 *   const location = 'us-central1'
 *   const client = new SessionsClient({apiEndpoint: 'us-central1-dialogflow.googleapis.com'})
 */
const client = new SessionsClient();

async function detectIntentText() {
  const sessionId = Math.random().toString(36).substring(7);
  const sessionPath = client.projectLocationAgentSessionPath(
    projectId,
    location,
    agentId,
    sessionId
  );
  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  for (const message of response.queryResult.responseMessages) {
    if (message.text) {
      console.log(`Agent Response: ${message.text.text}`);
    }
  }
  if (response.queryResult.match.intent) {
    console.log(
      `Matched Intent: ${response.queryResult.match.intent.displayName}`
    );
  }
  console.log(
    `Current Page: ${response.queryResult.currentPage.displayName}`
  );
}

detectIntentText();

Python

def run_sample():
    # TODO(developer): Replace these values when running the function
    project_id = "YOUR-PROJECT-ID"
    # For more information about regionalization see https://cloud.google.com/dialogflow/cx/docs/how/region
    location_id = "YOUR-LOCATION-ID"
    # For more info on agents see https://cloud.google.com/dialogflow/cx/docs/concept/agent
    agent_id = "YOUR-AGENT-ID"
    agent = f"projects/{project_id}/locations/{location_id}/agents/{agent_id}"
    # For more information on sessions see https://cloud.google.com/dialogflow/cx/docs/concept/session
    session_id = uuid.uuid4()
    texts = ["Hello"]
    # For more supported languages see https://cloud.google.com/dialogflow/es/docs/reference/language
    language_code = "en-us"

    detect_intent_texts(agent, session_id, texts, language_code)


def detect_intent_texts(agent, 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."""
    session_path = f"{agent}/sessions/{session_id}"
    print(f"Session path: {session_path}\n")
    client_options = None
    agent_components = AgentsClient.parse_agent_path(agent)
    location_id = agent_components["location"]
    if location_id != "global":
        api_endpoint = f"{location_id}-dialogflow.googleapis.com:443"
        print(f"API Endpoint: {api_endpoint}\n")
        client_options = {"api_endpoint": api_endpoint}
    session_client = SessionsClient(client_options=client_options)

    for text in texts:
        text_input = session.TextInput(text=text)
        query_input = session.QueryInput(text=text_input, language_code=language_code)
        request = session.DetectIntentRequest(
            session=session_path, query_input=query_input
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print(f"Query text: {response.query_result.text}")
        response_messages = [
            " ".join(msg.text.text) for msg in response.query_result.response_messages
        ]
        print(f"Response text: {' '.join(response_messages)}\n")

プロダクション

エージェントを本番環境で実行する場合は、必ずプロダクションのベストプラクティスを実施してください。

統合による操作

Dialogflow CX コンソールの概要