Migrar de la API de QnA de datos a la API de análisis conversacional

Esta guía describe las diferencias clave y los pasos para migrar sus aplicaciones de la API de Data QnA ( dataqna.googleapis.com ) a la API de análisis conversacional ( geminidataanalytics.googleapis.com ).

Proporcionar retroalimentación

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

Resumen de los cambios clave

La API de Análisis Conversacional introduce cambios en el punto de conexión de la API, el servicio que utiliza y la estructura de las solicitudes. La siguiente tabla resume las diferencias clave entre la API de Data QnA y la API de Análisis Conversacional, y enumera los pasos necesarios para la migración.

API de preguntas y respuestas sobre datos API de análisis conversacional Cambio requerido
punto final dataqna.googleapis.com punto final geminidataanalytics.googleapis.com Actualice el punto final de la API en sus solicitudes.
Servicio DataQuestionService Servicio DataChatService Actualice el nombre del servicio en sus solicitudes.
campo project en el mensaje AskQuestionRequest campo parent en el mensaje ChatRequest Reemplace el campo project con el campo parent en sus solicitudes. Para más información, consulte "Reemplazar project con parent para el enrutamiento de solicitudes" .
campo datasource_ids campo studio_references Reemplace el campo datasource_ids por el campo studio_references en sus solicitudes. Para obtener más información, consulte Actualizar referencias a los ID de origen de datos de Looker Studio .
Objeto AgentConfig Objeto ConversationOptions Reemplace el objeto AgentConfig por el objeto ConversationOptions en sus solicitudes. Para más información, consulte Habilitar el análisis de Python con ConversationOptions .
campo context en el mensaje AskQuestionRequest campo inline_context en el mensaje ChatRequest Reemplace el campo context por el campo inline_context en sus solicitudes. Para más información, consulte Reemplazar context por inline_context .

Para obtener ejemplos de cómo actualizar las estructuras de su solicitud de API, consulte Ejemplos: Actualizar las estructuras de su solicitud de API .

Reemplazar project con parent para el enrutamiento de solicitudes

En la API de preguntas y respuestas de datos, utilice el campo project dentro del mensaje AskQuestionRequest para especificar Google Cloud Proyecto. En la API de Análisis Conversacional, el campo project está obsoleto en el mensaje ChatRequest . En su lugar, se utiliza el campo parent para especificar tanto el proyecto como la ubicación.

El siguiente ejemplo muestra el formato para especificar el campo parent :

parent: "projects/your_project_name/locations/global"

En el ejemplo anterior, reemplace your_project_name con el nombre de su proyecto. Google Cloud proyecto.

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

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

Habilitar el análisis de Python con ConversationOptions

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

Reemplazar context con inline_context

En la API Data QnA, el mensaje AskQuestionRequest incluye un campo context para información contextual en línea. En la API Conversational Analytics, el campo de context se renombra como inline_context en el mensaje ChatRequest . Este cambio ayuda a distinguir el contexto en línea de otros tipos de contexto que pueden proporcionarse mediante agentes de datos.

Ejemplos: Actualice las estructuras de solicitud de API

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

Fuente de datos de BigQuery

Esta sección proporciona un ejemplo de cómo actualizar las solicitudes de API para las fuentes de datos de BigQuery. El ejemplo muestra cómo actualizar una solicitud que solicita un gráfico de barras que muestra los cinco estados con mayor número de aeropuertos.

El siguiente ejemplo de código muestra la estructura de 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"
      }
    }
  }
}

El siguiente ejemplo de código muestra la estructura de solicitud actualizada para la API de análisis 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 los ejemplos anteriores, puede reemplazar los valores de muestra de la siguiente manera:

  • your_project_name : El nombre de tu proyecto 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 : 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

Esta sección muestra un ejemplo de cómo actualizar las solicitudes de API para las fuentes de datos de Looker. El ejemplo muestra cómo actualizar una solicitud que solicita el recuento de pedidos por estado.

El siguiente ejemplo de código muestra la estructura de 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"
          }
        }
      }
    }
  }
}

El siguiente ejemplo de código muestra la estructura de solicitud actualizada para la API de análisis 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 los ejemplos anteriores, puede reemplazar los valores de muestra de la siguiente manera:

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

Fuente de datos de Looker Studio

Esta sección muestra un ejemplo de cómo actualizar las solicitudes de API para las fuentes de datos de Looker Studio. El ejemplo muestra cómo actualizar una solicitud que solicita un gráfico de barras que muestra los cinco operadores principales.

El siguiente ejemplo de código muestra la estructura de 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"
    }
  }
}

El siguiente ejemplo de código muestra la estructura de solicitud actualizada para la API de análisis 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 los ejemplos anteriores, puede reemplazar los valores de muestra de la siguiente manera:

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