Importar información de catálogos

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

Los procedimientos de importación que se describen en esta página se aplican tanto a las recomendaciones como a las búsquedas. Una vez que hayas importado los datos, ambos servicios podrán usarlos, por lo que no tendrás que importar los mismos datos dos veces si utilizas ambos servicios.

Puede importar sus datos de producto desde BigQuery o especificar los datos insertados en la solicitud. Todos estos procedimientos son importaciones únicas, excepto la vinculación de Merchant Center. Programa importaciones periódicas del catálogo (lo ideal es que sean diarias) para verificar que esté actualizado.

Consulta Mantén tu catálogo al día.

También puedes importar artículos de producto concretos. Para obtener más información, consulta Subir un producto.

Antes de empezar

Antes de empezar a importar tu catálogo, debes hacer lo siguiente:

1. Configura tu proyecto.
2. Crea una cuenta de servicio.
3. Añade la cuenta de servicio a tu entorno local.

Para obtener más información, consulta los requisitos de configuración.

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 los datos de su catálogo, cuándo puede usar cada método y algunas de sus limitaciones.

Tutoriales

En esta sección se explican diferentes métodos de importación de catálogos con tutoriales en vídeo y shell.

Tutorial en vídeo

En este vídeo se explica cómo importar un catálogo mediante la API Retail.

Tutorial para importar catálogos de BigQuery

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

Tutorial para importar un catálogo desde Cloud Storage

En este tutorial se explica cómo importar un gran número de artículos a un catálogo.

Tutorial para importar datos de catálogo de forma directa

En este tutorial se explica cómo importar productos a un catálogo de forma insertada.

Prácticas recomendadas para importar catálogos

Se necesitan datos de alta calidad para generar resultados de alta calidad. Si faltan campos en sus datos o tienen valores genéricos en lugar de valores reales, la calidad de sus predicciones y resultados de búsqueda se verá afectada.

Cuando importe datos de catálogo, asegúrese de implementar las siguientes prácticas recomendadas:

• Asegúrese de distinguir cuidadosamente los productos principales de las variantes. Antes de subir datos, consulte Niveles de producto.

  • Cambiar la configuración a nivel de producto después de haber dedicado mucho tiempo a importar datos. Los elementos principales (no las variantes) se devuelven como resultados de búsqueda o recomendaciones.

  • Ejemplo: Si el grupo de SKUs principal es Camiseta de cuello de pico,el modelo de recomendación devuelve una camiseta de cuello de pico y, quizás, camisetas de cuello redondo y de cuello de pico. Sin embargo, si no se usan variantes y cada SKU es primario, cada combinación de color y talla de la camiseta de cuello de pico se devolverá como un artículo distinto en el panel de recomendaciones: camiseta de cuello de pico marrón, talla XL; camiseta de cuello de pico marrón, talla L hasta camiseta de cuello de pico blanca, talla M; camiseta de cuello de pico blanca, talla S.

  • Las colecciones se pueden reconocer juntas siempre que se incluyan los IDs de variante junto con los IDs de producto principales en collectionMemberIds[]. De esta forma, se captura una colección de productos de la que un usuario puede haber comprado uno o varios productos del conjunto, y se atribuye todo el conjunto a la compra. De esta forma, se facilita que se muestren al mismo usuario otros productos de una colección determinada en una consulta relacionada futura.

  • Por ejemplo, si un usuario ha comprado una funda nórdica, se le mostrarán productos a juego de una colección de sábanas, como fundas de almohada.

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

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

  • En el caso de la importación insertada, no importes más de 5000 productos a la vez.

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

• Incluya toda la información opcional del catálogo que pueda.

• Asegúrate de que todos tus eventos usen una sola moneda, sobre todo si tienes previsto usar la consolaGoogle Cloud para obtener métricas de ingresos. La API Vertex AI Search para el sector del comercio no admite el uso de varias monedas por catálogo.

• Mantén tu catálogo actualizado, preferiblemente todos los días. Si programa importaciones periódicas del catálogo, evitará que la calidad del modelo disminuya con el tiempo. Puede programar importaciones automáticas y periódicas al importar su catálogo mediante la consola de búsqueda de comercio. También puedes usar Google Cloud Scheduler para automatizar las importaciones.

• No registre eventos de usuario de artículos de producto que aún no se hayan importado.

• Después de importar la información del catálogo, consulta la información sobre el registro y los informes de errores de tu proyecto. Si detectas más de unos pocos errores, revísalos y corrige los problemas del proceso que hayan provocado los errores.

La pipeline de ingestión de datos de Vertex AI Search para el sector del comercio abarca tanto el catálogo de productos como los datos de eventos de usuario. Este flujo de datos proporciona la base para un entrenamiento de modelos sólido y una evaluación continua a través de mecanismos de comentarios. La ingestión de datos precisa y completa no es solo un requisito previo, sino un proceso continuo esencial para mantener la adaptabilidad de los modelos subyacentes. Esto, a su vez, influye directamente en la calidad y la relevancia de los resultados de búsqueda, lo que ofrece un retorno de la inversión significativo.

Ten en cuenta estas prácticas recomendadas de ingesta de datos al diseñar tu solución de búsqueda de comercio.

¿Importación en bloque, streaming en tiempo real o ambas?

Vertex AI Search para el sector del comercio ofrece dos métodos principales para la ingestión de catálogos:

• Importación en lote

• Streaming en tiempo real

Este enfoque dual se adapta a las diversas necesidades arquitectónicas de los diferentes back-ends de los clientes. No es necesario elegir un método concreto, sino que se puede utilizar un modo de ingestión híbrido que combine la importación masiva y las actualizaciones de streaming en función de los requisitos específicos.

Las importaciones en bloque son ideales cuando se trata de añadir, eliminar o actualizar a gran escala miles de productos a la vez. Por el contrario, el streaming en tiempo real es ideal cuando se necesitan actualizaciones continuas para un volumen de productos relativamente pequeño. La elección entre estos métodos depende de la naturaleza de su catálogo de productos, la frecuencia de las actualizaciones y la arquitectura general de sus sistemas backend.

