Retail cambiará de nombre a Vertex AI Search for Retail. Estamos en proceso de actualizar el contenido para reflejar el nuevo desarrollo de la marca.

Se usó la API de Cloud Translation para traducir esta página.

Importa información del catálogo

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

Los procedimientos de importación de esta página se aplican a las recomendaciones y a la búsqueda. Después de importar datos, ambos servicios pueden usarlos, por lo que no necesitas importar los mismos datos dos veces si usas ambos servicios.

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álogos 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 del catálogo de forma intercalada

En este instructivo, se muestra cómo importar productos en 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, se verá afectada la calidad de tus predicciones y de los resultados de la búsqueda.

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

Asegúrate de pensar cuidadosamente a la hora de determinar qué productos o grupos de productos son principales y cuáles son variantes. Antes de subir datos, consulta Niveles de producto.

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

Los elementos principales se muestran como recomendaciones o resultados de la búsqueda. Los elementos de variantes no lo son.

Por ejemplo, si el grupo de SKU principal es "Camisa con cuello en V", el modelo de recomendación muestra un artículo de camisa con cuello V y, tal vez, una camisa con cuello redondo y una camisa con cuello redondo. Sin embargo, si no se usan variantes y cada SKU es el principal, cada combinación de color y talla de camisa con cuello V se muestra como un artículo distinto en el panel de recomendaciones: “Camisa con cuello V marrón, talla XL”, “Camisa con cuello V marrón, talla L”, hasta “Camisa blanca con cuello V, talla M”, “Camisa blanca con cuello V, talla S”.
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 toda 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 los eventos usen una sola moneda, en especial si planeas usar la consola de Google Cloud para obtener métricas de ingresos. La API de Vertex AI Search for Retail no admite el uso de varias monedas por catálogo.
Mantén actualizado tu catálogo.

Lo ideal es actualizarlo a diario. 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 Retail. 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.

Se esperan algunos errores, pero si tienes una gran cantidad de errores, debes revisarlos y solucionar los problemas de procesos que generaron los errores.

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

Puedes importar tus datos de productos desde Merchant Center, Cloud Storage, BigQuery o especificar los datos intercalados en la solicitud. Cada uno de estos procedimientos son importaciones únicas, a excepción de la vinculación de Merchant Center. Programa importaciones periódicas del catálogo (idealmente, a diario) para asegurarte de que tu catálogo esté actualizado. Consulta Mantén 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.

Sincronización de Merchant Center	Descripción	Importa datos de catálogos a través de Merchant Center vinculando la cuenta con Vertex AI Search for Retail. Después de la vinculación, las actualizaciones de los datos del catálogo en Merchant Center se sincronizan en tiempo real con Vertex AI Search for Retail.
	Cuándo usarla	Si tienes una integración existente con Merchant Center
	Limitaciones	Compatibilidad con el esquema limitado Por ejemplo, Merchant Center no admite las colecciones de productos. Merchant Center se convierte en la fuente de información para los datos hasta que se desvinculan, por lo que se deben agregar todos los atributos personalizados necesarios a los datos de Merchant Center. Control limitado. No puedes especificar ciertos campos o conjuntos de elementos para importar desde Merchant Center. Se importan todos los artículos y campos existentes en Merchant Center.
BigQuery	Descripción	Importa datos de una tabla de BigQuery cargada con anterioridad que use el esquema de Vertex AI Search for Retail o el esquema de Merchant Center. Se puede realizar con la consola de Google Cloud o curl.
	Cuándo usarla	Si tienes catálogos de productos con muchos atributos. La importación de BigQuery usa el esquema de Vertex AI Search for Retail, que tiene más atributos de producto que otras opciones de importación, incluidos los atributos personalizados clave-valor. Si tienes grandes volúmenes de datos La importación de BigQuery no tiene un límite de datos. Si ya usas BigQuery.
	Limitaciones	Requiere el paso adicional de creación de una tabla de BigQuery que se asigne al esquema de Vertex AI Search for Retail.
