Importa información del catálogo

En esta página, se describe cómo importar la información de tu catálogo y mantenerla actualizada.

Los procedimientos de importación de esta página se aplican tanto a las recomendaciones como a la búsqueda. Después de importar los datos, ambos servicios podrán usarlos, por lo que no es necesario importarlos dos veces si usas ambos servicios.

Video instructivo

Mira este video para aprender a importar un catálogo con la API de Retail.

Importa datos de un catálogo desde BigQuery

En este instructivo, se muestra cómo usar una tabla de BigQuery para importar grandes cantidades de datos de catálogo sin límites.

Para seguir la guía paso a paso sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

GUIARME

Importa datos de catálogo desde Cloud Storage

En este instructivo, se muestra cómo importar una gran cantidad de elementos a un catálogo.

Para seguir la guía paso a paso sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

GUIARME

Importa datos de catálogos intercalados

En este instructivo, se muestra cómo importar productos a un catálogo intercalado.

Para seguir la guía paso a paso sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

GUIARME

Antes de comenzar

Antes de importar la información de tu catálogo, debes completar las instrucciones que se indican en Antes de comenzar, en particular, cómo configurar tu proyecto, creación de una cuenta de servicio y agregado de la cuenta de servicio a tu entorno local.

Debes tener la función IAM del Administrador de venta minorista para realizar la importación.

Prácticas recomendadas para la importación de catálogos

Se necesitan datos de alta calidad para generar resultados de alta calidad. Si a tus datos les faltan campos o tienen valores de marcador de posición en lugar de valores reales, la calidad de tus predicciones y resultados de la búsqueda se ven afectados.

Cuando importes datos de catálogos, asegúrate de implementar las siguientes prácticas recomendadas:

• Asegúrate de distinguir con cuidado los productos principales de las variantes. Antes de subir cualquier dato, consulta Niveles de producto.

  • Cambiar la configuración a nivel del producto después de invertir un esfuerzo significativo en importar datos Los artículos principales (no las variantes) se muestran como resultados de la búsqueda o recomendaciones.

  • Ejemplo: Si el grupo de SKUs principal es Camisa con cuello en V,el modelo de recomendación devuelve una camisa con cuello en V y, tal vez, camisas con cuello redondo y escotado. Sin embargo, si no se usan variantes y cada SKU es principal, cada combinación de color o tamaño de la camisa con cuello en V se muestra como un artículo distinto en el panel de recomendaciones: Camisa marrón con cuello en V, talle XL, camisa marrón con cuello en V, talle L hasta camisa blanca con cuello en V, talle M, camisa blanca con cuello en V, talle S.

  • Las colecciones se pueden reconocer juntas siempre que se incluyan los IDs de variante junto con los IDs de productos principales en collectionMemberIds[]. Esto hace que se capture una colección de productos, de la cual un usuario puede haber comprado uno o más productos del conjunto, en el evento del usuario, lo que acredita todo el conjunto a la compra. Esto facilita la publicación de otros productos de una colección determinada para el mismo usuario en una consulta relacionada futura.

  • Ejemplo: Un usuario compró una funda de edredón, por lo que se muestran productos coincidentes en una colección de sábanas, como fundas de almohada.

• Respeta los límites de importación de artículos del producto.

  • Para realizar una importación masiva desde Cloud Storage, el tamaño de cada archivo debe ser de 2 GB o menos. Puedes incluir hasta 100 archivos a la vez en una sola solicitud de importación masiva.

  • Para la importación intercalada, importa no más de 5,000 artículos a la vez.

• Asegúrate de que la información del catálogo requerida esté incluida y sea correcta. No uses valores de marcador de posición.

• Incluye la mayor cantidad posible de información opcional del catálogo.

• Asegúrate de que todos tus eventos usen una sola moneda, en especial si planeas usar la consola deGoogle Cloud para obtener métricas de ingresos. La API de Vertex AI Search for Commerce no admite el uso de varias monedas por catálogo.

