Data QnA API에서 Conversational Analytics API로 이전

이 가이드에서는 데이터 QnA API (dataqna.googleapis.com)에서 Conversational Analytics API (geminidataanalytics.googleapis.com)로 애플리케이션을 이전하는 데 필요한 주요 차이점과 단계를 설명합니다.

의견 보내기

이전 프로세스 중에 불일치가 발생하면 conversational-analytics-api-feedback@google.com에 문의하세요.

주요 변경사항 개요

Conversational Analytics API는 API 엔드포인트, API가 사용하는 서비스, API 요청 구조를 변경합니다. 다음 표에는 데이터 QnA API와 대화형 분석 API의 주요 차이점이 요약되어 있으며 이전하는 데 필요한 단계가 나열되어 있습니다.

Data QnA API Conversational Analytics API 필요한 변경사항
dataqna.googleapis.com 엔드포인트 geminidataanalytics.googleapis.com 엔드포인트 요청에서 API 엔드포인트를 업데이트합니다.
DataQuestionService 서비스 DataChatService 서비스 요청에서 서비스 이름을 업데이트합니다.
AskQuestionRequest 메시지의 project 필드 ChatRequest 메시지의 parent 필드 요청에서 project 필드를 parent 필드로 바꿉니다. 자세한 내용은 요청 라우팅을 위해 project을 parent로 대체를 참고하세요.
datasource_ids 필드 studio_references 필드 요청에서 datasource_ids 필드를 studio_references 필드로 바꿉니다. 자세한 내용은 Looker Studio 데이터 소스 ID 참조 업데이트를 참고하세요.
AgentConfig 객체 ConversationOptions 객체 요청에서 AgentConfig 객체를 ConversationOptions 객체로 바꿉니다. 자세한 내용은 ConversationOptions로 Python 분석 사용 설정을 참고하세요.
AskQuestionRequest 메시지의 context 필드 ChatRequest 메시지의 inline_context 필드 요청에서 context 필드를 inline_context 필드로 바꿉니다. 자세한 내용은 context을 inline_context로 바꾸기를 참고하세요.

API 요청 구조를 업데이트하는 방법의 예는 예: API 요청 구조 업데이트를 참고하세요.

요청 라우팅을 위해 project을 parent로 바꿉니다.

Data QnA API에서는 AskQuestionRequest 메시지 내의 project 필드를 사용하여 Google Cloud 프로젝트를 지정합니다. Conversational Analytics API에서 project 필드는 ChatRequest 메시지 내에서 지원 중단됩니다. 대신 parent 필드를 사용하여 프로젝트와 위치를 모두 지정합니다.

다음 예는 parent 필드를 지정하는 형식을 보여줍니다.

parent: "projects/your_project_name/locations/global"

이전 예시에서 your_project_name를 Google Cloud 프로젝트 이름으로 바꿉니다.

Looker Studio 데이터 소스 ID에 대한 참조 업데이트

Data QnA API에서는 datasource_ids 필드를 사용하여 Looker Studio 데이터 소스 ID 목록을 제공합니다. Conversational Analytics API에서는 studio_references 필드를 사용하여 단일 데이터 소스 ID가 각각 포함된 StudioDatasourceReference 객체 목록을 제공합니다. 자세한 내용은 StudioDatasourceReferences를 참고하세요.

ConversationOptions로 Python 분석 사용 설정

도구를 사용 설정하기 위해 Data QnA API에서 사용되는 AgentConfig 객체는 Conversational Analytics API의 DataChatService 서비스에서 사용되지 않습니다. Conversational Analytics API에서 Python 분석과 같은 기능을 사용 설정하려면 데이터 에이전트를 만들거나 구성할 때 ConversationOptions 객체를 사용하세요. 자세한 내용은 ConversationOptions를 참고하세요.

context를 inline_context로 바꾸기

Data QnA API에서 AskQuestionRequest 메시지에는 인라인 컨텍스트 정보의 context 필드가 포함됩니다. Conversational Analytics API에서 context 필드는 ChatRequest 메시지에서 inline_context로 이름이 변경됩니다. 이 변경사항은 데이터 에이전트를 통해 제공될 수 있는 다른 유형의 컨텍스트와 인라인 컨텍스트를 구분하는 데 도움이 됩니다.

예: API 요청 구조 업데이트

다음 예시에서는 Data QnA API에서 Conversational Analytics API로 이전할 때 새 API 구조에 맞게 요청을 조정하는 방법을 보여줍니다. 이 예에서는 BigQuery, Looker, Looker Studio 데이터 소스를 다룹니다.

BigQuery 데이터 소스

이 섹션에서는 BigQuery 데이터 소스에 대한 API 요청을 업데이트하는 방법을 보여주는 예를 제공합니다. 이 예에서는 공항 수 기준 상위 5개 주를 보여주는 막대 그래프를 요청하는 방법을 보여줍니다.

다음 코드 샘플은 데이터 QnA API의 요청 구조를 보여줍니다.

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }
}

다음 코드 샘플은 Conversational Analytics API의 업데이트된 요청 구조를 보여줍니다.

messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }

이전 예시의 경우 샘플 값을 다음과 같이 바꿀 수 있습니다.

  • your_project_name: Google Cloud 프로젝트의 이름
  • your_project_id: BigQuery 프로젝트의 ID입니다. 공개 데이터 세트에 연결하려면 bigquery-public-data를 지정합니다.
  • your_dataset_id: BigQuery 데이터 세트의 ID입니다. 예를 들면 faa입니다.
  • your_table_id: BigQuery 테이블의 ID입니다. 예를 들면 us_airports입니다.

Looker 데이터 소스

이 섹션에서는 Looker 데이터 소스의 API 요청을 업데이트하는 방법을 보여주는 예를 제공합니다. 이 예시에서는 주문 상태별 주문 수를 요청하는 요청을 업데이트하는 방법을 보여줍니다.

다음 코드 샘플은 데이터 QnA API의 요청 구조를 보여줍니다.

project: "projects/your_project_name"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "https://your_company.looker.com"
        lookml_model: "your_model"
        explore: "your_explore"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

다음 코드 샘플은 Conversational Analytics API의 업데이트된 요청 구조를 보여줍니다.

messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "your_model"
        explore: "your_explore"
        looker_instance_uri: "https://your_company.looker.com"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

이전 예시의 경우 샘플 값을 다음과 같이 바꿀 수 있습니다.

  • your_project_name: Google Cloud 프로젝트의 이름
  • https://your_company.looker.com: Looker 인스턴스의 URI
  • your_model: LookML 모델의 이름
  • your_explore: LookML Explore의 이름
  • your_looker_client_id: Looker 클라이언트 ID
  • your_looker_client_secret: Looker 클라이언트 보안 비밀번호

Looker Studio 데이터 소스

이 섹션에서는 Looker Studio 데이터 소스의 API 요청을 업데이트하는 방법을 보여주는 예를 제공합니다. 이 예시에서는 상위 5개 운송업체를 보여주는 막대 그래프를 요청하는 요청을 업데이트하는 방법을 보여줍니다.

다음 코드 샘플은 데이터 QnA API의 요청 구조를 보여줍니다.

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

다음 코드 샘플은 Conversational Analytics API의 업데이트된 요청 구조를 보여줍니다.

messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

이전 예시의 경우 샘플 값을 다음과 같이 바꿀 수 있습니다.

  • your_project_name: Google Cloud 프로젝트의 이름
  • your_data_source_id: Looker Studio 데이터 소스의 ID