La función de importación en bloque admite tres fuentes de datos distintas:

• BigQuery BigQuery facilita la modificación rápida de los datos del catálogo, permite especificar fechas de partición durante la importación y posibilita la transformación eficiente de los datos mediante consultas de SQL.
• Google Cloud Storage: Cloud Storage requiere que se cumplan formatos específicos, como JSON, y restricciones de archivos. Los usuarios son responsables de gestionar las estructuras de los contenedores, la fragmentación de los archivos y otros aspectos del proceso de importación. Además, editar directamente el catálogo en Cloud Storage puede ser engorroso y, aunque puede ser rentable, no tiene la flexibilidad de otros métodos.
• Datos insertados: en el caso de catálogos extensos, es posible que las importaciones insertadas no sean la opción más escalable debido a las limitaciones de tamaño. Reserva su uso para actualizaciones menores o pruebas experimentales.

En los casos en los que se produzca un gran volumen de actualizaciones del catálogo de productos (miles de cambios, adiciones o eliminaciones de productos) en un breve periodo de tiempo y a intervalos regulares, puede ser muy eficaz combinar las importaciones en bloque y la transmisión en tiempo real. Almacena provisionalmente las actualizaciones en BigQuery o Cloud Storage y realiza importaciones incrementales masivas a intervalos regulares, como cada hora o cada dos horas. Este método gestiona de forma eficiente las actualizaciones a gran escala y minimiza las interrupciones.

Para las actualizaciones más pequeñas y menos frecuentes, o para las que deban reflejarse inmediatamente en el catálogo, usa la API de streaming en tiempo real. En el enfoque híbrido, la transmisión en tiempo real puede cubrir las lagunas entre las importaciones masivas, lo que garantiza que tu catálogo esté actualizado. Esta estrategia consigue un equilibrio entre hacer llamadas a la API REST individuales (para parchear productos) y realizar cambios en bloque, lo que optimiza tanto la eficiencia como la capacidad de respuesta en la gestión de tu catálogo de Vertex AI Search para el comercio.

Estrategias de ramificación para la gestión de catálogos

Mantener un catálogo unificado en una sola sucursal en lugar de tener catálogos diferentes en varias sucursales. Esta práctica optimiza las actualizaciones del catálogo y reduce el riesgo de incoherencias al cambiar de rama.

Las siguientes estrategias de ramificación habituales son eficaces para gestionar catálogos.

Actualizaciones de una sola sucursal

Designar una rama activa como predeterminada y actualizarla continuamente a medida que se produzcan cambios en el catálogo. Para hacer actualizaciones en bloque, usa la función de importación en periodos de poco tráfico para minimizar las interrupciones. Utiliza APIs de streaming para hacer actualizaciones más pequeñas e incrementales o agrúpalas en bloques más grandes para hacer importaciones periódicas.

Cambio de rama

Hay dos opciones para gestionar diferentes ramas:

• Usa ramas para las fases de prueba y verificación:

  • Algunos ingenieros de sitios de comercio eligen un enfoque de cambio de rama, en el que el catálogo se actualiza en una rama no activa y, a continuación, se convierte en la rama predeterminada (activa) cuando está listo para la producción. De esta forma, se puede preparar el catálogo del día siguiente con antelación. Las actualizaciones se pueden hacer mediante importación en bloque o streaming a la rama no activa, lo que asegura una transición fluida durante los periodos de poco tráfico.
  • La elección entre estas estrategias depende de tus requisitos específicos, la frecuencia de actualización y la configuración de la infraestructura. Sin embargo, independientemente de la estrategia elegida, es fundamental mantener un catálogo unificado en una sola sucursal para obtener un rendimiento óptimo y resultados de búsqueda coherentes en Vertex AI Search for commerce.

• Usa ramas para las copias de seguridad:

  • Una sola rama activa se centra en la ingestión y el procesamiento continuos de las actualizaciones de productos para mantener el índice de Vertex AI Search para el sector del comercio actualizado prácticamente en tiempo real.
  • Otra rama se centra en crear una instantánea diaria de los datos transformados en la búsqueda de comercio, que actúa como un mecanismo de respaldo sólido en caso de que los datos se dañen o haya problemas con la rama 0.
  • Una tercera rama se centra en crear una instantánea semanal de la fecha transformada. De esta forma, el cliente puede tener una copia de seguridad de un día y otra de una semana en ramas diferentes.

Eliminar ramas de catálogo

Si va a importar datos de catálogo nuevos a una sucursal, es importante que la sucursal del catálogo esté vacía para que los datos que se importen a ella sean íntegros. Cuando la sucursal esté vacía, podrá importar nuevos datos de catálogo y vincularla a una cuenta de comerciante.

Si estás publicando tráfico de predicciones o de búsqueda en directo y tienes previsto purgar tu rama predeterminada, te recomendamos que primero especifiques otra rama como predeterminada antes de purgarla. Como la rama predeterminada devolverá resultados vacíos después de purgarse, purgar una rama predeterminada activa puede provocar una interrupción.

Para purgar datos de una rama de catálogo, sigue estos pasos:

1. Ve a la página Datos de la consola de búsqueda de comercio.
   
   Ir a la página Datos

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

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

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

4. Introduce la sucursal y haz clic en Confirmar para purgar los datos del catálogo de la sucursal.

   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 purga, el estado de la purga se mostrará en la lista Catálogo de productos de la ventana Estado de la actividad.

Actualizaciones de inventario en Vertex AI Search para el sector del comercio

En esta sección se describe cómo optimizar el rendimiento de Vertex AI Search para el sector del comercio realizando actualizaciones periódicas del inventario.

Streaming en tiempo real