• Mantén tu catálogo actualizado, idealmente todos los días. La programación de importaciones periódicas de catálogo evita que la calidad del modelo disminuya con el tiempo. Puedes programar importaciones automáticas y recurrentes cuando importas tu catálogo con la consola de Search for Commerce. También puedes usar Google Cloud Scheduler para automatizar las importaciones.

• No registres eventos de usuario para los elementos de producto que aún no se importaron.

• Después de importar la información del catálogo, revisa la información sobre el registro y los informes de errores para tu proyecto. Si encuentras más de unos pocos errores, revísalos y corrige los problemas de procesos que los generaron.

Información acerca de la importación de datos del catálogo

Puedes importar tus datos de productos desde BigQuery o especificar los datos intercalados en la solicitud. Cada uno de estos procedimientos son importaciones únicas, con la excepción de vincular Merchant Center. Programa importaciones de catálogos normales (lo ideal sería a diario) para verificar que tu catálogo esté actualizado.

Consulta Cómo mantener tu catálogo actualizado.

También puedes importar artículos individuales. Para obtener más información, consulta Cómo subir un producto.

Consideraciones sobre la importación de catálogos

En esta sección, se describen los métodos que se pueden usar para importar por lotes tus datos de catálogos, cuándo puedes usar cada método y algunas de sus limitaciones.

Estructura de datos del producto para la transferencia del catálogo

En esta sección, se describe cómo preparar tus datos de productos para la transferencia del catálogo.

Productos principales

Los productos principales sirven como contenedores para agrupar productos variantes y como entradas en la cuadrícula de búsqueda. Solo los atributos comunes compartidos entre las variantes deben especificarse para los productos principales. Estos incluyen los siguientes:

• ID del producto principal
• ID del producto (idéntico al ID del producto principal)
• Título
• Descripción

Variante de productos

Los productos variantes heredan atributos comunes del producto principal, pero también pueden especificar valores únicos.

Los atributos obligatorios incluyen lo siguiente:

• Todos los atributos especificados para los productos principales (título, descripción) El precio, el título y la descripción pueden ser diferentes del producto principal.
• Atributos de variantes específicos (color, tamaño y otras variaciones relevantes del producto)

Recuperación de atributos

El proceso de recuperación considera todos los atributos que se pueden buscar tanto para los productos principales como para los productos con variantes.

Puntuación de relevancia

La puntuación de relevancia se basa únicamente en los campos de título y descripción. Para garantizar una diferenciación adecuada, modifica ligeramente los títulos de las variantes con respecto a los títulos de los productos principales (por ejemplo, Nombre del producto + Color).

Coincidencia de variantes en los resultados de la búsqueda

La correlación de variantes (por ejemplo, vestido azul) filtra los resultados según atributos de variantes predefinidos, como el color y el tamaño. Los resultados de la búsqueda muestran hasta cinco variantes coincidentes para cada producto principal.

Borra definitivamente ramas del catálogo

Si importas datos de catálogos nuevos a una rama existente, es importante que la rama del catálogo esté vacía para garantizar la integridad de los datos importados a la rama. Cuando la rama está vacía, puedes importar datos de catálogos nuevos y vincular la rama a una cuenta de comercio.

Si publicas predicciones en vivo o tráfico de búsqueda, y planeas purgar tu rama predeterminada, considera especificar primero otra rama como predeterminada antes de purgarla. Dado que la rama predeterminada publicará resultados vacíos después de que se borre definitivamente, borrar definitivamente una rama predeterminada activa puede causar una interrupción.

Para borrar datos de una rama del catálogo, completa los siguientes pasos:

1. Ve a la página Datos> en la consola de Search for commerce.
   
   Ir a la página Datos

2. Selecciona una rama de catálogo en el campo Nombre de la rama.

3. En el menú de tres puntos que se encuentra junto al campo Nombre de la rama, elige Purgar rama.

   Se mostrará un mensaje de advertencia que indica que está a punto de borrar todos los datos de la rama, así como los atributos creados para ella.

