從 Data QnA API 遷移至 Conversational Analytics API

本指南說明主要差異，以及將應用程式從 Data QnA API (dataqna.googleapis.com) 遷移至 Conversational Analytics API (geminidataanalytics.googleapis.com) 的步驟。

提供意見回饋

如果在遷移過程中發現任何差異，請與 conversational-analytics-api-feedback@google.com 聯絡。

主要異動總覽

對話式數據分析 API 導入了 API 端點、API 使用的服務，以及 API 要求結構的變更。下表摘要列出 Data QnA API 和 Conversational Analytics API 的主要差異，並列出遷移作業的必要步驟。

Data QnA API 對話式數據分析 API 必要變更
dataqna.googleapis.com 端點 geminidataanalytics.googleapis.com 端點 更新要求中的 API 端點。
DataQuestionService 項服務 DataChatService 項服務 在要求中更新服務名稱。
AskQuestionRequest 訊息中的 project 欄位 ChatRequest 訊息中的 parent 欄位 在要求中，將 project 欄位替換為 parent 欄位。詳情請參閱「Replace project with parent for request routing」。
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 中，ChatRequest 訊息內的 project 欄位已淘汰。請改用 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 欄位提供 StudioDatasourceReference 物件清單，每個物件都包含單一資料來源 ID。詳情請參閱 StudioDatasourceReferences。

使用 ConversationOptions 啟用 Python 分析

在 Data QnA API 中用於啟用工具的 AgentConfig 物件，不會在 Conversational Analytics API 的 DataChatService 服務中使用。如要在 Conversational Analytics API 中啟用 Python 分析等功能，請在建立或設定資料代理程式時使用 ConversationOptions 物件。詳情請參閱「ConversationOptions」。

以 inline_context 取代 context

在 Data QnA API 中，AskQuestionRequest 訊息包含 context 欄位，可提供內嵌的脈絡資訊。在 Conversational Analytics API 中，ChatRequest 訊息中的 context 欄位已重新命名為 inline_context。這項變更可協助區分內嵌背景資訊，以及可透過資料代理程式提供的其他類型背景資訊。

範例：更新 API 要求結構

下列範例說明從 Data QnA API 遷移至 Conversational Analytics API 時，如何調整要求以符合新版 API 結構。這些範例涵蓋 BigQuery、Looker 和 Looker Studio 資料來源。

BigQuery 資料來源

本節提供範例，說明如何更新 BigQuery 資料來源的 API 要求。這個範例說明如何更新要求，要求顯示機場總數前五名的州別長條圖。

以下程式碼範例顯示 Data 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 要求。這個範例說明如何更新要求，依訂單狀態取得訂單數量。

以下程式碼範例顯示 Data 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 要求。這個範例說明如何更新要求，以取得顯示前五大貨運公司的長條圖。

以下程式碼範例顯示 Data 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