Migrar da API Data QnA para a API Conversational Analytics

Neste guia, descrevemos as principais diferenças e etapas para migrar seus aplicativos da API Data QnA (dataqna.googleapis.com) para a API Conversational Analytics (geminidataanalytics.googleapis.com).

Enviar feedback

Se você encontrar discrepâncias durante o processo de migração, entre em contato com conversational-analytics-api-feedback@google.com.

Visão geral das principais mudanças

A API Conversational Analytics traz mudanças no endpoint de API, no serviço usado pela API e na estrutura das solicitações de API. A tabela a seguir resume as principais diferenças entre a API Data QnA e a API Conversational Analytics e lista as etapas necessárias de migração.

API Data QnA API Conversational Analytics Mudança obrigatória
Endpoint dataqna.googleapis.com Endpoint geminidataanalytics.googleapis.com Atualize o endpoint de API nas suas solicitações.
Serviço DataQuestionService Serviço DataChatService Atualize o nome do serviço nas suas solicitações.
Campo project na mensagem AskQuestionRequest Campo parent na mensagem ChatRequest Substitua o campo project pelo campo parent nas suas solicitações. Para mais informações, consulte Substituir project por parent no roteamento de solicitações.
Campo datasource_ids Campo studio_references Substitua o campo datasource_ids pelo campo studio_references nas suas solicitações. Para mais informações, consulte Atualizar referências aos IDs de fontes de dados do Looker Studio.
Objeto AgentConfig Objeto ConversationOptions Substitua o objeto AgentConfig pelo objeto ConversationOptions nas suas solicitações. Para mais informações, consulte Ativar a análise do Python com ConversationOptions.
Campo context na mensagem AskQuestionRequest Campo inline_context na mensagem ChatRequest Substitua o campo context pelo campo inline_context nas suas solicitações. Para mais informações, consulte Substituir context por inline_context.

Para conferir exemplos de como atualizar as estruturas de solicitação de API, consulte Exemplos: atualizar as estruturas de solicitação de API.

Substituir project por parent no roteamento de solicitações

Na API Data QnA, use o campo project na mensagem AskQuestionRequest para especificar o projeto Google Cloud . Na API Conversational Analytics, o campo project foi descontinuado na mensagem ChatRequest. Em vez disso, use o campo parent para especificar o projeto e o local.

O exemplo a seguir 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 projeto Google Cloud .

Atualizar referências aos IDs de fontes de dados do Looker Studio

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

Ativar a análise do Python com ConversationOptions

O objeto AgentConfig, usado na API Data QnA para ativar ferramentas, não é usado pelo serviço DataChatService na API Conversational Analytics. Para ativar recursos como a análise do Python na API Conversational Analytics, use o objeto ConversationOptions ao 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 de informações contextuais inline. Na API Conversational Analytics, o nome do campo context mudou para inline_context na mensagem ChatRequest. Essa mudança ajuda a distinguir o contexto inline de outros tipos de contexto que podem ser fornecidos por agentes de dados.

Exemplos: atualizar as estruturas de solicitação de API

Os exemplos a seguir mostram como adaptar suas solicitações à nova estrutura de API ao migrar da API Data QnA para a API Conversational Analytics. Esses exemplos abrangem fontes de dados do BigQuery, do Looker e do Looker Studio.

Fonte de dados do BigQuery

Nesta seção, você encontra um exemplo de como atualizar as solicitações de API de fontes de dados do BigQuery. O exemplo mostra como atualizar uma solicitação de um gráfico de barras com os cinco principais estados pelo número total de aeroportos.

O exemplo de código a seguir mostra a estrutura da solicitação 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 a seguir mostra a estrutura de solicitação atualizada da 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"
      }
    }
  }

Nos exemplos anteriores, é possível substituir os valores de exemplo da seguinte maneira:

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

Fonte de dados do Looker

Nesta seção, você encontra um exemplo de como atualizar as solicitações de API de fontes de dados do Looker. O exemplo mostra como atualizar uma solicitação de contagem de pedidos por status.

O exemplo de código a seguir mostra a estrutura da solicitação 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 a seguir mostra a estrutura de solicitação atualizada da 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"
          }
        }
      }
    }
  }
}

Nos exemplos anteriores, é possível substituir os valores de exemplo da seguinte maneira:

  • your_project_name: nome do projeto Google Cloud
  • https://your_company.looker.com: URI da sua instância do Looker
  • your_model: nome do seu modelo do LookML
  • your_explore: nome do Explore do LookML
  • your_looker_client_id: seu ID do cliente do Looker
  • your_looker_client_secret: sua chave secreta de cliente do Looker

Fonte de dados do Looker Studio

Nesta seção, você encontra um exemplo de como atualizar as solicitações de API de fontes de dados do Looker Studio. O exemplo mostra como atualizar uma solicitação de um gráfico de barras com as cinco principais companhias.

O exemplo de código a seguir mostra a estrutura da solicitação 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 a seguir mostra a estrutura de solicitação atualizada da 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"
    }
  }
}

Nos exemplos anteriores, é possível substituir os valores de exemplo da seguinte maneira:

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