4. Ingresa la rama y haz clic en Confirmar para borrar definitivamente los datos del catálogo de la rama.

   Se inicia una operación de larga duración para purgar los datos de la rama del catálogo. Cuando se complete la operación de eliminación, el estado de la eliminación se mostrará en la lista Catálogo de productos de la ventana Estado de la actividad.

Sincroniza Merchant Center con Vertex AI Search for Commerce

Merchant Center es una herramienta que puedes usar a fin de que tus datos de tiendas y productos estén disponibles para los anuncios de Shopping y otros servicios de Google.

Para realizar una sincronización continua entre Merchant Center y Vertex AI Search para comercio, puedes vincular tu cuenta de Merchant Center a Vertex AI Search para comercio.

Cuando configures una sincronización de Merchant Center para Vertex AI Search for Commerce, debes tener asignado el rol de IAM de administrador en Merchant Center. Si bien un rol de acceso estándar te permitirá leer los feeds de Merchant Center, cuando intentes sincronizar Merchant Center con Vertex AI Search for Commerce, recibirás un mensaje de error. Por lo tanto, antes de que puedas sincronizar correctamente tu cuenta de Merchant Center con Vertex AI Search for Commerce, actualiza tu rol.

Vincula tu cuenta de Merchant Center

Mientras Vertex AI Search for Commerce está vinculado a la cuenta de Merchant Center, los cambios en tus datos de productos en la cuenta de Merchant Center se actualizan automáticamente en cuestión de minutos en Vertex AI Search for Commerce. Si deseas evitar que los cambios de Merchant Center se sincronicen con Vertex AI Search para comercio, puedes desvincular tu cuenta de Merchant Center.

La desvinculación de tu cuenta de Merchant Center no borra los productos en Vertex AI Search para comercio. Para borrar productos importados, consulta Borra información del producto.

Para sincronizar tu cuenta de Merchant Center, completa los siguientes pasos.

Sincroniza tu cuenta de Merchant Center

Para ver tu cuenta de Merchant Center vinculada, ve a la página Datos de la consola de búsqueda para comercio electrónico y haz clic en el botón Merchant Center en la parte superior derecha de la página. Esta acción abrirá el panel Cuentas de Merchant Center vinculadas. También puedes agregar cuentas de Merchant Center adicionales desde este panel.

Consulta Visualiza la información agregada sobre tu catálogo para obtener instrucciones sobre cómo ver los productos que se importaron.

Enumera los vínculos de tu cuenta de Merchant Center

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Desvincula tu cuenta de Merchant Center

Si desvinculas tu cuenta de Merchant Center, esa cuenta dejará de sincronizar los datos del catálogo con Vertex AI Search para comercio. Este procedimiento no borra ningún producto en Vertex AI Search for Commerce que ya se haya subido.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Limitaciones sobre la vinculación a Merchant Center

• Una cuenta de Merchant Center se puede vincular a cualquier cantidad de ramas de catálogo, pero una sola rama de catálogo solo se puede vincular a una cuenta de Merchant Center.

• Una cuenta de Merchant Center no puede ser una cuenta de varios clientes (MCA). Sin embargo, puedes vincular subcuentas individuales.

• Es posible que la primera importación después de vincular la cuenta de Merchant Center tarde horas en completarse. El tiempo depende de la cantidad de ofertas en la cuenta de Merchant Center.

• Las modificaciones de productos que usen los métodos de la API se inhabilitan para las ramas vinculadas a una cuenta de Merchant Center. Los cambios en los datos del catálogo de productos en esas ramas se deben realizar con Merchant Center. Esos cambios se sincronizan de forma automática con Vertex AI Search for Commerce.

• El tipo de producto de colección no es compatible con las ramas que usan la vinculación de Merchant Center.

• Tu cuenta de Merchant Center solo se puede vincular con ramas de catálogo vacías para garantizar la precisión de los datos. Para borrar productos de una rama de catálogo, consulta Borra información del producto.

Importa datos de catálogos desde Merchant Center

