從 Data QnA API 遷移至 Conversational Analytics API

本指南說明主要差異,以及將應用程式從 Data QnA API (dataqna.googleapis.com) 遷移至對話式數據分析 API (geminidataanalytics.googleapis.com) 的步驟。

提供意見回饋

如果在遷移過程中發現任何不一致之處,請與 conversational-analytics-api-feedback@google.com 聯絡。

主要異動總覽

對話式數據分析 API 導入了 API 端點、API 使用的服務,以及 API 要求結構的變更。下表摘要列出 Data 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 欄位。詳情請參閱「更新數據分析資料來源 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 專案。在對話式數據分析 API 中,ChatRequest 訊息內的 project 欄位已淘汰。而是使用 parent 欄位同時指定專案和位置。

以下範例說明指定 parent 欄位的格式:

parent: "projects/BILLING_PROJECT/locations/global"

在上述範例中,請將 BILLING_PROJECT 替換為計費專案 ID。

更新數據分析資料來源 ID 的參照

在 Data QnA API 中,您可以使用 datasource_ids 欄位提供數據分析資料來源 ID 清單。在對話式數據分析 API 中,您可以使用 studio_references 欄位提供 StudioDatasourceReference 物件清單,每個物件都包含一個資料來源 ID。詳情請參閱「StudioDatasourceReference」。

啟用 Python 分析功能,並使用 ConversationOptions

AgentConfig 物件在 Data QnA API 中用於啟用工具,但 Conversational Analytics API 中的 DataChatService 服務不會使用該物件。如要在對話式數據分析 API 中啟用 Python 分析等功能,請在建立或設定資料代理時使用 ConversationOptions 物件。BigQuery 資料來源不支援 Python 分析。詳情請參閱「ConversationOptions」。

將 context 替換為 inline_context

在 Data QnA API 中,AskQuestionRequest 訊息包含 context 欄位,用於內嵌情境資訊。在對話式數據分析 API 中,ChatRequest 訊息的 context 欄位已重新命名為 inline_context。這項異動有助於區分內嵌背景資訊,以及可透過資料代理提供的其他類型背景資訊。

範例:更新 API 要求結構

以下範例說明如何從 Data QnA API 遷移至對話式數據分析 API,並根據新的 API 結構調整要求。這些範例涵蓋 BigQuery、Looker 和數據分析資料來源。

BigQuery 資料來源

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

下列程式碼範例顯示 Data QnA API 的要求結構:

project: "projects/BILLING_PROJECT"
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: "PROJECT_ID"
        dataset_id: "DATASET_ID"
        table_id: "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/BILLING_PROJECT/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "PROJECT_ID"
        dataset_id: "DATASET_ID"
        table_id: "TABLE_ID"
      }
    }
  }
}

在上述範例中,您可以按照下列方式替換範例值:

  • BILLING_PROJECT:計費專案的 ID。
  • PROJECT_ID:BigQuery 專案 ID。如要連結公開資料集,請指定 bigquery-public-data。
  • DATASET_ID:BigQuery 資料集的 ID。例如:faa。
  • TABLE_ID:BigQuery 資料表的 ID。例如:us_airports。

Looker 資料來源

本節提供範例,說明如何更新 Looker 資料來源的 API 要求。這個範例說明如何更新要求,依訂單狀態取得訂單數量。

下列程式碼範例顯示 Data QnA API 的要求結構:

project: "projects/BILLING_PROJECT"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "INSTANCE_URI"
        lookml_model: "MODEL_NAME"
        explore: "EXPLORE_NAME"
      }
      credentials {
        oauth {
          secret {
            client_id: "CLIENT_ID"
            client_secret: "CLIENT_SECRET"
          }
        }
      }
    }
  }
}

下列程式碼範例顯示 Conversational Analytics API 的更新要求結構:

messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
parent: "projects/BILLING_PROJECT/locations/global"
credentials {
  oauth {
    secret {
      client_id: "CLIENT_ID"
      client_secret: "CLIENT_SECRET"
    }
  }
}
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "MODEL_NAME"
        explore: "EXPLORE_NAME"
        looker_instance_uri: "INSTANCE_URI"
      }
    }
  }
}

在上述範例中,您可以按照下列方式替換範例值:

  • BILLING_PROJECT:計費專案的 ID。
  • CLIENT_ID:產生的 Looker API 金鑰用戶端 ID。
  • CLIENT_SECRET:產生的 Looker API 金鑰用戶端密鑰。
  • MODEL_NAME:LookML 模型的名稱。
  • EXPLORE_NAME:LookML 探索的名稱。
  • INSTANCE_URI:Looker 執行個體的 URI。

數據分析資料來源

本節提供範例,說明如何更新數據分析資料來源的 API 要求。這個範例說明如何更新要求,請 Gemini 製作長條圖,顯示前五大電信業者。

下列程式碼範例顯示 Data QnA API 的要求結構:

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

下列程式碼範例顯示 Conversational Analytics API 的更新要求結構:

messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
parent: "projects/BILLING_PROJECT/locations/global"
inline_context {
  datasource_references {
    studio {
      studio_references {
        datasource_id: "DATA_SOURCE_ID"
      }
    }
  }
}

在上述範例中,您可以按照下列方式替換範例值:

  • BILLING_PROJECT:計費專案的 ID。
  • DATA_SOURCE_ID:數據分析資料來源的 ID。