Passer de l'API Data QnA à l'API Conversational Analytics

Ce guide décrit les principales différences et les étapes à suivre pour migrer vos applications de l'API Data QnA (dataqna.googleapis.com) vers l'API Conversational Analytics (geminidataanalytics.googleapis.com).

Fournir des commentaires

Si vous rencontrez des incohérences lors du processus de migration, contactez conversational-analytics-api-feedback@google.com.

Présentation des principales modifications

L'API Conversational Analytics apporte des modifications au point de terminaison de l'API, au service utilisé par l'API et à la structure des requêtes API. Le tableau suivant récapitule les principales différences entre l'API Data QnA et l'API Conversational Analytics, et liste les étapes requises pour la migration.

API Data QnA API Conversational Analytics Modification requise
Point de terminaison dataqna.googleapis.com Point de terminaison geminidataanalytics.googleapis.com Mettez à jour le point de terminaison de l'API dans vos requêtes.
Service DataQuestionService Service DataChatService Mettez à jour le nom du service dans vos requêtes.
Champ project dans le message AskQuestionRequest Champ parent dans le message ChatRequest Remplacez le champ project par le champ parent dans vos requêtes. Pour en savoir plus, consultez Remplacer project par parent pour le routage des requêtes.
Champ datasource_ids Champ studio_references Remplacez le champ datasource_ids par le champ studio_references dans vos requêtes. Pour en savoir plus, consultez Mettre à jour les références aux ID de sources de données Looker Studio.
Objet AgentConfig Objet ConversationOptions Remplacez l'objet AgentConfig par l'objet ConversationOptions dans vos requêtes. Pour en savoir plus, consultez Activer l'analyse Python avec ConversationOptions.
Champ context dans le message AskQuestionRequest Champ inline_context dans le message ChatRequest Remplacez le champ context par le champ inline_context dans vos requêtes. Pour en savoir plus, consultez Remplacer context par inline_context.

Pour obtenir des exemples de mise à jour de vos structures de requêtes d'API, consultez Exemples : Mettre à jour vos structures de requêtes d'API.

Remplacez project par parent pour le routage des requêtes.

Dans l'API Data QnA, vous utilisez le champ project du message AskQuestionRequest pour spécifier le projet Google Cloud . Dans l'API Conversational Analytics, le champ project est obsolète dans le message ChatRequest. Utilisez plutôt le champ parent pour spécifier à la fois le projet et l'emplacement.

L'exemple suivant montre comment spécifier le champ parent :

parent: "projects/your_project_name/locations/global"

Dans l'exemple précédent, remplacez your_project_name par le nom de votre projet Google Cloud .

Mettre à jour les références aux ID de sources de données Looker Studio

Dans l'API Data QnA, vous utilisez le champ datasource_ids pour fournir une liste d'ID de sources de données Looker Studio. Dans l'API Conversational Analytics, vous utilisez le champ studio_references pour fournir une liste d'objets StudioDatasourceReference, chacun contenant un seul ID de source de données. Pour en savoir plus, consultez StudioDatasourceReferences.

Activer l'analyse Python avec ConversationOptions

L'objet AgentConfig, utilisé dans l'API Data QnA pour activer les outils, n'est pas utilisé par le service DataChatService dans l'API Conversational Analytics. Pour activer des fonctionnalités telles que l'analyse Python dans l'API Conversational Analytics, utilisez l'objet ConversationOptions lorsque vous créez ou configurez un agent de données. Pour en savoir plus, consultez ConversationOptions.

Remplacer context par inline_context

Dans l'API Data QnA, le message AskQuestionRequest inclut un champ context pour les informations contextuelles intégrées. Dans l'API Conversational Analytics, le champ context est renommé inline_context dans le message ChatRequest. Cette modification permet de distinguer le contexte intégré des autres types de contexte qui peuvent être fournis par les agents de données.

Exemples : Mettre à jour les structures de vos requêtes d'API

Les exemples suivants montrent comment adapter vos requêtes à la nouvelle structure de l'API lorsque vous migrez de l'API Data QnA vers l'API Conversational Analytics. Ces exemples couvrent les sources de données BigQuery, Looker et Looker Studio.

Source de données BigQuery

Cette section fournit un exemple de mise à jour de vos requêtes d'API pour les sources de données BigQuery. L'exemple montre comment modifier une requête qui demande un graphique à barres affichant les cinq États les plus importants en termes de nombre total d'aéroports.

L'exemple de code suivant montre la structure de la requête pour l'API Data QnA :

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"
      }
    }
  }
}

L'exemple de code suivant montre la structure de requête mise à jour pour l'API Conversational Analytics :

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"
      }
    }
  }

Pour les exemples précédents, vous pouvez remplacer les exemples de valeurs comme suit :

  • your_project_name : nom de votre projet Google Cloud .
  • your_project_id : ID de votre projet BigQuery. Pour vous connecter à un ensemble de données public, spécifiez bigquery-public-data.
  • your_dataset_id : ID de l'ensemble de données BigQuery. Exemple :faa
  • your_table_id : ID de la table BigQuery. Exemple :us_airports

Source de données Looker

Cette section fournit un exemple de mise à jour de vos requêtes API pour les sources de données Looker. L'exemple montre comment mettre à jour une requête qui demande le nombre de commandes par état.

L'exemple de code suivant montre la structure de la requête pour l'API Data QnA :

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"
          }
        }
      }
    }
  }
}

L'exemple de code suivant montre la structure de requête mise à jour pour l'API Conversational Analytics :

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"
          }
        }
      }
    }
  }
}

Pour les exemples précédents, vous pouvez remplacer les exemples de valeurs comme suit :

  • your_project_name : nom de votre projet Google Cloud
  • https://your_company.looker.com : URI de votre instance Looker
  • your_model : nom de votre modèle LookML
  • your_explore : nom de votre exploration LookML
  • your_looker_client_id : ID client Looker
  • your_looker_client_secret : code secret du client Looker

Source de données Looker Studio

Cette section fournit un exemple de mise à jour de vos requêtes d'API pour les sources de données Looker Studio. L'exemple montre comment mettre à jour une requête qui demande un graphique à barres affichant les cinq principaux opérateurs.

L'exemple de code suivant montre la structure de la requête pour l'API Data QnA :

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"
    }
  }
}

L'exemple de code suivant montre la structure de requête mise à jour pour l'API Conversational Analytics :

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"
    }
  }
}

Pour les exemples précédents, vous pouvez remplacer les exemples de valeurs comme suit :

  • your_project_name : nom de votre projet Google Cloud
  • your_data_source_id : ID de votre source de données Looker Studio