Puedes importar datos de catálogos de Merchant Center de forma masiva como un procedimiento único desde BigQuery con el esquema de Merchant Center (solo recomendaciones).

Importación masiva desde Merchant Center

Puedes importar datos de catálogos de Merchant Center con la consola de Search for Commerce o el método products.import. La importación masiva es un procedimiento de una sola vez y solo es compatible con las recomendaciones.

Para importar tu catálogo desde Merchant Center, completa los siguientes pasos:

1. Con las instrucciones de las transferencias de Merchant Center, configura una transferencia desde Merchant Center a BigQuery.

   Usarás el esquema de la tabla de productos de Google Merchant Center. Configura la transferencia para que se repita a diario, pero configura la fecha de vencimiento de tu conjunto de datos a 2 días.

2. Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que la Búsqueda con Vertex AI para comercio pueda acceder al conjunto de datos de BigQuery. Obtén más información.

3. Importa tus datos de catálogos de BigQuery a Vertex AI Search para comercio.

   Consola de Cloud

   1. Ve a la página Datos> en la consola de Search for commerce.
      
      Ir a la página Datos

   2. Haz clic en Importar para abrir el panel Importar.

   3. Elige Catálogo de productos.

   4. Selecciona BigQuery como tu fuente de datos.

   5. Selecciona la rama a la que subirás tu catálogo.

   6. Selecciona Merchant Center como el esquema de datos.

   7. Ingresa la tabla de BigQuery donde se encuentran tus datos.

   8. Opcional: Ingresa la ubicación de un bucket de Cloud Storage en tu proyecto como una ubicación temporal para tus datos.

      Si no se especifica, se usa una ubicación predeterminada. Si se especifica, el bucket de Cloud Storage y BigQuery deben estar en la misma región.

   9. Elige si quieres programar una carga recurrente para los datos de tu catálogo.

   10. Si es la primera vez que importas tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente, selecciona los niveles de producto. Más información sobre los niveles de producto

       Cambiar la configuración a nivel del producto después de importar cualquier dato requiere un esfuerzo significativo.

   11. Haz clic en Importar.

   curl

   1. Si es la primera vez que subes tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente, configura los niveles de producto con el método Catalog.patch. Para esta operación se requiere la función de Administrador de venta minorista. Más información sobre los niveles de producto

      • ingestionProductType: Admite los valores primary (predeterminado) y variant.
      • merchantCenterProductIdField: Admite los valores offerId (predeterminado) y itemGroupId. Si no usas Merchant Center, establece el valor predeterminado offerId.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT_TYPE",
        "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Importa tu catálogo mediante el método Products.import.

      • DATASET_ID: el ID del conjunto de datos de BigQuery.
      • TABLE_ID: el ID de la tabla de BigQuery que contiene tus datos.
      • STAGING_DIRECTORY: Opcional Un directorio de Cloud Storage que se usa como ubicación provisional de tus datos antes de que se importen a BigQuery. Deja este campo vacío para crear automáticamente un directorio temporal (recomendado).
      • ERROR_DIRECTORY: Opcional Un directorio de Cloud Storage para obtener información sobre los errores de la importación. Deja este campo vacío para crear automáticamente un directorio temporal (recomendado).
      • dataSchema: Para la propiedad dataSchema, usa el valor product_merchant_center. Consulta el esquema de la tabla de productos de Merchant Center.

      Recomendamos que no especifiques directorios de etapa de pruebas o de error para que se pueda crear automáticamente un bucket de Cloud Storage con nuevos directorios de etapa de pruebas y de error. Estos directorios se crean en la misma región que el conjunto de datos de BigQuery y son únicos para cada importación (lo que evita que varios trabajos de importación habiliten la etapa de pruebas de datos en el mismo directorio y, potencialmente, vuelvan a importar los mismos datos). Después de tres días, el bucket y los directorios se borran de forma automática para reducir los costos de almacenamiento.

      Un nombre de bucket creado automáticamente incluye el ID del proyecto, la región del bucket y el nombre del esquema de los datos, separados por guiones bajos (por ejemplo, 4321_us_catalog_retail). Los directorios creados de forma automática se denominan staging o errors, seguidos por un número (por ejemplo, staging2345 o errors5678).

      Si especificas directorios, el bucket de Cloud Storage debe estar en la misma región que el conjunto de datos de BigQuery o la importación fallará. Proporciona los directorios de etapa de pruebas y de error en el formato gs://<bucket>/<folder>/; deberían ser diferentes.

     curl -X POST \
          -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
          -H "Content-Type: application/json; charset=utf-8" \
          --data '{
            "inputConfig":{
               "bigQuerySource": {
                 "datasetId":"DATASET_ID",
                 "tableId":"TABLE_ID",
                 "dataSchema":"product_merchant_center"
               }
             }
         }' \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Importa datos de un catálogo desde BigQuery