• En el caso de los datos dinámicos, como la información de inventario (precio y disponibilidad) y los detalles a nivel de tienda, incluido el estado de tramitación y los precios específicos de la tienda, el streaming en tiempo real es la única opción disponible en Vertex AI Search para el sector del comercio.
• Esta distinción se debe a la alta frecuencia de las fluctuaciones del inventario en comparación con los datos del catálogo de productos, que son relativamente estáticos. La disponibilidad de los productos puede cambiar varias veces al día, mientras que las descripciones o los atributos permanecen relativamente constantes.
• La frecuencia de las actualizaciones a nivel de tienda aumenta aún más con el número de establecimientos.

Actualizaciones asíncronas

• Para adaptarse a este ritmo de cambio, Vertex AI Search para el sector del comercio utiliza actualizaciones de inventario asíncronas mediante APIs que devuelven un ID de trabajo.
• El proceso de actualización no se considera completo hasta que se sondea y se confirma el estado del trabajo, lo que puede provocar un pequeño retraso que va de segundos a minutos.

Actualizaciones fuera de plazo

• Una de las características destacables de este sistema es la posibilidad de actualizar la información del inventario antes de que el producto correspondiente se ingiera en el catálogo. De esta forma, se aborda la situación habitual en la que las cadenas de suministro de inventario y de datos de producto operan de forma independiente en los comercios, lo que a veces provoca que la información del inventario esté disponible antes de que se actualice el catálogo de productos. Cuando actualice el inventario, utilice la opción allowMissing para gestionar las actualizaciones de inventario y de productos que no estén en orden.
• Al permitir que las actualizaciones de inventario se produzcan antes de la ingestión del catálogo, Vertex AI Search para el comercio se adapta a estas discrepancias en la canalización, lo que garantiza que los datos de inventario sean precisos incluso en el caso de los productos recién introducidos.
• Sin embargo, la información de inventario de un producto se conserva durante 24 horas y se elimina si no se ingiere un producto coincidente en ese periodo. Este mecanismo asegura la coherencia de los datos e impide que la información de inventario obsoleta se mantenga en el sistema.

Comprobaciones previas del catálogo de productos para realizar pruebas A/B sólidas en Vertex AI Search para el sector del comercio

En esta sección se explica cómo ejecutar comprobaciones previas en los datos del catálogo de productos.

Asegurar la paridad de las actualizaciones del catálogo

• Para preparar una prueba A/B en Vertex AI Search para el sector del comercio, es fundamental mantener una paridad estricta entre el catálogo antiguo (de control) y el catálogo de Vertex AI Search para el sector del comercio (de prueba). Cualquier desequilibrio entre ambos puede afectar negativamente a la prueba A/B, lo que puede dar lugar a observaciones sesgadas y resultados no válidos. Por ejemplo, las incoherencias en la disponibilidad o los precios de los productos, o incluso las discrepancias menores en los atributos, pueden introducir sesgos no intencionados en los datos de prueba.
• Para mitigar este riesgo, es imprescindible diseñar un proceso de actualización paralelo para los catálogos de control y de prueba, evitando las actualizaciones secuenciales siempre que sea posible. El objetivo es maximizar el tiempo durante el cual ambos catálogos están sincronizados. Por otro lado, las actualizaciones en serie pueden provocar retrasos en uno u otro carril. Estos retrasos pueden provocar discrepancias temporales en el catálogo, de modo que un producto puede estar en stock en un catálogo, pero no en otro. O bien, un producto recién añadido aparece en un catálogo antes que en otro. Estas disparidades pueden influir significativamente en el comportamiento, los clics y las compras de los usuarios, lo que en última instancia lleva a una comparación injusta y a resultados imprecisos de las pruebas A/B.
• Al priorizar las actualizaciones paralelas y esforzarse por mantener la paridad del catálogo, las tiendas pueden garantizar la igualdad de condiciones en las pruebas A/B de Vertex AI Search para el sector del comercio. Este enfoque permite analizar los resultados de las pruebas de forma objetiva e imparcial, lo que da lugar a estadísticas más fiables y a la toma de decisiones fundamentadas.

Lograr la paridad de los datos de catálogo

• La profundidad y la precisión de la comprensión de los productos de un modelo de búsqueda de comercio electrónico dependen de la riqueza y la calidad de la información del catálogo de productos subyacente. Cuanto más completos sean los datos de producto del catálogo, mejor preparado estará el modelo para entender y clasificar los productos de forma eficaz.
• Por lo tanto, para preparar las pruebas A/B, es imprescindible asegurarse de que los datos de producto subidos al catálogo antiguo (de control) y al catálogo de Vertex AI Search for commerce (de prueba) sean idénticos. Cualquier discrepancia en la información de los productos entre estos dos entornos puede sesgar significativamente los resultados de las pruebas A/B.
• Por ejemplo, si el buscador antiguo se beneficia de un catálogo más completo o extenso en comparación con Vertex AI Search para el sector del comercio, esto crea una ventaja injusta. Si falta información en el catálogo de Vertex AI Search para el sector del comercio, puede ser crucial para entender y clasificar los productos, lo que puede dar lugar a resultados de búsqueda imprecisos y a comparaciones de rendimiento engañosas. Detectar estas disparidades puede ser complicado con herramientas externas y, a menudo, requiere una inspección manual meticulosa de ambos catálogos.
• Si se aseguran de que ambos catálogos contengan los mismos datos de producto con el mismo nivel de detalle, los comerciantes pueden crear un entorno de pruebas A/B equitativo en Vertex AI Search for commerce. Este enfoque fomenta una comparación justa e imparcial de los dos buscadores, lo que facilita una evaluación precisa de su rendimiento y sus capacidades.

Planificación de la recuperación tras fallos

Un plan de recuperación tras desastres bien preparado asegura que tus funciones de búsqueda de comercio sigan operativas y respondan correctamente, lo que minimiza el impacto en la experiencia de los clientes y en la generación de ingresos. Este plan debería permitir restaurar rápidamente el catálogo para solucionar el posible fallo de las canalizaciones de ingestión de eventos de usuario y de catálogo, independientemente de la causa subyacente.

