API による操作

CX 用 APIの使用は ES 用 API の使用と似ていますが、新しい型、メソッド、フィールドに合わせて一部のリソースパスとメソッドが変更されています。

システムで次の処理を行う必要があります。

  • Dialogflow CX は現在、限られた数の統合しかサポートしていないため、システムがエンドユーザーと直接対話するためのユーザー インターフェースを提供する必要があります。
  • 会話ターンごとに Dialogflow API を呼び出して、エンドユーザー入力を API に送信する必要があります。
  • エージェントのレスポンスが純粋に静的な(一般的でない)場合を除き、webhook サービスをホストして、Webhook 対応フルフィルメントを処理する必要があります。

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

API フロー図。

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

処理のためにエンドユーザー入力を CX API に送信する方法は、ES API とよく似ています。以下の例では、Sessions リソースの detectIntent メソッドを呼び出します。

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

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

REST とコマンドライン

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

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

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

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

{
  "responseId": "89dd432b-1df4-48c4-be6b-d6550c3422b0",
  "queryResult": {
    "text": "I want to ask about data plans for international travel.",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Sure! I can help with that. "
          ]
        }
      },
      {
        "text": {
          "text": [
            "I need to ask a few questions before I can find the best option for you."
          ]
        }
      },
      {
        "text": {
          "text": [
            "What's your name?"
          ]
        }
      }
    ],
    "currentPage": {
      "name": "projects/project-id/locations/region-id/agents/027ac861-f275-45ed-a879-92aeb554df4e/pages/48d4352f-c995-4e46-8857-999709882959",
      "displayName": "Collect Customer Info"
    },
    "intent": {
      "name": "projects/project-id/locations/region-id/agents/027ac861-f275-45ed-a879-92aeb554df4e/intents/d48acf76-10f6-491f-be0c-cb58e1ce74d6",
      "displayName": "Data Plan Intent"
    },
    "intentDetectionConfidence": 1
  }
}

Java


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
    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.of(projectId, locationId, agentId, sessionId);
      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();

        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
  );
  console.info(sessionPath);

  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  console.log(`User Query: ${query}`);
  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")