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.
Campo datasource_ids Campo studio_references 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.

Substituir 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 exemplo de código seguinte 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 exemplo de código seguinte 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 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 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 apresenta 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 exemplo de código seguinte 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