Usar BigQuery para la organización provisional de datos ofrece una ventaja clara en la recuperación ante desastres. Si el catálogo actual o los datos de eventos de usuario de Vertex AI Search for commerce no son significativamente diferentes de la copia más reciente almacenada en BigQuery, al llamar a la API Import se puede iniciar una restauración rápida. Este enfoque minimiza el tiempo de inactividad y garantiza que la función de búsqueda siga operativa.

Por el contrario, si BigQuery no está integrado en tu flujo de procesamiento de datos, debes tener mecanismos alternativos para volver a cargar el catálogo rápidamente desde un estado correcto conocido. Estos mecanismos pueden incluir sistemas de copia de seguridad, replicación de datos u otras estrategias de conmutación por error.

Si incorporas estas consideraciones sobre la recuperación ante desastres en tu arquitectura de Vertex AI Search para el comercio, podrás reforzar la solidez del sistema y mantener la continuidad del negocio incluso ante interrupciones inesperadas.

Planificar la alta disponibilidad

Cuando suba su catálogo de productos a Vertex AI Search, es importante que tenga en cuenta cómo gestionan los distintos servicios la regionalidad para diseñar una canalización de ingestión de datos resistente. Google Cloud

Para crear una canalización de ingestión con recuperación ante desastres mediante Dataflow, implementa tus trabajos en varias regiones con uno de los siguientes diseños:

• Activo/activo: las instancias de Dataflow de varias regiones procesan datos de forma activa simultáneamente.
• Activa/pasiva: una instancia de Dataflow de una región está activa, mientras que las instancias de otras regiones permanecen en espera.

A continuación, te explicamos cómo implementar estos diseños con Pub/Sub y Dataflow:

• Servicios globales: algunos servicios, como Pub/Sub, operan a nivel mundial. Google Cloud gestiona su disponibilidad de acuerdo con sus acuerdos de nivel de servicio (SLAs) específicos.
• Servicios regionales: otros servicios, como Dataflow, que puedes usar para transformar e ingerir datos en Vertex AI Search, son regionales. Eres responsable de configurar estos componentes para que tengan alta disponibilidad y recuperación tras fallos.

Por ejemplo, al usar BigQuery para conservar datos, se puede configurar para que sea multirregional, de modo que Google Cloudgestione automáticamente la redundancia y la disponibilidad de los datos. Del mismo modo, cuando se usa Cloud Storage, se puede configurar para que sea multirregional.

Diseño activo-activo

El diseño activo/activo usa atributos de mensajes de Pub/Sub y filtros de suscripción para asegurarse de que cada mensaje se procese exactamente una vez por un trabajo de Dataflow activo en una región específica.

1. Añadir atributos de mensaje: cuando publiques mensajes en el tema de Pub/Sub, como actualizaciones de productos, incluye un atributo que indique la región de destino. Por ejemplo:

   • region: us-central1
   • region: us-east1

2. Configurar filtros de suscripción: en cada flujo de procesamiento de Dataflow regional, configure su suscripción de Pub/Sub para que solo extraiga los mensajes que coincidan con su región mediante filtros de mensajes. Por ejemplo, la suscripción a la tarea de Dataflow us-central1 tendría un filtro como attributes.region = "us-central1".

3. Conmutación por error: si una región deja de estar disponible, actualiza tu sistema de publicación upstream para etiquetar todos los mensajes nuevos con un atributo de una región en buen estado. De esta forma, el procesamiento de mensajes se redirige a la instancia de Dataflow de la región de conmutación por error.

Se pueden configurar varios componentes de la arquitectura para que sean multirregionales de forma predeterminada. Por ejemplo, cuando se usa BigQuery para conservar datos, se puede configurar para que sea multirregional, de modo que Cloud Storage gestione automáticamente la redundancia y la disponibilidad de los datos. Del mismo modo, cuando se usa Cloud Storage, se puede configurar para que sea multirregional.

Diseño activo o pasivo

Este diseño implica que solo haya una canalización de Dataflow regional que extraiga mensajes de Pub/Sub en un momento dado.

1. Adjuntar una suscripción: asegúrate de que solo esté adjunta la suscripción de Pub/Sub del trabajo de Dataflow de la región activa y de que esté recibiendo mensajes. Las suscripciones de las tareas de Dataflow en regiones pasivas se deben crear, pero deben permanecer separadas.

2. Conmutación por error: si se produce un error en la región activa, de forma manual o mediante programación:

   • Desvincula la suscripción de Pub/Sub asociada a la tarea de Dataflow de la región que ha fallado.
   • Adjunta la suscripción de Pub/Sub asociada a una tarea de Dataflow en una de las regiones pasivas (de espera).

De esta forma, la carga de procesamiento de mensajes se transfiere a la región recién activada.

Resiliencia y análisis forense

Usar BigQuery en el diseño de la ingestión de datos puede ayudar a gestionar la resiliencia y a crear funciones de análisis forense y depuración. Los productos y el inventario que se ingieren directamente con las APIs patch y addLocalInventory implican que, cuando los datos se envían a Vertex AI Search para el comercio, no queda ningún rastro de la actualización de los productos y el inventario. Es posible que el usuario quiera saber por qué un producto no se muestra como esperaba. Tener un área de almacenamiento provisional creada con BigQuery que incluya un historial completo de los datos facilita este tipo de investigación y depuración.

Arquitectura de referencia

En esta arquitectura, la ingestión de datos suele tener fases sin procesar, seleccionadas y de consumo, todas ellas basadas en BigQuery. El sistema movería los datos entre las fases mediante Dataflow y los orquestaría para automatizar todo el proceso con flujos de trabajo en la nube:

• El sistema tomaría los datos sin procesar tal cual y les añadiría una marca de tiempo para mantener el historial. Estos datos no cambian, por lo que los clientes los considerarían una fuente fiable.
• Después, el sistema transformaría los datos en una fase seleccionada y volvería a etiquetarlos con la hora. De esta forma, los clientes sabrían cuándo se ha transformado y si ha habido algún error.
• Por último, el sistema crearía vistas en la fase de consumo de los datos seleccionados usando la hora en la que el sistema etiquetó los datos anteriormente. De esta forma, el cliente sabrá exactamente qué datos transformados se deben ingerir finalmente en Vertex AI Search para el sector del comercio.