Cloud Storage	Descripción	Importar datos en formato JSON desde archivos cargados en un bucket de Cloud Storage Cada archivo debe ser de 2 GB o menos, y se pueden importar hasta 100 archivos a la vez. La importación se puede realizar con la consola de Google Cloud o curl. Usa el formato de datos JSON `Product`, que permite atributos personalizados.
	Cuándo usarla	Si necesitas cargar una gran cantidad de datos en un solo paso.
	Limitaciones	No es ideal para los catálogos con actualizaciones frecuentes de inventario y precios, ya que los cambios no se reflejan de inmediato.
Importación intercalada	Descripción	Importación mediante una llamada al método `Product.import`. Usa el objeto `ProductInlineSource`, que tiene menos atributos del catálogo de productos que el esquema de Vertex AI Search for Retail, pero admite atributos personalizados.
	Cuándo usarla	Si tienes datos de catálogo no relacionales o planos o una frecuencia alta de actualizaciones de cantidad o precio.
	Limitaciones	No se pueden importar más de 100 elementos de catálogo a la vez. Sin embargo, se pueden realizar muchos pasos de carga; no hay límite de elementos.

Borrar definitivamente las ramas del catálogo

Si importas datos de catálogo nuevos a una rama existente, es importante que esta esté vacía. Esto garantiza la integridad de los datos importados a la rama. Cuando la rama está vacía, puedes importar datos de catálogo nuevos y, luego, vincular la rama a una cuenta de comerciante.

Si estás entregando tráfico de predicción o de búsqueda en vivo y planeas borrar definitivamente tu rama predeterminada, primero debes especificar otra rama como predeterminada antes de hacerlo. Debido a que la rama predeterminada entregará resultados vacíos después de su eliminación definitiva, esta acción puede provocar una interrupción.

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

Ve a la página Datos> en la consola de Search for Retail.

Ir a la página Datos
Selecciona una rama de catálogo en el campo Nombre de la rama (Branch name).
En el menú de tres puntos junto al campo Nombre de rama, elige Purge branch.

Aparecerá un mensaje que te advierte que estás a punto de borrar todos los datos de la rama, así como cualquier atributo creado para ella.

Nota: No puedes deshacer una eliminación definitiva de los datos de una rama de catálogo.
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 borrar definitivamente los datos de la rama de catálogo. Cuando se completa la operación de borrado definitivo, su estado se muestra en la lista Catálogo de productos, en la ventana Estado de la actividad.

Nota: La lista de los datos del catálogo de la rama no se actualiza automáticamente después de que se completa la eliminación definitiva. Debes actualizar la página para ver una lista actualizada de la rama.

Sincroniza Merchant Center con Vertex AI Search for Retail

Para una sincronización continua entre Merchant Center y Vertex AI Search for Retail, puedes vincular tu cuenta de Merchant Center a Vertex AI Search for Retail. Después de la vinculación, la información del catálogo en tu cuenta de Merchant Center se importa de inmediato a Vertex AI Search for Retail.

Cuando configures una sincronización de Merchant Center para Vertex AI Search for Retail, debes tener asignado el rol de administrador en Merchant Center. Aunque un rol de acceso estándar te permitirá leer los feeds de Merchant Center en la IU, recibirás un mensaje de error cuando intentes sincronizar Merchant Center con Vertex AI Search for Retail. Por lo tanto, antes de que puedas sincronizar correctamente tu cuenta de Merchant Center con Vertex AI Search for Retail, deberás actualizar tu rol según corresponda.

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

Si desvinculas tu cuenta de Merchant Center, no se borrará ningún producto en Vertex AI Search for Retail. Para borrar productos importados, consulta Borra la información de los productos.

Sincronice su cuenta de Merchant Center

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

Consola

Ve a la página Datos> en la consola de Search for Retail.

Ir a la página Datos
Haz clic en Importar para abrir el panel Importar datos.
Elige Catálogo de productos.
Selecciona Sincronización de Merchant Center como tu fuente de datos.
Selecciona tu cuenta de Merchant Center. Verifica Acceso de usuario si no ves tu cuenta.
Opcional: Selecciona Filtro de feeds de Merchant Center para importar solo las ofertas de los feeds seleccionados.

