Esta es la documentación solo de Recomendaciones IA. Para probar Retail Search y la consola unificada de venta minorista en la fase restringida de Google Analytics, comuníquese con el equipo de Ventas de Cloud. Si no planea usar Retail Search, permanezca en la consola de Recomendaciones hasta nuevo aviso.

Si usas la versión v1beta de Recomendaciones IA, migra a la versión minorista de la API.

Importar información de los catálogos

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

Antes de comenzar

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

Debes elegir los niveles de producto antes de importar tu catálogo y debes tener la función de Administrador de venta minorista de IAM para poder realizar la importación.

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

Recomendaciones IA requiere datos de alta calidad para realizar predicciones de alta calidad. Si a tus datos les faltan campos o tienen valores de marcador de posición en lugar de valores reales, la calidad de tus predicciones se ve afectada.

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

  • Asegúrate de revisar la información sobre los niveles de producto antes de subir cualquier dato.

    Cambiar los niveles de producto después de importar cualquier dato requiere un esfuerzo significativo.

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

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

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

  • Asegúrate de que toda la información del catálogo requerida esté incluida y sea correcta.

    No uses valores ficticios o de marcador de posición.

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

  • Asegúrate de que todos tus eventos usen una moneda única, en especial si planeas usar Cloud Console para obtener métricas de ingresos. La API de venta minorista no admite el uso de varias monedas por catálogo.

  • Mantén actualizado tu catálogo.

    Lo ideal es actualizarlo a diario. La programación de importaciones periódicas de catálogo evita que la calidad del modelo disminuya con el tiempo. Puedes usar Google Cloud Scheduler para automatizar esta tarea.

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

  • Después de importar la información del catálogo, revisa la información sobre el registro y los informes de errores para tu proyecto.

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

Importación de datos de catálogos

Para importar tus datos de productos, puedes hacerlo desde Merchant Center, Cloud Storage, BigQuery o especificar los datos intercalados en la solicitud. Cada uno de estos procedimientos es de importaciones únicas. Te recomendamos importar el catálogo a diario para asegurarte de que esté actualizado. Consulta Mantenimiento de tu catálogo actualizado.

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

Importación de datos de catálogos de Merchant Center

Puedes importar datos de catálogos de Merchant Center con Cloud Console o la API de venta minorista.

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

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

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

  2. Si tu conjunto de datos de BigQuery está en otro proyecto, configura los permisos necesarios para que Recomendaciones IA pueda acceder al conjunto de datos de BigQuery. Más información

  3. Importa tus datos de catálogos de BigQuery a Recomendaciones IA.

    Console

    1. Ve a la página Datos de Recomendaciones IA en Google Cloud Console.
      Ir a la página Datos de Recomendaciones IA
    2. Haz clic en Importar para abrir el panel Importar catálogo.
    3. Ingresa los ID del conjunto de datos y la tabla de BigQuery en los que se encuentran tus datos.
    4. Ingresa la ubicación de un bucket de Cloud Storage en tu proyecto.

      Este bucket se usa como una ubicación temporal para tus datos.

    5. Si es la primera vez que importas tu catálogo o si vuelves a importar uno después de borrar definitivamente, selecciona los niveles de producto para la carga (registro de eventos del usuario) y predicción.

      Cambiar los niveles de producto después de importar cualquier dato requiere un esfuerzo significativo. Obtén más información sobre los niveles de producto.

    6. Haga clic en Import.

    cURL

    1. Si es la primera vez que subes tu catálogo o si vuelves a importar uno después de la eliminación, configura tuniveles de producto mediante la Catalog.patch. Para esta operación se requiere la función de Administrador de venta minorista.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      --data '{
      "productLevelConfig": {
        "ingestionProductType": "PRODUCT-TYPE",
        "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
      }
      }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"
    2. Importa tu catálogo mediante el método Products.import.

      • dataset-id: el ID del conjunto de datos de BigQuery.
      • table-id: el ID de la tabla de BigQuery que contiene tus datos.
      • staging-directory: Opcional Un directorio de Cloud Storage que se usa como ubicación provisional de tus datos antes de que se importen a BigQuery. Deja este campo vacío para que Recomendaciones IA cree de forma automática un directorio temporal (recomendado).
      • error-directory: Opcional Un directorio de Cloud Storage para obtener información sobre los errores de la importación. Deja este campo vacío para que Recomendaciones IA cree de forma automática un directorio temporal (recomendado).
      • dataSchema: Para la propiedad dataSchema, usa el valor product_merchant_center. Consulta el esquema de la tabla de productos de Merchant Center.

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

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

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

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

Importación de datos de catálogos de BigQuery

Si deseas importar datos del catálogo en el formato correcto desde BigQuery, usa el esquema de Recomendaciones IA para crear una tabla de BigQuery con el formato correcto y Carga la tabla vacía con los datos de tu catálogo. Luego, carga los datos a Recomendaciones IA.

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