Las ramas 0, 1 y 2 sirven como copias de seguridad activas, de un día y de una semana, respectivamente. Los datos insertados directamente en la rama 0 se agregan y se indexan en la rama 1 a diario y en la rama 2 semanalmente. De esta forma, se puede revertir cualquier corrupción de datos, lo que mejora la continuidad empresarial y la resiliencia del sistema.

Además, se pueden realizar análisis y depuraciones, ya que todo el historial y el linaje de los datos se conservan en conjuntos de datos globales de BigQuery.

Planificar casos extremos con la ingestión de catálogos

Una vez que se hayan establecido los mecanismos principales para la ingestión de catálogos en Vertex AI Search para el sector del comercio, se debe adoptar un enfoque proactivo para evaluar su resiliencia ante varios casos extremos. Aunque es posible que algunos de estos casos no sean relevantes para los requisitos específicos de tu empresa, tenerlos en cuenta en el diseño del backend puede ser muy útil para el futuro.

Este paso preparatorio implica revisar la capacidad de tu canalización de datos para gestionar situaciones inesperadas o extremas, lo que garantiza su solidez y adaptabilidad a las demandas cambiantes. Si anticipas posibles problemas y los abordas de forma proactiva, puedes mitigar las interrupciones futuras y mantener el flujo de datos de producto en tu sistema de búsqueda de comercio.

Para ello, la lógica de Dataflow debe diseñarse de forma que:

• Valida cada elemento de los datos sin procesar para que coincida con un esquema adecuado. El contrato de los datos sin procesar debe determinarse al principio y cada elemento de datos debe compararse siempre con el contrato. Si la validación falla, el elemento de datos sin procesar debe etiquetarse con la hora y conservarse en las tablas sin procesar fallidas de BigQuery con los errores reales que se utilizan para análisis forenses.

  Estos son algunos ejemplos:

  • Un atributo determinado que no forma parte del contrato aparece de repente en el elemento de datos sin procesar.
  • Falta un atributo obligatorio en el elemento de datos sin procesar.

• Valida cada elemento de los datos sin procesar para transformarlos al formato de Vertex AI Search para el sector del comercio. Vertex AI Search para el sector del comercio requiere algunos campos obligatorios para la ingestión de productos. Ahora se debe volver a comprobar cada elemento de los datos sin procesar para ver si se puede transformar correctamente al formato de esquema de Vertex AI Search para el sector del comercio. En caso de que falle la transformación, el elemento de datos sin procesar debe etiquetarse con la hora y conservarse en las tablas de datos seleccionados fallidas de BigQuery con mensajes de error reales que puedan ayudar en las investigaciones.

  Estos son algunos ejemplos:

  • Un atributo concreto, como el precio, no se puede formatear como número porque el elemento de datos sin procesar lo tiene como alfanumérico.
  • Falta el nombre del producto.

En este ejemplo se muestra un esquema de tabla de BigQuery de muestra para conservar todos los errores con fines de depuración:

[
    {
      "mode": "REQUIRED",
      "name": "ingestedTimestamp",
      "type": "TIMESTAMP"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadString",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadBytes",
      "type": "BYTES"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "key",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "value",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "attributes",
      "type": "RECORD"
    },
    {
      "mode": "NULLABLE",
      "name": "errorMessage",
      "type": "STRING"
    },
    {
      "mode": "NULLABLE",
      "name": "stacktrace",
      "type": "STRING"
    }
  ]

Pruebas de estrés y escalabilidad

Prepárate para eventos de gran volumen y para el crecimiento con pruebas de carga y escalabilidad.

Eventos con mucho tráfico

Los eventos con mucho tráfico, como las festividades, suponen un reto importante para las canalizaciones de ingestión de datos. El aumento de las actualizaciones de inventario, incluidos los niveles de stock y los precios, y los posibles cambios en los atributos de los productos requieren una infraestructura sólida. Es importante que evalúes si tu sistema de ingesta puede gestionar este aumento de la carga. Las pruebas de carga simuladas, que replican los patrones de tráfico máximo, identifican los cuellos de botella y aseguran un funcionamiento fluido durante estos periodos críticos.

Ofertas flash

Las ofertas flash suponen un reto único debido a su corta duración y a las rápidas fluctuaciones del inventario. Es fundamental que la sincronización del inventario se realice en tiempo real para evitar discrepancias entre los resultados de búsqueda y la disponibilidad real. Si no lo hace, puede provocar experiencias negativas para los clientes, como que los productos populares aparezcan como disponibles cuando en realidad están agotados, o al revés. Además, los cambios de precio durante las ofertas flash pueden influir significativamente en la clasificación de los productos, lo que pone de manifiesto la necesidad de actualizar los precios de forma precisa y oportuna en el índice de búsqueda.

Expansión del catálogo

El crecimiento de la empresa o la ampliación de la línea de productos pueden provocar un aumento drástico (por ejemplo, de 5 o 10 veces) en el número de productos de su catálogo. Tu arquitectura de ingesta debe ser escalable para adaptarse a este crecimiento sin problemas. Esto puede requerir que se revise toda la canalización de ETL (extracción, transformación y carga), sobre todo si se introducen nuevas fuentes de datos o formatos de información de producto.

Si abordas de forma proactiva estas posibles situaciones, podrás asegurarte de que tu canalización de ingestión de Vertex AI Search para el sector del comercio siga siendo sólida, escalable y adaptable, incluso ante picos de tráfico repentinos, rebajas flash o un crecimiento significativo del catálogo. Esta estrategia proactiva protege la precisión y la fiabilidad de los resultados de búsqueda, lo que contribuye a ofrecer una experiencia de usuario positiva y a impulsar el éxito de la empresa.