Para importar datos del catálogo en el formato correcto desde BigQuery, usa el esquema de Vertex AI Search para comercio para crear una tabla de BigQuery con el formato correcto y cargar la tabla vacía con los datos de tu catálogo. Luego, sube tus datos a Vertex AI Search for Commerce.

Si necesitas más ayuda con las tablas de BigQuery, consulta Introducción a las tablas. Para obtener ayuda con las consultas de BigQuery, consulta Descripción general de las consultas de datos de BigQuery.

Para seguir la guía paso a paso sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

GUIARME

Para importar tu catálogo, haz lo siguiente:

1. Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que la Búsqueda con Vertex AI para comercio pueda acceder al conjunto de datos de BigQuery. Obtén más información.

2. Importa tus datos de catálogo a Vertex AI Search para el comercio.

   Consola de Cloud

   1. Ve a la página Datos> en la consola de Search for commerce.
      
      Ir a la página Datos
   2. Haz clic en Importar para abrir el panel Importar datos.
   3. Elige Catálogo de productos.
   4. Selecciona BigQuery como tu fuente de datos.
   5. Selecciona la rama a la que subirás tu catálogo.
   6. Elige Esquema de catálogos de productos de venta minorista. Este es el esquema de producto para Vertex AI Search for Commerce.
   7. Ingresa la tabla de BigQuery donde se encuentran tus datos.
   8. Opcional: En Mostrar opciones avanzadas, ingresa la ubicación de un bucket de Cloud Storage en tu proyecto como una ubicación temporal para tus datos.
      
      Si no se especifica, se usa una ubicación predeterminada. Si se especifica, el bucket de Cloud Storage y BigQuery deben estar en la misma región.
   9. Si no tienes habilitada la búsqueda y usas el esquema de Merchant Center, selecciona el nivel del producto.
      
      Debes seleccionar el nivel del producto si es la primera vez que importas tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente. Obtén más información sobre los niveles de producto. Cambiar los niveles de producto después de importar cualquier dato requiere un esfuerzo significativo.
      
      Importante: No puedes activar la búsqueda para proyectos con un catálogo de productos que se haya transferido como variantes.
   10. Haz clic en Importar.

   curl

   1. Si es la primera vez que subes tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente, configura los niveles de producto con el método Catalog.patch. Para esta operación se requiere la función de Administrador de venta minorista.

      • ingestionProductType: Admite los valores primary (predeterminado) y variant.
      • merchantCenterProductIdField: Admite los valores offerId y itemGroupId. Si no usas Merchant Center, no es necesario que configures este campo.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Crea un archivo de datos para los parámetros de entrada de la importación.

      Usa el objeto BigQuerySource para apuntar a tu conjunto de datos de BigQuery.

      • DATASET_ID: el ID del conjunto de datos de BigQuery.
      • TABLE_ID: el ID de la tabla de BigQuery que contiene tus datos.
      • PROJECT_ID: Es el ID del proyecto en el que se encuentra la fuente de BigQuery. Si no se especifica, el ID del proyecto se hereda de la solicitud principal.
      • STAGING_DIRECTORY: Opcional Un directorio de Cloud Storage que se usa como ubicación provisional de tus datos antes de que se importen a BigQuery. Deja este campo vacío para crear automáticamente un directorio temporal (recomendado).
      • ERROR_DIRECTORY: Opcional Un directorio de Cloud Storage para obtener información sobre los errores de la importación. Deja este campo vacío para crear automáticamente un directorio temporal (recomendado).
      • dataSchema: Para la propiedad dataSchema, usa el valor product (predeterminado). Usarás el esquema de Vertex AI Search for Commerce.

      Recomendamos que no especifiques directorios de etapa de pruebas o de error para que se pueda crear automáticamente un bucket de Cloud Storage con nuevos directorios de etapa de pruebas y de error. Estos directorios se crean en la misma región que el conjunto de datos de BigQuery y son únicos para cada importación (lo que evita que varios trabajos de importación habiliten la etapa de pruebas de datos en el mismo directorio y, potencialmente, vuelvan a importar los mismos datos). Después de tres días, el bucket y los directorios se borran de forma automática para reducir los costos de almacenamiento.

      Un nombre de bucket creado automáticamente incluye el ID del proyecto, la región del bucket y el nombre del esquema de los datos, separados por guiones bajos (por ejemplo, 4321_us_catalog_retail). Los directorios creados de forma automática se denominan staging o errors, seguidos por un número (por ejemplo, staging2345 o errors5678).

      Si especificas directorios, el bucket de Cloud Storage debe estar en la misma región que el conjunto de datos de BigQuery o la importación fallará. Proporciona los directorios de etapa de pruebas y de error en el formato gs://<bucket>/<folder>/; deberían ser diferentes.

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }

   3. Importa la información de tu catálogo con una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí se muestra como input.json).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      Puedes verificar el estado de manera programática mediante la API. Deberías recibir un objeto de respuesta similar al siguiente:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      El campo de nombre es el ID del objeto de operación. Para solicitar el estado de este objeto, reemplaza el campo de nombre por el valor que muestra el método import hasta que el campo done se muestre como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      Cuando se completa la operación, el objeto que se muestra tiene un valor done de true y, además, incluye un objeto de estado similar al siguiente ejemplo:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Puedes inspeccionar los archivos en el directorio de errores de Cloud Storage para ver si se produjeron errores durante la importación.

