Migra de la API de Data QnA a la API de Conversational Analytics

En esta guía, se describen las principales diferencias y los pasos para migrar tus aplicaciones desde la API de Data QnA (dataqna.googleapis.com) hasta la API de Conversational Analytics (geminidataanalytics.googleapis.com).

Proporciona comentarios

Si encuentras alguna discrepancia durante el proceso de migración, comunícate con conversational-analytics-api-feedback@google.com.

Descripción general de los cambios clave

La API de Conversational Analytics ingresa cambios en el extremo de API, el servicio que usa la API y la estructura de las solicitudes a la API. En la siguiente tabla, se resumen las diferencias clave entre la API de Data QnA y la de Conversational Analytics, y se enumeran los pasos necesarios para la migración.

API de Data QnA API de Conversational Analytics Cambio obligatorio
Extremo dataqna.googleapis.com Extremo geminidataanalytics.googleapis.com Actualiza el extremo de API en tus solicitudes.
Servicio DataQuestionService Servicio DataChatService Actualiza el nombre del servicio en tus solicitudes.
Campo project en el mensaje AskQuestionRequest Campo parent en el mensaje ChatRequest Reemplaza el campo project por el campo parent en tus solicitudes. Para obtener más información, consulta Reemplaza project por parent para el enrutamiento de solicitudes.
Campo datasource_ids Campo studio_references Reemplaza el campo datasource_ids por el campo studio_references en tus solicitudes. Para obtener más información, consulta Actualiza las referencias a los IDs de las fuentes de datos de Looker Studio.
Objeto AgentConfig Objeto ConversationOptions Reemplaza el objeto AgentConfig por el objeto ConversationOptions en tus solicitudes. Para obtener más información, consulta Habilita el análisis de Python con ConversationOptions.
Campo context en el mensaje AskQuestionRequest Campo inline_context en el mensaje ChatRequest Reemplaza el campo context por el campo inline_context en tus solicitudes. Para obtener más información, consulta Reemplaza context por inline_context.

Para ver ejemplos de cómo actualizar las estructuras de tus solicitudes a la API, consulta Ejemplos: cómo actualizar las estructuras de tus solicitudes a la API.

Reemplazar project por parent para el enrutamiento de solicitudes

En la API de Data QnA, usas el campo project dentro del mensaje AskQuestionRequest para especificar el proyecto de Google Cloud . En la API de Conversational Analytics, el campo project dejó de estar disponible en el mensaje ChatRequest. En su lugar, debes usar el campo parent para especificar el proyecto y la ubicación.

En el siguiente ejemplo, se muestra el formato para especificar el campo parent:

parent: "projects/your_project_name/locations/global"

En el ejemplo anterior, reemplaza your_project_name por el nombre de tu proyecto de Google Cloud .

Actualiza las referencias a los IDs de las fuentes de datos de Looker Studio

En la API de Data QnA, debes usar el campo datasource_ids para proporcionar una lista de IDs de fuentes de datos de Looker Studio. En la API de Conversational Analytics, se usa el campo studio_references para proporcionar una lista de objetos StudioDatasourceReference, cada uno de los cuales contiene un solo ID de fuente de datos. Para obtener más información, consulta StudioDatasourceReferences.

Habilita el análisis de Python con ConversationOptions

El objeto AgentConfig, que se usa en la API de Data QnA para habilitar herramientas, no lo usa el servicio DataChatService en la API de Conversational Analytics. Para habilitar funciones, como el análisis de Python en la API de Conversational Analytics, usa el objeto ConversationOptions cuando crees o configures un agente de datos. Para obtener más información, consulta ConversationOptions.

Reemplaza context por inline_context

En la API de Data QnA, el mensaje AskQuestionRequest incluye un campo context para la información contextual intercalada. En la API de Conversational Analytics, el campo context se cambió a inline_context en el mensaje ChatRequest. Este cambio ayuda a distinguir el contexto intercalado de otros tipos de contexto que se pueden proporcionar a través de los agentes de datos.

Ejemplos: cómo actualizar las estructuras de tus solicitudes a la API

En los siguientes ejemplos, se muestra cómo adaptar tus solicitudes a la nueva estructura de la API cuando migres de la API de Data QnA a la de Conversational Analytics. En estos ejemplos, se abarcan las fuentes de datos de BigQuery, Looker y Looker Studio.

Fuente de datos de BigQuery

En esta sección, se proporciona un ejemplo de cómo actualizar tus solicitudes a la API para las fuentes de datos de BigQuery. En el ejemplo, se muestra cómo actualizar una solicitud que pide un gráfico de barras que muestre los cinco estados principales según la cantidad total de aeropuertos.

En la siguiente muestra de código, se ve la estructura de la solicitud para la API de 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"
      }
    }
  }
}

En la siguiente muestra de código, se ve la estructura de solicitud actualizada para la API de 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"
      }
    }
  }

En los ejemplos anteriores, puedes reemplazar los valores de muestra de la siguiente manera:

  • your_project_name: el nombre de tu proyecto de Google Cloud
  • your_project_id: el ID de tu proyecto de BigQuery. Para conectarte a un conjunto de datos públicos, especifica bigquery-public-data
  • your_dataset_id: el ID del conjunto de datos de BigQuery. Por ejemplo, faa
  • your_table_id: el ID de la tabla de BigQuery. Por ejemplo, us_airports

Fuente de datos de Looker

En esta sección, se proporciona un ejemplo de cómo actualizar tus solicitudes a la API para las fuentes de datos de Looker. En el ejemplo, se muestra cómo actualizar una solicitud que pide el recuento de pedidos por estado.

En la siguiente muestra de código, se ve la estructura de la solicitud para la API de 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"
          }
        }
      }
    }
  }
}

En la siguiente muestra de código, se ve la estructura de solicitud actualizada para la API de 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"
          }
        }
      }
    }
  }
}

En los ejemplos anteriores, puedes reemplazar los valores de muestra de la siguiente manera:

  • your_project_name: el nombre de tu proyecto de Google Cloud
  • https://your_company.looker.com: el URI de tu instancia de Looker
  • your_model: el nombre de tu modelo de LookML
  • your_explore: el nombre de tu exploración de LookML
  • your_looker_client_id: tu ID de cliente de Looker
  • your_looker_client_secret: tu secreto del cliente de Looker

Fuente de datos de Looker Studio

En esta sección, se proporciona un ejemplo de cómo actualizar tus solicitudes a la API para las fuentes de datos de Looker Studio. En el ejemplo, se muestra cómo actualizar una solicitud que pide un gráfico de barras que muestre las cinco empresas de transporte principales.

En la siguiente muestra de código, se ve la estructura de la solicitud para la API de 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"
    }
  }
}

En la siguiente muestra de código, se ve la estructura de solicitud actualizada para la API de 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"
    }
  }
}

En los ejemplos anteriores, puedes reemplazar los valores de muestra de la siguiente manera:

  • your_project_name: el nombre de tu proyecto de Google Cloud
  • your_data_source_id: el ID de tu fuente de datos de Looker Studio