Migre da API Data QnA para a API Conversational Analytics

Este guia descreve as principais diferenças e os passos para migrar as suas aplicações da API Data QnA (dataqna.googleapis.com) para a API Conversational Analytics (geminidataanalytics.googleapis.com).

Enviar feedback

Se detetar alguma discrepância durante o processo de migração, contacte conversational-analytics-api-feedback@google.com.

Vista geral das principais alterações

A API Conversational Analytics introduz alterações ao ponto final da API, ao serviço que a API usa e à estrutura dos pedidos da API. A tabela seguinte resume as principais diferenças entre a API Data QnA e a API Conversational Analytics, e lista os passos necessários para a migração.

API Data QnA API Conversational Analytics Alteração necessária
dataqna.googleapis.com ponto final geminidataanalytics.googleapis.com ponto final Atualize o ponto final da API nos seus pedidos.
DataQuestionService serviço DataChatService serviço Atualize o nome do serviço nos seus pedidos.
Campo project na mensagem AskQuestionRequest Campo parent na mensagem ChatRequest Substitua o campo project pelo campo parent nos seus pedidos. Para mais informações, consulte o artigo Substitua project por parent para o encaminhamento de pedidos.
datasource_ids campo studio_references campo Substitua o campo datasource_ids pelo campo studio_references nos seus pedidos. Para mais informações, consulte o artigo Atualize as referências aos IDs das origens de dados do Looker Studio.
AgentConfig objeto ConversationOptions objeto Substitua o objeto AgentConfig pelo objeto ConversationOptions nos seus pedidos. Para mais informações, consulte o artigo Ative a análise Python com o ConversationOptions.
Campo context na mensagem AskQuestionRequest Campo inline_context na mensagem ChatRequest Substitua o campo context pelo campo inline_context nos seus pedidos. Para mais informações, consulte o artigo Substitua context por inline_context.

Para ver exemplos de como atualizar as estruturas de pedidos da API, consulte o artigo Exemplos: atualize as estruturas de pedidos da API.

Substitua project por parent para o encaminhamento de pedidos

Na API Data QnA, usa o campo project na mensagem AskQuestionRequest para especificar o Google Cloud projeto. Na API Conversational Analytics, o campo project está descontinuado na mensagem ChatRequest. Em alternativa, use o campo parent para especificar o projeto e a localização.

O exemplo seguinte mostra o formato para especificar o campo parent:

parent: "projects/your_project_name/locations/global"

No exemplo anterior, substitua your_project_name pelo nome do seu Google Cloud projeto.

Atualize as referências aos IDs das origens de dados do Looker Studio

Na API Data QnA, usa o campo datasource_ids para fornecer uma lista de IDs de origens de dados do Looker Studio. Na API Conversational Analytics, usa o campo studio_references para fornecer uma lista de objetos StudioDatasourceReference, cada um contendo um único ID de origem de dados. Para mais informações, consulte o artigo StudioDatasourceReferences.

Ative a análise de Python com o ConversationOptions

O objeto AgentConfig, que é usado na API Data QnA para ativar ferramentas, não é usado pelo serviço DataChatService na API Conversational Analytics. Para ativar funcionalidades como a análise Python na API Conversational Analytics, use o objeto ConversationOptions quando criar ou configurar um agente de dados. Para mais informações, consulte ConversationOptions.

Substituir context por inline_context

Na API Data QnA, a mensagem AskQuestionRequest inclui um campo context para informações contextuais incorporadas. Na API Conversational Analytics, o campo context é renomeado para inline_context na mensagem ChatRequest. Esta alteração ajuda a distinguir o contexto inline de outros tipos de contexto que podem ser fornecidos através de agentes de dados.

Exemplos: atualize as estruturas dos pedidos de API

Os exemplos seguintes mostram como adaptar os seus pedidos à nova estrutura da API quando migrar da API Data QnA para a API Conversational Analytics. Estes exemplos abrangem origens de dados do BigQuery, do Looker e do Looker Studio.

Origem de dados do BigQuery

Esta secção fornece um exemplo de como atualizar os pedidos API para origens de dados do BigQuery. O exemplo mostra como atualizar um pedido que pede um gráfico de barras que mostre os cinco principais estados pelo número total de aeroportos.

O seguinte exemplo de código mostra a estrutura do pedido da 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"
      }
    }
  }
}

O seguinte exemplo de código mostra a estrutura de pedido atualizada para a 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"
      }
    }
  }

Para os exemplos anteriores, pode substituir os valores de exemplo da seguinte forma:

  • your_project_name: o nome do seu Google Cloud projeto.
  • your_project_id: o ID do seu projeto do BigQuery. Para estabelecer ligação a um conjunto de dados público, especifique bigquery-public-data.
  • your_dataset_id: o ID do conjunto de dados do BigQuery. Por exemplo, faa.
  • your_table_id: o ID da tabela do BigQuery. Por exemplo, us_airports.

Origem de dados do Looker

Esta secção fornece um exemplo de como atualizar os pedidos da API para origens de dados do Looker. O exemplo mostra como atualizar um pedido que pede a quantidade de encomendas por estado da encomenda.

O seguinte exemplo de código mostra a estrutura do pedido da 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"
          }
        }
      }
    }
  }
}

O seguinte exemplo de código mostra a estrutura de pedido atualizada para a 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"
          }
        }
      }
    }
  }
}

Para os exemplos anteriores, pode substituir os valores de exemplo da seguinte forma:

  • your_project_name: o nome do seu Google Cloud projeto
  • https://your_company.looker.com: o URI da sua instância do Looker
  • your_model: o nome do seu modelo LookML
  • your_explore: o nome da sua exploração do LookML
  • your_looker_client_id: o seu ID de cliente do Looker
  • your_looker_client_secret: O segredo do cliente do Looker

Origem de dados do Looker Studio

Esta secção fornece um exemplo de como atualizar os seus pedidos de API para origens de dados do Looker Studio. O exemplo mostra como atualizar um pedido que pede um gráfico de barras que mostre as cinco principais transportadoras.

O seguinte exemplo de código mostra a estrutura do pedido da 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"
    }
  }
}

O seguinte exemplo de código mostra a estrutura de pedido atualizada para a 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"
    }
  }
}

Para os exemplos anteriores, pode substituir os valores de exemplo da seguinte forma:

  • your_project_name: o nome do seu Google Cloud projeto
  • your_data_source_id: o ID da sua origem de dados do Looker Studio