API로 상호작용

CX용 API 사용은 새로운 유형, 메서드, 필드를 수용하기 위해 일부 리소스 경로와 메서드를 수정했다는 점을 제외하면 ES용 API 사용과 유사합니다.

시스템에서는 다음과 같은 사항을 처리해야 합니다.

  • Dialogflow CX는 현재까지 제한된 개수의 통합만 지원하므로 최종 사용자와 직접 상호작용하기 위한 사용자 인터페이스를 시스템에서 제공해야 할 수 있습니다.
  • 최종 사용자 입력을 API에 전송하려면 각 대화 차례마다 Dialogflow API를 호출해야 합니다.
  • 에이전트 응답이 완전히 정적인 경우(일반적이지 않음)를 제외하고 웹훅 사용 fulfillment를 처리하려면 웹훅 서비스를 호스팅해야 합니다.

다음 다이어그램은 세션에서 한 개의 대화 차례 동안 진행되는 단계를 보여줍니다.

API 흐름 다이어그램

  1. 최종 사용자가 내용을 입력하거나 말합니다. 이를 최종 사용자 입력이라고 합니다.
  2. 사용자 인터페이스 시스템이 입력을 수신하여 인텐트 인식 요청에서 Dialogflow API로 전달합니다.
  3. Dialogflow API가 인텐트 인식 요청을 수신합니다. 입력을 인텐트 또는 양식 매개변수와 일치시키고, 필요에 따라 매개변수를 설정하며, 세션 상태를 업데이트합니다. 웹훅 사용 fulfillment를 호출해야 하는 경우 웹훅 서비스에 웹훅 요청을 보냅니다. 그 이외의 경우 6단계로 이동합니다.
  4. 웹훅 서비스가 웹훅 요청을 수신합니다. 이 서비스는 외부 API 호출, 데이터베이스 쿼리 또는 업데이트 등 필요한 작업을 수행합니다.
  5. 웹훅 서비스가 응답을 빌드하고 Dialogflow 응답을 다시 Dialogflow로 보냅니다.
  6. Dialogflow가 인텐트 인식 응답을 만듭니다. 웹훅이 호출된 경우 웹훅 응답에 제공된 응답을 사용합니다. 웹훅이 호출되지 않은 경우 에이전트에 정의된 정적 응답을 사용합니다. Dialogflow는 사용자 인터페이스 시스템에 인텐트 인식 응답을 보냅니다.
  7. 사용자 인터페이스 시스템은 인텐트 인식 응답을 수신하고 텍스트 또는 오디오 응답을 최종 사용자에게 전달합니다.
  8. 최종 사용자가 응답을 보거나 듣습니다.

최종 사용자 입력을 처리하기 위해 CX API로 보내는 것은 ES API와 매우 유사합니다. 아래 예시에서는 Sessions 리소스의 detectIntent 메서드를 호출합니다.

세션 참조의 프로토콜 및 버전을 선택합니다.

프로토콜 V3 V3beta1
REST 세션 리소스 세션 리소스
RPC 세션 인터페이스 세션 인터페이스
C# 없음 없음
Go 없음 없음
자바 SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 없음 없음
Python SessionsClient SessionsClient
Ruby 없음 해당 사항 없음

REST 및 명령줄

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • project-id: GCP 프로젝트 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"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 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
  }
}

자바


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