Exportar datos a BigQuery

En esta página se describe cómo subir datos de productos y eventos de usuario del comercio a BigQuery. Una vez que tus datos estén en BigQuery, podrás usarlos para hacer previsiones de ventas con Vertex AI y verlos en paneles de Looker prediseñados.

Si tus datos de comercio ya están en tablas de eventos de producto y de usuario en BigQuery, en el formato de Vertex AI Search para comercio, puedes saltarte esta página e ir directamente a Obtener paneles de control que muestren indicadores clave del rendimiento y Generar previsiones de ventas a partir de datos de comercio. Para obtener más información sobre el formato, consulta los artículos Esquema de producto y Acerca de los eventos de usuario.

Antes de empezar

Antes de exportar sus datos de comercio a BigQuery, debe haber completado los procedimientos que se describen en la sección Configuración inicial.

Entre los datos que recoge se incluyen los siguientes:

• Importar información de catálogos.
• Registrar eventos de usuario en tiempo real.
• Importar historial de eventos de usuario.

Crear un conjunto de datos en BigQuery

Debe crear uno o dos conjuntos de datos en BigQuery para almacenar los datos de eventos de producto y de usuario.

Puedes usar un conjunto de datos para almacenar ambos tipos de datos o crear dos conjuntos de datos, uno para cada tipo de datos.

Debes crear los conjuntos de datos en el mismo proyecto en el que hayas implementado Vertex AI Search para el comercio.

1. Si no has usado BigQuery en tu proyecto antes, habilita la API BigQuery y asegúrate de que tienes el rol de gestión de identidades y accesos que te permite crear conjuntos de datos y tablas.

   Consulta las secciones Antes de empezar y Control de acceso con IAM de la documentación de BigQuery.

2. Crea un conjunto de datos en BigQuery en la multirregión de EE. UU.. Por ejemplo, llámalo retail_data.

   Nota: Los datos de eventos de usuario de Vertex AI Search para el sector del comercio no se pueden exportar a regiones que no sean de EE. UU. Ten en cuenta que Vertex AI Search para el comercio no usa información personal identificable. Si eliges una región de la UE para la ubicación del conjunto de datos, tus datos de cliente principales de BigQuery residirán en la UE. Los Datos de Cliente Principales de BigQuery se definen en los Términos Específicos del Servicio de BigQuery.

3. Opcional: Para colocar los datos de eventos de usuario en un conjunto de datos independiente de los datos de producto, cree un segundo conjunto de datos. Por ejemplo, llámalo retail_user_event_data.

Para obtener más información sobre cómo crear conjuntos de datos de BigQuery, consulta la documentación de BigQuery.

Este conjunto de datos se usará para almacenar las tablas de datos que exporte. En los siguientes procedimientos se describe cómo exportar.

Exportar el catálogo de Vertex AI Search para el comercio a una tabla de BigQuery

Usa el método export para exportar tu catálogo de comercio a una tabla de BigQuery.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: ID del proyecto de la API Vertex AI Search for commerce en el que ha creado el conjunto de datos de BigQuery.
• BRANCH_ID: ID de la rama del catálogo. Usa default_branch para obtener datos de la rama predeterminada. Para obtener más información, consulta Ramas de catálogo.
• DATASET_ID: el nombre del conjunto de datos que has creado en Crear un conjunto de datos en BigQuery. Por ejemplo, usa retail_data o retail_product_data. El conjunto de datos debe estar en el mismo proyecto. No añadas el ID de proyecto al campo datasetId.
• TABLE_ID_PREFIX: prefijo del ID de la tabla. Este prefijo no puede ser una cadena vacía. Se añade el sufijo retail_products para completar el nombre de la tabla. Por ejemplo, si el prefijo es test, la tabla se llama test_retail_products.

Cuerpo JSON de la solicitud:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Para enviar tu solicitud, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

A continuación, ejecuta el siguiente comando para enviar tu solicitud REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export"

PowerShell (Windows)

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