Configura el acceso a tu conjunto de datos de BigQuery

Para configurar el acceso cuando tu conjunto de datos de BigQuery está en un proyecto diferente al de tu servicio de Vertex AI Search for Commerce, completa los siguientes pasos.

1. Abre la página IAM en la consola de Google Cloud .

   Abrir la página IAM

2. Selecciona tu proyecto de Vertex AI Search for Commerce.

3. Busca la cuenta de servicio con el nombre Cuenta de servicio de venta minorista.

   Si no iniciaste una operación de importación, es posible que esta cuenta de servicio no aparezca en la lista. Si no ves esta cuenta de servicio, regresa a la tarea de importación y comienza la importación. Cuando falle debido a errores de permisos, regresa aquí y completa esta tarea.

4. Copia el identificador para la cuenta de servicio, que se parece a una dirección de correo electrónico (por ejemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com).

5. Cambia a tu proyecto de BigQuery (en la misma página IAM y administración) y haz clic en person_add Otorgar acceso.

6. En Nuevos principales, ingresa el identificador de la cuenta de servicio de Vertex AI Search para comercio y selecciona el rol BigQuery > Usuario de BigQuery.

7. Haz clic en Agregar otra función y seleccione BigQuery > Editor de datos de BigQuery.

   Si no deseas proporcionar el rol de editor de datos a todo el proyecto, puedes agregar este rol directamente al conjunto de datos. Obtén más información.

8. Haz clic en Guardar.

Importa datos de catálogo desde Cloud Storage

Para importar datos del catálogo en formato JSON, crea uno o más archivos JSON que contengan los datos del catálogo que deseas importar y súbelos a Cloud Storage. Desde allí, puedes importarla a Vertex AI Search for Commerce.

