Migrar de la API Data QnA a la API Conversational Analytics

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

Enviar comentarios

Si detectas alguna discrepancia durante el proceso de migración, ponte en contacto con conversational-analytics-api-feedback@google.com.

Resumen de los cambios clave

La API Conversational Analytics introduce cambios en el endpoint de la API, el servicio que utiliza la API y la estructura de las solicitudes de la API. En la siguiente tabla se resumen las principales diferencias entre la API Data QnA y la API Conversational Analytics, y se indican los pasos necesarios para la migración.

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

Para ver ejemplos de cómo actualizar las estructuras de las solicitudes de la API, consulte Ejemplos: actualice las estructuras de las solicitudes de la API.

Sustituye project por parent para enrutar las solicitudes.

En la API Data QnA, se usa el campo project del mensaje AskQuestionRequest para especificar el Google Cloud proyecto. En la API Conversational Analytics, el campo project ya no está disponible en el mensaje ChatRequest. En su lugar, utiliza el campo parent para especificar tanto el proyecto como 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, sustituye your_project_name por el nombre de tu Google Cloud proyecto.

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

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

Habilitar el análisis de Python con ConversationOptions

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

Reemplazar context por inline_context

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

Ejemplos: actualizar las estructuras de las solicitudes de la API

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

Fuente de datos de BigQuery

En esta sección se muestra un ejemplo de cómo actualizar las solicitudes de 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 con el mayor número de aeropuertos.

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

En el siguiente ejemplo de código se muestra la estructura de solicitud actualizada de la 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"
      }
    }
  }

En los ejemplos anteriores, puede sustituir los valores de ejemplo de la siguiente manera:

  • your_project_name: el nombre de tu Google Cloud proyecto.
  • your_project_id: el ID de tu proyecto de BigQuery. Para conectarte a un conjunto de datos público, especifica bigquery-public-data.
  • your_dataset_id: 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 muestra un ejemplo de cómo actualizar las solicitudes a la API de 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 el siguiente código de muestra se muestra la estructura de la solicitud de la 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"
          }
        }
      }
    }
  }
}

En el siguiente ejemplo de código se muestra la estructura de solicitud actualizada de la 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"
          }
        }
      }
    }
  }
}

En los ejemplos anteriores, puede sustituir los valores de ejemplo de la siguiente manera:

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

Fuente de datos de Looker Studio

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

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

En el siguiente ejemplo de código se muestra la estructura de solicitud actualizada de la 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"
    }
  }
}

En los ejemplos anteriores, puede sustituir los valores de ejemplo de la siguiente manera:

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