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 usas ambos servicios.

Tutorial en vídeo

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

Importar datos del catálogo 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.

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Importar datos del catálogo de Cloud Storage

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

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Importar datos de catálogo insertados

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

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Antes de empezar

Antes de importar la información de su catálogo, debe haber completado las instrucciones de la sección Antes de empezar, en concreto, configurar su proyecto, crear una cuenta de servicio y añadir la cuenta de servicio a su entorno local.

Para realizar la importación, debes tener el rol de IAM Administrador de comercios minoristas.

Prácticas recomendadas para importar catálogos

Para generar resultados de alta calidad, se necesitan datos de alta calidad. Si faltan campos en sus datos o tienen valores de marcador de posición 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 registra una colección de productos de la que un usuario puede haber comprado uno o varios productos en el evento de usuario, lo que atribuye toda la colección 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 de registro y de 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.

Acerca de la importación de datos de catálogo

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.

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.

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

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).

Recuperació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.

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.

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

Mientras Vertex AI Search para el comercio esté vinculado 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 cuestión de minutos en Vertex AI Search para el comercio. 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 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 seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

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. Selecciona la sucursal a la que subirás el 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). Al cabo de 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.iam.gserviceaccount.com).

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.

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í, puede 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 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.iam.gserviceaccount.com), 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. Selecciona la sucursal a la que subirás el 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

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

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

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

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

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

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

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

  return operationName;
}

Formato de datos JSON de elementos de 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"
  }

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

Historial de datos de catálogo

Vertex AI Search para el sector del comercio permite importar y gestionar datos históricos de catálogos. Los datos históricos del catálogo pueden ser útiles cuando se usan eventos de usuario históricos 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 de 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, con la diferencia de 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 artículos 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 las importaciones

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