El rendimiento de la canalización de ingestión de datos debe evaluarse y se debe establecer una base para las siguientes métricas:

1. ¿Cuánto tiempo se tarda en publicar e ingerir todo el catálogo y los datos de inventario? Esto puede ser necesario de forma puntual durante el BFCM, cuando los precios pueden cambiar significativamente en todo el catálogo.
2. ¿Cuánto tiempo tardará en reflejarse una actualización de un solo producto?
3. ¿Cuál es la tasa más alta de actualizaciones de productos e inventario que puede procesar el sistema?

Cuellos de botella

• Evalúa y comprueba si las canalizaciones pueden aumentar y reducir su escala correctamente.
• Determina si el límite máximo de instancias es demasiado alto o demasiado bajo.
• Determina si Vertex AI Search para el sector del comercio está limitando la frecuencia del sistema comprobando si aparece el código HTTP 429.
• Confirma si es necesario aumentar determinadas cuotas de API para reducir los límites de frecuencia.

Estructura de datos de producto para la ingestión de catálogos

En esta sección se describe cómo preparar los datos de producto para la ingestión de catálogos.

Productos principales

Los productos principales sirven como contenedores para agrupar productos variantes y como entradas en la cuadrícula de búsqueda. Solo se deben especificar los atributos comunes de las variantes en los productos principales. Por ejemplo:

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

Consulte el artículo Acerca de los atributos de producto para obtener más información.

Productos con variantes

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

Entre los atributos obligatorios se incluyen los siguientes:

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

Consulte el artículo Acerca de los atributos de producto para obtener más información.

Obtención de atributos

En el proceso de recuperación se tienen en cuenta todos los atributos por los que se pueden buscar productos principales y variantes.

Puntuación de relevancia

La puntuación de relevancia se basa únicamente en los campos de título y descripción. Para asegurar que se diferencien correctamente, modifique 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 búsqueda

La coincidencia de variantes (por ejemplo, vestido azul) filtra los resultados en función de atributos de variante predefinidos, como el color y la talla. Los resultados de búsqueda devuelven hasta cinco variantes coincidentes de cada producto principal.

Sincronizar Merchant Center con Vertex AI Search para el sector del comercio

Merchant Center es una herramienta que puede usar para que los datos de su tienda y de sus productos estén disponibles en los anuncios de shopping y en otros servicios de Google.

Para que la sincronización entre Merchant Center y Vertex AI Search para el sector del comercio sea continua, puede vincular su cuenta de Merchant Center a Vertex AI Search para el sector del comercio.

Cuando configure una sincronización de Merchant Center para Vertex AI Search for commerce, debe tener asignado el rol de gestión de identidades y accesos Administrador en Merchant Center. Aunque el rol de acceso estándar le permite leer los feeds de Merchant Center, cuando intenta sincronizar Merchant Center con Vertex AI Search para el comercio, aparece un mensaje de error. Por lo tanto, antes de poder sincronizar correctamente su cuenta de Merchant Center con Vertex AI Search para el sector del comercio, debe cambiar su rol.

Vincular una cuenta de Merchant Center

Aunque Vertex AI Search para el comercio está vinculada a la cuenta de Merchant Center, los cambios que haga en los datos de producto de la cuenta de Merchant Center se actualizarán automáticamente en Vertex AI Search para el comercio en cuestión de minutos. Si quiere evitar que los cambios de Merchant Center se sincronicen con Vertex AI Search for commerce, puede desvincular su cuenta de Merchant Center.

Desvincular su cuenta de Merchant Center no elimina los productos de Vertex AI Search para el comercio. Para eliminar productos importados, consulta Eliminar información de productos.

Para sincronizar su cuenta de Merchant Center, siga estos pasos.

Sincronizar una cuenta de Merchant Center

Para ver su cuenta de Merchant Center vinculada, vaya a la página Datos de la consola de comercio y haga clic en el botón Merchant Center, situado en la parte superior derecha de la página. Se abrirá el panel Cuentas de Merchant Center vinculadas. También puede añadir más cuentas de Merchant Center desde este panel.

Consulte Ver información agregada sobre su catálogo para obtener instrucciones sobre cómo ver los productos que se han importado.

Consultar las vinculaciones de cuentas 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"

Desvincular una cuenta de Merchant Center

Si desvincula su cuenta de Merchant Center, esta dejará de sincronizar datos de catálogo con Vertex AI Search para el sector del comercio. Este procedimiento no elimina ningún producto de Vertex AI Search para el sector del comercio 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 de la vinculación con Merchant Center

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

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

• La primera importación después de vincular su cuenta de Merchant Center puede tardar horas en completarse. El tiempo necesario dependerá del número de ofertas de la cuenta de Merchant Center.

• Las modificaciones de productos mediante métodos de la API están inhabilitadas en las ramas vinculadas a una cuenta de Merchant Center. Los cambios que se hagan en los datos del catálogo de productos de esas sucursales deben realizarse en Merchant Center. Esos cambios se sincronizan automáticamente con Vertex AI Search para el sector del comercio.

• El tipo de producto de la colección no se admite en las sucursales que usan la vinculación de Merchant Center.

• Su cuenta de Merchant Center solo se puede vincular a ramas de catálogo vacías para que los datos sean precisos. Para eliminar productos de una rama de catálogo, consulte Eliminar información de producto.

Importar datos del catálogo de BigQuery

Para importar datos de catálogo en el formato correcto desde BigQuery, usa el esquema de Vertex AI Search for commerce para crear una tabla de BigQuery con el formato correcto y cargar la tabla vacía con tus datos de catálogo. A continuación, suba sus datos a Vertex AI Search para el sector del comercio.

Para obtener más ayuda con las tablas de BigQuery, consulta el artículo Introducción a las tablas. Si necesitas ayuda con las consultas de BigQuery, consulta el artículo sobre cómo consultar datos de BigQuery.

Para importar tu catálogo, sigue estos pasos:

1. Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que Vertex AI Search for commerce pueda acceder al conjunto de datos de BigQuery. Más información

