Migrar da API de QnA de Dados para a API de Análise Conversacional,Migrar da API de QnA de Dados para a API de Análise Conversacional

Private Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Este guia descreve 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 ).

Fornecer feedback

Se você encontrar alguma discrepância durante o processo de migração, entre em contato com [e-mail] .

Visão geral das principais mudanças

A API de Análise Conversacional introduz alterações no endpoint da API, no serviço que a API utiliza e na estrutura das solicitações da API. A tabela a seguir resume as principais diferenças entre a API de QnA de Dados e a API de Análise Conversacional, além de listar as etapas necessárias para a migração.

API de perguntas e respostas de dados	API de análise conversacional	Mudança necessária
ponto final dataqna.googleapis.com	ponto final geminidataanalytics.googleapis.com	Atualize o endpoint da API em suas solicitações.
Serviço DataQuestionService	Serviço DataChatService	Atualize o nome do serviço em 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 obter mais informações, consulte Substituir project pelo parent para roteamento de solicitações .
campo datasource_ids	campo studio_references	Substitua o campo datasource_ids pelo campo studio_references nas suas solicitações. Para obter mais informações, consulte Atualizar referências aos IDs de fonte de dados do Looker Studio .
Objeto AgentConfig	Objeto ConversationOptions	Substitua o objeto AgentConfig pelo objeto ConversationOptions nas suas solicitações. Para obter mais informações, consulte Habilitar 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 obter mais informações, consulte Substituir context por inline_context .

Para obter exemplos de como atualizar suas estruturas de solicitação de API, consulte Exemplos: Atualizar suas estruturas de solicitação de API .

Substituir project pelo parent para roteamento de solicitação

Na API Data QnA, você usa o campo project dentro da mensagem AskQuestionRequest para especificar o Google Cloud projeto. Na API de Análise Conversacional, o campo project está obsoleto na mensagem ChatRequest . Em vez disso, você usa 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 seu Google Cloud projeto.

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

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

Habilitar análise Python com ConversationOptions

O objeto AgentConfig , usado na API Data QnA para habilitar ferramentas, não é usado pelo serviço DataChatService na API Conversational Analytics. Para habilitar recursos como a análise Python na API Conversational Analytics, use o objeto ConversationOptions ao criar ou configurar um agente de dados. Para obter 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 em linha. Na API Conversational Analytics, o campo context foi renomeado para inline_context na mensagem ChatRequest . Essa alteração ajuda a distinguir o contexto em linha de outros tipos de contexto que podem ser fornecidos por agentes de dados.

Exemplos: Atualize suas estruturas de solicitação de API

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

Fonte de dados do BigQuery

Esta seção fornece um exemplo de como atualizar suas solicitações de API para fontes de dados do BigQuery. O exemplo mostra como atualizar uma solicitação que solicita um gráfico de barras que mostre os cinco principais estados pelo número total de aeroportos.

O exemplo de código a seguir mostra a estrutura de solicitação para a 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 para a API de análise conversacional:

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, você pode substituir os valores de amostra da seguinte maneira:

• your_project_name : O nome do seu Google Cloud projeto.
• your_project_id : o ID do seu projeto do BigQuery. Para se conectar 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 .

Fonte de dados do Looker

Esta seção fornece um exemplo de como atualizar suas solicitações de API para fontes de dados do Looker. O exemplo mostra como atualizar uma solicitação que solicita a contagem de pedidos por status do pedido.

O exemplo de código a seguir mostra a estrutura de solicitação para a 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 para a API de análise conversacional:

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, você pode substituir os valores de amostra da seguinte maneira:

• 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 do seu LookML Explore
• your_looker_client_id : Seu ID de cliente Looker
• your_looker_client_secret : Seu segredo de cliente Looker

Fonte de dados do Looker Studio

Esta seção fornece um exemplo de como atualizar suas solicitações de API para fontes de dados do Looker Studio. O exemplo mostra como atualizar uma solicitação que solicita um gráfico de barras que mostra as cinco principais operadoras.

O exemplo de código a seguir mostra a estrutura de solicitação para a 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 para a API de análise conversacional:

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, você pode substituir os valores de amostra da seguinte maneira:

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