Para ver un ejemplo del formato de elemento de producto JSON, consulta Formato de datos JSON de elemento de producto.

Para obtener ayuda con la carga de archivos en Cloud Storage, consulta Carga objetos.

1. Asegúrate de que la cuenta de servicio de Vertex AI Search for Commerce tenga permiso para leer y escribir en el bucket.

   La cuenta de servicio de Vertex AI Search para comercio electrónico aparece en la página de IAM en la consola de Google Cloud con el nombre Cuenta de servicio de venta minorista. Usa el identificador de la cuenta de servicio, que se parece a una dirección de correo electrónico (por ejemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com), cuando agregues la cuenta a los permisos de tu bucket.

2. Importa los datos de tu catálogo.

   Consola de Cloud

   1. Ve a la página Datos> en la consola de Search for commerce.
      
      Ir a la página Datos
   2. Haz clic en Importar para abrir el panel Importar datos.
   3. Elige Catálogo de productos como tu fuente de datos.
   4. Selecciona la rama a la que subirás tu catálogo.
   5. Elige Esquema de catálogos de productos de venta minorista como el esquema.
   6. Ingresa la ubicación de Cloud Storage de tus datos.
   7. Si no tienes habilitada la búsqueda, selecciona los niveles de productos.
      
      Debes seleccionar los niveles de productos si es la primera vez que importas tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente. Obtén más información sobre los niveles de producto. Cambiar los niveles de producto después de importar cualquier dato requiere un esfuerzo significativo.
      
      Importante: No puedes activar la búsqueda para proyectos con un catálogo de productos que se haya transferido como variantes.
   8. Haz clic en Importar.

   curl

   1. Si es la primera vez que subes tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente, configura los niveles de tus productos con el método Catalog.patch. Más información sobre los niveles de producto

      • ingestionProductType: Admite los valores primary (predeterminado) y variant.
      • merchantCenterProductIdField: Admite los valores offerId y itemGroupId. Si no usas Merchant Center, no es necesario que configures este campo.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Crea un archivo de datos para los parámetros de entrada de la importación. Usa el objeto GcsSource para que apunte a tu bucket de Cloud Storage.

      Puedes proporcionar varios archivos o solo uno. En este ejemplo, se usan dos archivos.

      • INPUT_FILE: Son los archivos en Cloud Storage que contienen tus datos de catálogo.
      • ERROR_DIRECTORY: Un directorio de Cloud Storage para obtener información sobre los errores de la importación

      Los campos de archivo de entrada deben tener el formato gs://<bucket>/<path-to-file>/. El directorio de errores debe tener el formato gs://<bucket>/<folder>/. Si el directorio de errores no existe, se creará. El bucket ya debe existir.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }

   3. Importa la información de tu catálogo con una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí se muestra como input.json).

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      La forma más fácil de verificar el estado de tu operación de importación es usar la Google Cloud consola. Para obtener más información, consulta Cómo ver el estado de una operación de integración específica.

      También puedes verificar el estado de manera programática mediante la API. Deberías recibir un objeto de respuesta similar al siguiente:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      El campo de nombre es el ID del objeto de operación. Solicita el estado de este objeto y reemplaza el campo de nombre por el valor que muestra el método de importación hasta que el campo done se muestre como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      Cuando se completa la operación, el objeto tiene un done de true y, además, incluye un objeto de estado similar al siguiente ejemplo:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Puedes inspeccionar los archivos en el directorio de errores de Cloud Storage para ver qué tipo de errores se produjeron durante la importación.

Importa datos de catálogos intercalados

{
"inputConfig": {
  "productInlineSource": {
      "products": [
        { PRODUCT_1 }
        { PRODUCT_2 }
      ]
    }
  }
}

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Formato de datos JSON de elementos de productos

Las entradas Product en tu archivo JSON deberían verse como los siguientes ejemplos.

Proporciona un producto completo en una sola línea. Cada producto debe estar en su propia línea.