curl

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

  2. Si es la primera vez que subes tu catálogo o si lo vuelves a importar después de borrarlo definitivamente, configura tus niveles de producto mediante el método Catalog.patch. Para esta operación, se requiere la función de administrador de Recomendaciones IA.

    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"
    
  3. Crea un archivo de datos para los parámetros de entrada de la importación. Los valores de tus parámetros de entrada dependen de si importas desde Cloud Storage o BigQuery.

    Usa el objeto BigQuerySource para apuntar al conjunto de datos de BigQuery.

    • dataset-id: el ID del conjunto de datos de BigQuery.
    • table-id: el ID de la tabla de BigQuery que contiene tus datos.
    • project-id: El ID del proyecto en el que se encuentra la fuente de BigQuery. Si no se especifica, el ID del proyecto se hereda de la solicitud superior.
    • staging-directory: Opcional Un directorio de Cloud Storage que se usa como ubicación provisional para tus datos antes de que se importen a BigQuery. Deja este campo vacío para que Recomendaciones IA cree de forma automática un directorio temporal (recomendado).
    • error-directory: Opcional Un directorio de Cloud Storage para obtener información sobre los errores de la importación. Deja este campo vacío para que Recomendaciones IA cree de forma automática un directorio temporal (recomendado).
    • dataSchema: Para la propiedad dataSchema, usa el valor product (predeterminado). Usarás el esquema de Recomendaciones IA.

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

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

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

    {
    "inputConfig":{
     "bigQuerySource": {
       "projectId": "project-id",
       "datasetId":"dataset-id",
       "tableId":"table-id",
       "dataSchema":"product"}
      }
    }
    
  4. Importa la información de tu catálogo a Recomendaciones IA mediante una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí se muestra como input.json).

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

    La forma más fácil de verificar el estado de tu operación de importación es usar Cloud Console. Si deseas obtener más información, consulta Visualización del estado de una operación de integración específica.

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

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

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

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

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

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

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

Configura el acceso a tu conjunto de datos de BigQuery

Para configurar el acceso cuando el conjunto de datos de BigQuery está en un proyecto diferente al del servicio de Recomendaciones IA, completa los siguientes pasos.

  1. Abre la página IAM en Cloud Console.

    Abrir la página IAM

  2. Selecciona tu proyecto de Recomendaciones IA.

  3. Busca la cuenta de servicio con el nombre Cuenta de servicio de Recomendaciones de AutoML.

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

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

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

  6. Ingresa el identificador para la cuenta de servicio de Recomendaciones IA y selecciona la función BigQuery > Usuario de BigQuery.

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

    Si no deseas proporcionar la función de editor de datos a todo el proyecto, puedes agregar esta función directamente al conjunto de datos. Más información

  8. Haz clic en Guardar.

Importación de datos de catálogos desde Cloud Storage

Para importar datos del catálogo en formato JSON, crea uno o más archivos JSON que contengan los datos del catálogo que deseas importar y súbelos a Cloud Storage. Desde allí, puedes importarlo a Recomendaciones IA.

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

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

curl

  1. Asegúrate de que la cuenta de servicio de Recomendaciones IA tenga permiso para leer y escribir en el bucket.

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

  2. Si es la primera vez que subes tu catálogo o si vuelves a importar el catálogo después de borrarlo definitivamente, configura tus niveles de producto mediante el método Catalog.patch.

    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"
    
  3. Crea un archivo de datos para los parámetros de entrada de la importación. Usas el objeto GcsSource para que apunte a tu bucket de Cloud Storage.

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

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

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

    {
    "inputConfig":{
     "gcsSource": {
       "inputUris": ["input-file1", "input-file2"]
     }
    },
    "errorsConfig":{"gcsPrefix":"error-directory"}
    }
    
  4. Importa la información de tu catálogo a Recomendaciones IA mediante una solicitud POST al método de REST Products:import y proporciona el nombre del archivo de datos (aquí se muestra como input.json).

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

    La forma más fácil de verificar el estado de tu operación de importación es usar Cloud Console. Si deseas obtener más información, consulta Visualización del estado de una operación de integración específica.

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

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

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

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

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

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

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

Importa datos de catálogos en línea

curl

Importa la información de tu catálogo a Recomendaciones IA de forma intercalada mediante una solicitud POST al método REST Products:import mediante productInlineSource para especificar los datos de tu catálogo.

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

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

    {
    "inputConfig": {
    "productInlineSource": {
      "products": [
        {
          <product1>
        },
        {
          <product2>
        },
        ....
      ]
    }
    }
    }
    
  2. Llama al método POST:

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

Formato de datos JSON de elementos de productos

Las entradas Product del archivo JSON deberían verse como los siguientes ejemplos. Los saltos de línea son para facilitar la lectura Debe proporcionar un artículo completo en una sola línea. Cada artículo de producto debe estar en su propia línea.

Campos obligatorios mínimos:

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

Objeto completo:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
  "id": "1234",
  "categories": "Apparel & Accessories > Shoes",
  "title": "ABC sneakers",
  "description": "Sneakers for the rest of us",
  "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
  "language_code": "en",
  "tags": [ "black-friday" ],
  "priceInfo": {"currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50},
  "availableTime": "2020-01-01T03:33:33.000001Z",
  "availableQuantity": "1",
  "uri":"http://foobar",
  "images": [{"uri": "http://foobar/img1", "height": 320, "width": 320 }]
}

Cómo mantener tu catálogo actualizado

Recomendaciones IA se basa en tener información actual del producto para proporcionarte las mejores recomendaciones. Te recomendamos importar el catálogo a diario para asegurarte de que esté actualizado. Puedes usar Google Cloud Scheduler para programar importaciones.

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

Para actualizar un solo elemento, consulta Actualización de la información del catálogo.

Actualización por lotes

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

Supervisa el estado de la importación

Mantener actualizado tu catálogo es importante para obtener recomendaciones de alta calidad. Debes supervisar las tasas de error de importación y tomar medidas si es necesario. Si quieres obtener más información, consulta Configuración de alertas para problemas de carga de datos.

¿Qué sigue?