Si no se especifica, se importarán las ofertas de todos los feeds (incluidos los futuros).
Opcional: Para importar solo las ofertas orientadas a determinados países o idiomas, expanda la opción Mostrar opciones avanzadas y seleccione los idiomas y países de venta de Merchant Center que desea utilizar como filtro.
Selecciona la rama a la que subirás tu catálogo.
Haga clic en Import.

curl

Verifica que la cuenta de servicio en tu entorno local tenga acceso a la cuenta de Merchant Center y a Vertex AI Search for Retail. Si deseas verificar qué cuentas tienen acceso a tu cuenta de Merchant Center, consulta Acceso de los usuarios a Merchant Center.
Usa el método MerchantCenterAccountLink.create para establecer el vínculo.
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"primaryFeedId": PRIMARY_FEED_ID_1}
    {"primaryFeedId": PRIMARY_FEED_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
```
- MERCHANT_CENTER_ID: Es el ID de la cuenta de Merchant Center.
- BRANCH_ID: Es el ID de la rama con la que se establecerá el vínculo. Acepta los valores "0", "1" o "2".
- LANGUAGE_CODE: Es el código de idioma de dos letras de los productos que deseas importar (OPCIONAL). Como se ve en Merchant Center, en la columna Language del producto. Si no la estableces, se importarán todos los idiomas.
- FEED_LABEL: Es la etiqueta de feed de los productos que deseas importar (opcional). Puedes ver la etiqueta de feed en Merchant Center, en la columna Etiqueta de feed del producto. Si no la estableces, se importarán todas las etiquetas de feed.
- FEED_FILTERS: Es una lista de los feeds principales desde los que se importarán los productos (OPCIONAL). Si no seleccionas feeds, se compartirán todos los feeds de la cuenta de Merchant Center. Puedes encontrar los IDs en el recurso de feeds de datos de Content API o si visitas Merchant Center, seleccionas un feed y obtienes el ID del feed a partir del parámetro dataSourceId en la URL del sitio. Por ejemplo, mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID.

Para ver tu cuenta de Merchant Center vinculada, ve a la página Datos de Search for Retail Console y haz clic en el botón Merchant Center que se encuentra en la parte superior derecha de la página. Se 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 de tu catálogo si necesitas instrucciones para ver los productos que se importaron.

Genera una lista de los vínculos de tu cuenta de Merchant Center

Genera una lista de los vínculos de tu cuenta de Merchant Center.

Consola

Ve a la página Datos> en la consola de Search for Retail.

Ir a la página Datos
Haz clic en el botón Merchant Center en la parte superior derecha de la página para abrir una lista de tus cuentas vinculadas de Merchant Center.

curl

Usa el método MerchantCenterAccountLink.list para enumerar el recurso de vínculos.

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, esta dejará de sincronizar los datos del catálogo con Vertex AI Search for Retail. Con este procedimiento, no se borra ningún producto que ya se haya subido en Vertex AI Search for Retail.

Consola

Ve a la página Datos> en la consola de Search for Retail.

Ir a la página Datos
Haz clic en el botón Merchant Center en la parte superior derecha de la página para abrir una lista de tus cuentas vinculadas de Merchant Center.
Haz clic en Desvincular junto a la cuenta de Merchant Center que desvinculas y confirma tu elección en el cuadro de diálogo que aparece.

curl

Usa el método MerchantCenterAccountLink.delete para quitar el recurso MerchantCenterAccountLink.

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 cuentas secundarias 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.
Cualquier modificación de producto con métodos de API se inhabilita 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 sincronizarán automáticamente con Vertex AI Search for Retail.
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 del catálogo, consulta Borra la información del producto.

Importa datos del catálogo desde Merchant Center

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.

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

Importar de forma masiva desde Merchant Center

Puedes importar datos del catálogo desde Merchant Center con la consola de Search for Retail o con el método products.import. La importación masiva es un procedimiento único y solo se admite para las recomendaciones.

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

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.
Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que Vertex AI Search for Retail pueda acceder a él. Obtener más información.
Importa los datos de tu catálogo de BigQuery a Vertex AI Search for Retail.
Consola
1. Ve a la página Datos> en la consola de Search for Retail.
  
  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. Ingresa la ubicación de un bucket de Cloud Storage en tu proyecto como una ubicación temporal para tus datos (opcional).
  
  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 lo importas de nuevo después de borrarlo definitivamente, selecciona los niveles de producto. Más información sobre los niveles de producto
  
  Cambiar la configuración de nivel del producto después de importar datos requiere un esfuerzo significativo.
  
  Importante: No puedes activar la búsqueda de proyectos con un catálogo de productos que se hayan transferido solo como variantes. Si deseas usar la búsqueda y transferir variantes, usa el nivel de producto primary.
11. Haz clic en Importar.
curl
1. Si es la primera vez que subes tu catálogo o vuelves a importarlo 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, establécelo en 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 un directorio temporal de forma automática (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 un directorio temporal automáticamente (recomendado).
  - dataSchema: Para la propiedad dataSchema, usa el valor product_merchant_center. Consulta el esquema de la tabla de productos de Merchant Center.
  Te recomendamos que no especifiques directorios de etapa de pruebas o con errores; de esta manera, se puede crear de forma automática un bucket de Cloud Storage con nuevos directorios de etapa de pruebas y errores. 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 pongan en etapa de prueba datos en el mismo directorio y posiblemente 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 for Retail 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 Retail.

Para obtener 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:

Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que Vertex AI Search for Retail pueda acceder a él. Obtener más información.
Importa los datos de tu catálogo a Vertex AI Search for Retail.
Consola
1. Ve a la página Datos> en la consola de Search for Retail.
  
  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 Retail Product Catalogs Schema. Este es el esquema de productos de Vertex AI Search for Retail.
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 BigQuery y Cloud Storage 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 de producto.
  
  Debes seleccionar el nivel de producto si es la primera vez que importas tu catálogo o si vuelves a importarlo 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 datos requiere un esfuerzo significativo.
  
  Importante: No puedes activar la búsqueda de proyectos con un catálogo de productos que se hayan transferido como variantes.
10. Haz clic en Importar.
curl
1. Si es la primera vez que subes tu catálogo o vuelves a importarlo 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 superior.
  - 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 un directorio temporal de forma automática (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 un directorio temporal automáticamente (recomendado).
  - dataSchema: Para la propiedad dataSchema, usa el valor product (predeterminado). Usarás el esquema de Vertex AI Search for Retail.
  Te recomendamos que no especifiques directorios de etapa de pruebas o con errores; de esta manera, se puede crear de forma automática un bucket de Cloud Storage con nuevos directorios de etapa de pruebas y errores. 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 pongan en etapa de prueba datos en el mismo directorio y posiblemente 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. Para importar la información de tu catálogo, realiza una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí, que 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 del servicio de Vertex AI Search for Retail, completa los siguientes pasos.

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

Abrir la página IAM
Selecciona tu proyecto de Vertex AI Search for Retail.
Busca la cuenta de servicio con el nombre Retail Service Account.

Si no iniciaste una operación de importación con anterioridad, 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 para iniciar la importación. Cuando falle debido a errores de permisos, regresa aquí y completa esta tarea.
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).
Cambia a tu proyecto de BigQuery (en la misma página de IAM y administración) y haz clic en Otorgar acceso.
En Principales nuevas, ingresa el identificador de la cuenta de servicio de Vertex AI Search for Retail y selecciona el rol BigQuery > Usuario de BigQuery.
Haz clic en Agregar otra función y seleccione BigQuery > Editor de datos de BigQuery.

Si no deseas proporcionar la función de editor de datos a todo el proyecto, puedes agregar esta función directamente al conjunto de datos. Obtener más información.
Haz clic en Guardar.

Importa datos de catálogos 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 importarlo a Vertex AI Search for Retail.

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 Sube objetos.

Asegúrate de que la cuenta de servicio de Vertex AI Search for Retail tenga permiso de lectura y escritura en el bucket.

La cuenta de servicio de Vertex AI Search for Retail aparece en la página IAM de la consola de Google Cloud con el nombre Retail Service Account. 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 agregas la cuenta a los permisos de tu bucket.
Importa los datos de tu catálogo.
Consola
1. Ve a la página Datos> en la consola de Search for Retail.
  
  Ir a la página Datos
2. Haz clic en Importar para abrir el panel Importar datos.
3. Elige Catálogo de productos como fuente de datos.
4. Selecciona la rama a la que subirás tu catálogo.
5. Elige Retail Product Catalogs Schema como esquema.
6. Ingresa la ubicación de Cloud Storage de tus datos.
7. Si no tienes habilitada la búsqueda, selecciona los niveles de producto.
  
  Debes seleccionar los niveles de 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 datos requiere un esfuerzo significativo.
  
  Importante: No puedes activar la búsqueda de proyectos con un catálogo de productos que se hayan transferido como variantes.
8. Haz clic en Importar.
curl
1. Si es la primera vez que subes tu catálogo o vuelves a importarlo después de borrarlo definitivamente, configura los niveles de producto 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 crea. El bucket ya debe existir.
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
  }
},
"errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```
3. Importa la información del catálogo mediante una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí, que 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 la operación de importación es usar la consola de Google Cloud. Para obtener más información, consulta Consulta 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. Para solicitar el estado de este objeto, debes reemplazar el campo de nombre con 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 del catálogo de forma intercalada

curl

Para importar la información de tu catálogo de forma intercalada, realiza una solicitud POST al método de REST Products:import y usa el objeto productInlineSource para especificar los datos del catálogo.

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

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

Crea el archivo JSON para tu producto y llámalo ./data.json:

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

Llama al método POST:

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

Java

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 for Retail 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 anterior del producto se puede usar para enriquecer los datos históricos de eventos del usuario 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. Establece la disponibilidad del producto en 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`

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 de pasado.

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 documentados para importar datos del catálogo desde BigQuery o importar datos del catálogo desde Cloud Storage. Sin embargo, asegúrate de configurar el campo expireTime en una marca de tiempo de pasado.

Mantén tu catálogo actualizado

Para obtener 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 importes datos con la consola de Google 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 artículo, 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. Debes hacer esto de la misma manera que la importación inicial; sigue los pasos que se indican en Importa datos del catálogo.

Supervisa el estado de la importación

Para supervisar la transferencia y el estado del catálogo, sigue estos pasos:

Consulta la información agregada sobre tu catálogo y una vista previa de los productos subidos en la pestaña Catálogo de la página Datos de Search for Retail.

Ir a la página Datos
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 búsqueda en la página Calidad de los datos.

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

Ir a la página Calidad de los datos
Para crear alertas que te avisen si algo sale mal en tus cargas de datos, sigue los procedimientos que se indican en Configura alertas de Cloud Monitoring.

Mantener tu catálogo actualizado es importante para obtener resultados de alta calidad. Usa alertas para supervisar las tasas de errores de importación y toma 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.

Importa información del catálogo

Importa datos de un catálogo desde BigQuery

Importa datos de catálogos desde Cloud Storage

Importa datos del catálogo de forma intercalada

Antes de comenzar

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

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

Consideraciones sobre la importación de catálogos

Borrar definitivamente las ramas del catálogo

Sincroniza Merchant Center con Vertex AI Search for Retail

Sincronice su cuenta de Merchant Center

Consola

curl

Genera una lista de los vínculos de tu cuenta de Merchant Center

Consola

curl

Desvincula tu cuenta de Merchant Center

Consola

curl

Limitaciones sobre la vinculación a Merchant Center

Importa datos del catálogo desde Merchant Center

Importar de forma masiva desde Merchant Center

Consola

curl

Importa datos de un catálogo desde BigQuery

Consola

curl

Configura el acceso a tu conjunto de datos de BigQuery

Importa datos de catálogos desde Cloud Storage

Consola

curl

Importa datos del catálogo de forma intercalada

curl

Java

Formato de datos JSON de elementos de productos

Datos históricos de catálogos

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

Llama al método Product.Create

Importación intercalada de productos vencidos

Importa productos vencidos de BigQuery o Cloud Storage

Mantén tu catálogo actualizado

Actualización por lotes

Supervisa el estado de la importación

¿Qué sigue?

Llama al método `Product.Create`