Campos obligatorios mínimos:

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

Objeto completo:

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

Datos históricos de catálogos

Vertex AI Search para el comercio admite la importación y administración de datos históricos de catálogos. Los datos históricos de catálogos pueden ser útiles cuando usas eventos históricos de los usuarios para el entrenamiento de modelos. La información del producto anterior se puede usar para enriquecer los datos históricos de los eventos de usuarios y mejorar la exactitud del modelo.

Los productos históricos se almacenan como productos vencidos. No se muestran en las respuestas de la búsqueda, pero son visibles para las llamadas a la API Update, List y Delete.

Importación de datos históricos de catálogos

Cuando el campo expireTime de un producto se establece en una marca de tiempo anterior, este producto se considera como un producto histórico. Configura la disponibilidad del producto como OUT_OF_STOCK para evitar afectar las recomendaciones.

Recomendamos usar los siguientes métodos para importar datos históricos de catálogos:

• Llama al método Product.Create.
• Importación intercalada de productos vencidos
• Importar productos vencidos desde BigQuery

Llama al método Product.Create

Usa el método Product.Create para crear una entrada Product con el campo expireTime configurado en una marca de tiempo anterior.

Importación intercalada de productos vencidos

Los pasos son idénticos a los de la importación intercalada, excepto que los productos deben tener los campos expireTime configurados en una marca de tiempo anterior.

Proporciona un producto completo en una sola línea. Cada producto debe estar en su propia línea.

Un ejemplo de ./data.json que se usa en la solicitud de importación intercalada:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Importa productos vencidos de BigQuery o Cloud Storage

Usa los mismos procedimientos que se documentaron para importar datos de catálogos desde BigQuery o importar datos de catálogos desde Cloud Storage. Sin embargo, asegúrate de configurar el campo expireTime como una marca de tiempo anterior.

Mantén tu catálogo actualizado

Para obtener los mejores resultados, tu catálogo debe contener información actualizada. Te recomendamos importar el catálogo a diario para asegurarte de que esté actualizado. Puedes usar Google Cloud Scheduler para programar importaciones o elegir una opción de programación automática cuando importas datos con la consola deGoogle Cloud .

Solo puedes actualizar los elementos de productos nuevos o modificados o puedes importar todo el catálogo. Si importas productos que ya están en tu catálogo, no se vuelven a agregar. Se actualiza cualquier elemento que haya cambiado.

Para actualizar un solo elemento, consulta Cómo actualizar la información del producto.

Actualización por lotes

Puedes usar el método de importación para actualizar por lotes tu catálogo. El procedimiento es el mismo que para la importación inicial; sigue los pasos en Importa datos del catálogo.

Supervisa el estado de la importación

Para supervisar la incorporación y el estado del catálogo, haz lo siguiente:

1. Consulta la información agregada sobre tu catálogo y obtén una vista previa de los productos subidos en la pestaña Catálogo de la página Datos de la Búsqueda para comercio.

   Ir a la página Datos

2. Evalúa si necesitas actualizar los datos del catálogo para mejorar la calidad de los resultados de la búsqueda y desbloquear los niveles de rendimiento de la búsqueda en la página Calidad de los datos.

   Para obtener más información sobre cómo verificar la calidad de los datos de búsqueda y ver los niveles de rendimiento de la búsqueda, consulta Cómo desbloquear los niveles de rendimiento de la búsqueda. Para obtener un resumen de las métricas del catálogo disponibles en esta página, consulta Métricas de calidad del catálogo.

   Ir a la página Calidad de los datos

3. Para crear alertas que te informen si algo sale mal con tus cargas de datos, sigue los procedimientos que se indican en Configura alertas de Cloud Monitoring.

   Mantener actualizado tu catálogo es importante para obtener resultados de alta calidad. Usa alertas para supervisar las tasas de error de importación y tomar medidas si es necesario.

¿Qué sigue?

• Comienza a grabar eventos de usuario.
• Consulta información agregada sobre tu catálogo.
• Configura alertas de carga de datos.