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 の主な違いと、移行に必要な手順をまとめます。

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 では、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 オブジェクトのリストを指定します。各オブジェクトには 1 つのデータソース ID が含まれています。詳細については、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 で、ChatRequest メッセージの context フィールドの名前が inline_context に変更されました。この変更により、インライン コンテキストとデータ エージェントを介して提供される他のタイプのコンテキストを区別できます。

例: API リクエスト構造を更新する

次の例は、Data QnA API から Conversational Analytics API に移行する際に、新しい API 構造に合わせてリクエストを調整する方法を示しています。これらの例では、BigQuery、Looker、Looker Studio のデータソースについて説明します。

BigQuery データソース

このセクションでは、BigQuery データソースの API リクエストを更新する方法の例を示します。この例は、空港の合計数が多い上位 5 つの州を示す棒グラフをリクエストするリクエストの更新方法を示しています。

次のコードサンプルは、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 リクエストを更新する方法の例を示します。この例は、上位 5 社の携帯通信会社を示す棒グラフを求めるリクエストの更新方法を示しています。

次のコードサンプルは、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