2. Importa los datos de tu catálogo a Vertex AI Search para el sector del comercio.

   consola de Cloud

   1. Ve a la página Datos de la consola de búsqueda de comercio.
      
      Ir a la página Datos
   2. Haga clic en Importar para abrir el panel Importar datos.
   3. Elige Catálogo de productos.
   4. Selecciona BigQuery como fuente de datos.
   5. Seleccione la sucursal a la que subirá su catálogo.
   6. Elige Esquema de catálogos de productos de Retail. Este es el esquema de producto de Vertex AI Search para el sector del comercio.
   7. Introduzca la tabla de BigQuery en la que se encuentran sus datos.
   8. Opcional: En Mostrar opciones avanzadas, introduce la ubicación de un segmento de Cloud Storage de tu proyecto como ubicación temporal de tus datos.
      
      Si no se especifica, se usa una ubicación predeterminada. Si se especifica uno, el segmento de BigQuery y el de Cloud Storage deberán estar en la misma región.
   9. Si no tiene habilitada la búsqueda y usa el esquema de Merchant Center, seleccione el nivel de producto.
      
      Debe seleccionar el nivel de producto si es la primera vez que importa su catálogo o si lo vuelve a importar después de haberlo purgado. Más información sobre los niveles de producto Cambiar los niveles de producto después de haber importado datos requiere un esfuerzo considerable.
      
      Importante: No puedes activar la búsqueda de proyectos con un catálogo de productos que se haya insertado como variantes.
   10. Haz clic en Importar.

   curl

   1. Si es la primera vez que sube su catálogo o lo va a volver a importar después de haberlo purgado, defina los niveles de producto mediante el método Catalog.patch. Esta operación requiere el rol de administrador de comercio.

      • ingestionProductType: admite los valores primary (predeterminado) y variant.
      • merchantCenterProductIdField: admite los valores offerId y itemGroupId. Si no usa Merchant Center, no tiene que definir 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 con los parámetros de entrada de la importación.

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

      • DATASET_ID: ID del conjunto de datos de BigQuery.
      • TABLE_ID: el ID de la tabla de BigQuery que contiene los datos.
      • PROJECT_ID: 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 los datos antes de importarlos a BigQuery. Deja este campo vacío para crear automáticamente un directorio temporal (opción recomendada).
      • ERROR_DIRECTORY: opcional. Un directorio de Cloud Storage con información sobre los errores de la importación. Deja este campo en blanco para crear automáticamente un directorio temporal (recomendado).
      • dataSchema: en la propiedad dataSchema, use el valor product (predeterminado). Usarás el esquema de Vertex AI Search para el sector del comercio.

      Te recomendamos que no especifiques directorios de almacenamiento provisional ni de errores. De esta forma, se puede crear automáticamente un segmento de Cloud Storage con nuevos directorios de almacenamiento provisional y de 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 varias tareas de importación transfieran datos al mismo directorio y que se vuelvan a importar los mismos datos). Transcurridos tres días, el contenedor y los directorios se eliminan automáticamente para reducir los costes de almacenamiento.

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

      Si especificas directorios, el segmento de Cloud Storage debe estar en la misma región que el conjunto de datos de BigQuery. De lo contrario, la importación fallará. Proporciona los directorios de almacenamiento provisional y de errores en el formato gs://<bucket>/<folder>/. Deben ser diferentes.

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

   3. Importe la información de su catálogo haciendo una solicitud POST al método REST Products:import. Para ello, proporcione el nombre del archivo de datos (en este caso, 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 consultar el estado de forma programática mediante la API. Deberías recibir un objeto de respuesta similar a este:

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

      El campo name es el ID del objeto de operación. Para solicitar el estado de este objeto, sustituye el campo name por el valor devuelto por el método import hasta que el campo done devuelva 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 devuelto tiene un valor done de true e incluye un objeto Status 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 del directorio de errores en Cloud Storage para ver si se han producido errores durante la importación.

Configurar el acceso a un 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 Vertex AI Search for commerce, sigue estos pasos.

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

   Abre la página de gestión de identidades y accesos.

2. Selecciona tu proyecto de Vertex AI Search para el sector del comercio.

3. Busca la cuenta de servicio con el nombre Retail Service Account.

   Si no has iniciado ninguna operación de importación anteriormente, es posible que esta cuenta de servicio no aparezca. Si no ves esta cuenta de servicio, vuelve a la tarea de importación e inicia la importación. Si falla debido a errores de permisos, vuelve aquí y completa esta tarea.

4. Copia el identificador de la cuenta de servicio, que tiene el formato de una dirección de correo electrónico (por ejemplo, service-525@gcp-sa-retail.).

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

6. En Nuevos principales, introduce el identificador de la cuenta de servicio de Vertex AI Search for commerce y selecciona el rol BigQuery > Usuario de BigQuery.

7. Haz clic en Añadir otro rol y selecciona BigQuery > Editor de datos de BigQuery.

   Si no quiere asignar el rol Editor de datos a todo el proyecto, puede añadirlo directamente al conjunto de datos. Más información

8. Haz clic en Guardar.

Esquema de producto

Cuando importes un catálogo de BigQuery, usa el siguiente esquema de producto de Vertex AI Search for commerce para crear una tabla de BigQuery con el formato correcto y cargarla con los datos de tu catálogo. A continuación, importa el catálogo.

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Importar datos del catálogo de Cloud Storage

Para importar datos de catálogo en formato JSON, crea uno o varios archivos JSON que contengan los datos de catálogo que quieras importar y súbelos a Cloud Storage. Desde ahí, puedes importarlo a Vertex AI Search para el sector del comercio.

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

Para obtener ayuda sobre cómo subir archivos a Cloud Storage, consulta Subir objetos.

1. Asegúrate de que la cuenta de servicio de Vertex AI Search para el sector del comercio tenga permiso para leer y escribir en el segmento.

   La cuenta de servicio de Vertex AI Search para el sector del comercio se muestra en la página IAM de la consola Google Cloud con el nombre Cuenta de servicio de retail. Usa el identificador de la cuenta de servicio, que tiene el formato de una dirección de correo electrónico (por ejemplo, service-525@gcp-sa-retail.), al añadir la cuenta a los permisos de tu segmento.

2. Importa los datos de tu catálogo.

   consola de Cloud

   1. Ve a la página Datos de la consola de búsqueda de comercio.
      
      Ir a la página Datos
   2. Haga clic en Importar para abrir el panel Importar datos.
   3. Elija Catálogo de productos como fuente de datos.
   4. Seleccione la sucursal a la que subirá su catálogo.
   5. Elija Esquema de catálogos de productos de Retail.
   6. Introduce 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 lo vuelves a importar después de haberlo purgado. Más información sobre los niveles de producto Cambiar los niveles de producto después de haber importado datos requiere un esfuerzo considerable.
      
      Importante: No puedes activar la búsqueda de proyectos con un catálogo de productos que se haya insertado como variantes.
   8. Haz clic en Importar.

   curl

   1. Si es la primera vez que sube su catálogo o lo vuelve a importar después de haberlo purgado, defina 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 usa Merchant Center, no tiene que definir 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 con los parámetros de entrada de la importación. Usa el objeto GcsSource para dirigirlo a tu segmento de Cloud Storage.

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

      • INPUT_FILE: uno o varios archivos de Cloud Storage que contengan los datos de su catálogo.
      • ERROR_DIRECTORY: un directorio de Cloud Storage con información sobre los errores de la importación.

      Los campos del 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 segmento ya debe existir.

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

   3. Importe la información de su catálogo haciendo una solicitud POST al método REST Products:import. Para ello, proporcione el nombre del archivo de datos (en este caso, 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 sencilla de comprobar el estado de la operación de importación es usar la consola Google Cloud . Para obtener más información, consulta Ver el estado de una operación de integración específica.

      También puedes consultar el estado de forma programática mediante la API. Deberías recibir un objeto de respuesta similar a este:

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

      El campo name es el ID del objeto de operación. Solicita el estado de este objeto, sustituyendo el campo name por el valor devuelto por el método import, hasta que el campo done devuelva 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 devuelto tiene un valor done de true e incluye un objeto Status 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 del directorio de errores en Cloud Storage para ver qué tipo de errores se han producido durante la importación.

Importar datos de catálogo insertados

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 artículos de producto

Las entradas de Product de tu archivo JSON deben tener un formato similar a los siguientes ejemplos.

Incluya un producto completo en una sola línea. Cada producto debe estar en una línea independiente.

Campos obligatorios:

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

      {
        "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 }
        ]
      }

Historial de datos de catálogo

Vertex AI Search para el sector del comercio permite importar y gestionar datos históricos de catálogos. El historial de datos del catálogo puede ser útil cuando se usan eventos de usuario antiguos para entrenar modelos. La información de productos anteriores se puede usar para mejorar los datos históricos de eventos de usuario y la precisión del modelo.

Los productos antiguos se almacenan como productos caducados. No se devuelven en las respuestas de búsqueda, pero son visibles para las llamadas a las APIs Update, List y Delete.

Importar el historial de datos del catálogo

Si el campo expireTime de un producto tiene asignada una marca de tiempo anterior, se considera un producto histórico. Asigne el valor OUT_OF_STOCK al atributo de disponibilidad del producto para que no afecte a las recomendaciones.

Te recomendamos que utilices los siguientes métodos para importar datos de catálogo históricos:

• Llamar al método Product.Create.
• Importar productos caducados de forma insertada.
• Importar productos caducados de BigQuery.

Llama al método Product.Create.

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

Importar productos caducados de forma insertada

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

Incluya un producto completo en una sola línea. Cada producto debe estar en una línea independiente.

Ejemplo de ./data.json usado en la solicitud de importación insertada:

{
"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
            }
          }
      ]
    }
  }
}

