從 Data QnA API 遷移至 Conversational Analytics API

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

提供意見回饋

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

主要異動總覽

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

如需更新 API 要求結構的範例，請參閱「範例：更新 API 要求結構」。

將 project 替換為 parent，以便轉送要求

在 Data QnA API 中，您可以使用 AskQuestionRequest 訊息中的 project 欄位指定 Google Cloud 專案。在 Conversational Analytics API 中，project 欄位已在 ChatRequest 訊息中淘汰。請改用 parent 欄位指定專案和位置。

以下範例顯示指定 parent 欄位的格式：

parent: "projects/PROJECT_NAME/locations/global"

在先前的範例中，請將 PROJECT_NAME 替換為您的 Google Cloud 專案名稱。

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

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

使用 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 和數據分析資料來源。

BigQuery 資料來源

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

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

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

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

• PROJECT_NAME：您 Google Cloud 專案的名稱。
• 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/PROJECT_NAME"
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/PROJECT_NAME/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"
      }
    }
  }
}

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

• PROJECT_NAME：您 Google Cloud 專案的名稱。
• CLIENT_ID：您產生的 Looker API 金鑰用戶端 ID。
• CLIENT_SECRET：您產生的 Looker API 金鑰用戶端密鑰。
• MODEL_NAME：LookML 模型的名稱。
• EXPLORE_NAME：LookML 探索的名稱。
• INSTANCE_URI：Looker 執行個體的 URI。

數據分析資料來源

本節提供範例，說明如何更新數據分析資料來源的 API 要求。這個範例說明如何更新要求，要求提供顯示前五大貨運公司的長條圖。

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

project: "projects/PROJECT_NAME"
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/PROJECT_NAME/locations/global"
inline_context {
  datasource_references {
    studio {
      datasource_ids: "DATA_SOURCE_ID"
    }
  }
}

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

• PROJECT_NAME：您 Google Cloud 專案的名稱。
• DATA_SOURCE_ID：數據分析資料來源的 ID。