A continuación, ejecuta el siguiente comando para enviar tu solicitud REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/operations/17986570020347019923",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportProductsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_products"
        }
      ]
    }
  }
}

Exportar eventos de usuario a una tabla de BigQuery

Usa el método userEvents.export para exportar tus eventos de usuario del comercio a una tabla de BigQuery:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: ID del proyecto de la API Vertex AI Search for commerce en el que ha creado el conjunto de datos de BigQuery.
• DATASET_ID: el nombre del conjunto de datos que has creado en Crear un conjunto de datos en BigQuery. Por ejemplo, usa retail_data o retail_product_data.
• TABLE_ID_PREFIX: prefijo del ID de la tabla. Este prefijo no puede ser una cadena vacía. Se añade el sufijo retail_products para completar el nombre de la tabla. Por ejemplo, si el prefijo es test, la tabla se llama test_retail_products.

Cuerpo JSON de la solicitud:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Para enviar tu solicitud, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

A continuación, ejecuta el siguiente comando para enviar tu solicitud REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export"

PowerShell (Windows)

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

A continuación, ejecuta el siguiente comando para enviar tu solicitud REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/17203443067109586170",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportUserEventsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_user_events"
        }
      ]
    }
  }
}

Acerca de los datos exportados

A continuación, se indica lo que debe saber sobre los datos de comercio que exporta a las tablas de BigQuery:

• Los datos que se exportan a las tablas de BigQuery de tu proyecto son vistas autorizadas, no vistas materializadas.

• No puedes cambiar ni actualizar los datos de estas tablas.

• Los productos se actualizan cada hora.

• Los eventos de usuario se actualizan casi en tiempo real.

Acerca de los datos de eventos de usuario exportados

A continuación, se indica lo que debe saber sobre la información de producto que se incluye en los datos de eventos de usuario exportados.

Información sobre el precio de los productos

La forma en que el método userEvents.export devuelve la información sobre el precio de los productos depende de lo siguiente:

• Ha incluido información de precios en los datos de eventos de usuario en el momento de la ingestión. Cuando llamas al método userEvents.export, el precio que se devuelve con un evento de usuario es el precio del producto en el momento del evento.

• No ha incluido información sobre precios en sus datos de eventos de usuario, pero sí en sus datos de producto en el momento de la ingestión. Cuando llamas al método userEvents.export, el precio devuelto con un evento de usuario no es necesariamente el precio del producto en el momento del evento. Es el precio que figura en sus datos de producto en el momento de la ingestión.

• No ha incluido información sobre precios en los datos de eventos de usuario y no hay información sobre precios disponible en sus datos de producto. Cuando llamas al método userEvents.export, no se devuelve ningún precio con los eventos de usuario.

Otra información del producto

Toda la información de los productos (excepto el precio) se combina con la información de los eventos de usuario en el momento en que llama al método userEvents.export. Los valores de los productos pueden cambiar desde el momento en que se produce el evento del usuario hasta el momento en que llama a userEvents.export. Por este motivo, los valores de los productos sin precio que se devuelven en la tabla de eventos de usuario pueden ser diferentes de los valores de los productos en el momento del evento de usuario.

Opcional: Confirma que las nuevas tablas están en BigQuery

Una vez que haya exportado sus datos de producto y de eventos de usuario a BigQuery, compruebe que las nuevas tablas estén presentes.

1. En BigQuery, ve al conjunto de datos o a los conjuntos de datos que has creado en Crear un conjunto de datos en BigQuery.

2. Abre los conjuntos de datos y comprueba que aparecen las dos tablas que has exportado. Por ejemplo, busca tablas cuyos nombres terminen en retail_products y retail_user_events.

Para obtener más información sobre cómo trabajar con tablas de BigQuery, consulta el artículo sobre cómo consultar y ver datos.

Consulta la página Gobierno de datos para obtener más información sobre cómo gestiona Vertex AI Search para el sector del comercio los datos de los clientes.