Importar productos caducados de BigQuery o Cloud Storage

Sigue los mismos procedimientos que se describen en los artículos sobre importar datos del catálogo de BigQuery o importar datos del catálogo de Cloud Storage. Sin embargo, asegúrate de asignar al campo expireTime una marca de tiempo anterior.

Mantener tu catálogo actualizado

Para obtener los mejores resultados, su catálogo debe contener información actualizada. Te recomendamos que importes tu 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 al importar datos con la consolaGoogle Cloud .

Puede actualizar solo los elementos de producto nuevos o modificados, o bien importar todo el catálogo. Si importa productos que ya están en su catálogo, no se volverán a añadir. Se actualiza cualquier elemento que haya cambiado.

Para actualizar un solo artículo, consulta Actualizar la información de un producto.

Actualización por lotes

Puede usar el método de importación para actualizar su catálogo por lotes. Para ello, sigue los mismos pasos que para la importación inicial, que se describen en el artículo Importar datos de catálogos.

Monitorizar el estado de la importación

Para monitorizar la ingestión y el estado del catálogo, sigue estos pasos:

1. Consulte información agregada sobre su catálogo y vea una vista previa de los productos subidos en la pestaña Catálogo de la página Datos de la sección 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 búsqueda y desbloquear los niveles de rendimiento de búsqueda en la página Calidad de los datos.

   Para obtener más información sobre cómo comprobar la calidad de los datos de búsqueda y ver los niveles de rendimiento de búsqueda, consulta el artículo Desbloquear niveles de rendimiento de búsqueda. Para ver 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

3. Para crear alertas que te avisen si hay algún problema con las subidas de datos, sigue los procedimientos que se indican en Configurar alertas de Cloud Monitoring.

   Es importante que mantengas tu catálogo actualizado para obtener resultados de alta calidad. Usa alertas para monitorizar las tasas de errores de importación y tomar medidas si es necesario.

Siguientes pasos

• Empieza a registrar eventos de usuario.
• Consulta información agregada sobre tu catálogo.
• Configurar alertas de subida de datos