Esta es la documentación de Recomendaciones IA, Retail Search y la nueva consola de venta minorista. Para usar Retail Search en la fase restringida de Google Analytics, comuníquese con el equipo de Ventas de Cloud.

Si solo usas Recomendaciones IA, permanece en la consola de Recomendaciones y consulta la documentación de Recomendaciones IA.

Importar datos de autocompletado

El autocompletado es una función que permite predecir el resto de las palabras que escribe un usuario, lo que puede mejorar la experiencia de búsqueda del usuario. Puede proporcionar sugerencias antes de que se escriban en función del conjunto de datos proporcionado o en función de los eventos de usuario que proporcionaste.

En esta página, se describe cómo importar tu conjunto de datos de autocompletado a la venta minorista. Estas instrucciones son solo para subir tus datos de autocompletado. Mantenla actualizada si planeas usar tu conjunto de datos de autocompletado todo el tiempo. Para obtener la función de autocompletado, consulta CompletionService.CompleteQuery. Los datos de autocompletado solo se usan para la búsqueda de venta minorista. Recomendaciones IA no usa estos datos.

Antes de comenzar

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

Debes tener la función de IAM Editor de venta minorista para poder realizar la importación.

Prácticas recomendadas para la importación del autocompletado

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

  • Lee los archivos de esquema enumerados en las secciones y la documentación de la API a continuación.

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

  • Incluye tantos campos como sea posible.

  • Mantén tu propio conjunto de datos de autocompletado actualizado si planeas usar tu propio conjunto de datos subido.

Importa datos de autocompletado

Importa datos de autocompletado desde BigQuery

Si quieres importar datos de autocompletado en el formato correcto desde BigQuery, usa el esquema de autocompletado de venta minorista para crear una tabla de BigQuery con el formato correcto y cargar la tabla con tus datos de autocompletado. Luego, sube tus datos a la venta minorista.

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.

Propaga datos a BigQuery

Usa el esquema de autocompletado de venta minorista para subir tus datos de autocompletado a BigQuery.

BigQuery puede usar el esquema para validar si los datos con formato JSON tienen nombres y tipos de campo correctos (como STRING, INTEGER y RECORD), pero no pueden realizar validaciones, como la determinación:

  • Si un campo de string se asignó a un valor de enumeración reconocible.
  • Si un campo de string usa el formato correcto.
  • Si un campo de número entero o flotante tiene valor en un rango válido.
  • Si un campo faltante es un campo obligatorio.

Para garantizar la calidad de tus datos y la experiencia de búsqueda del usuario final, asegúrate de consultar el esquema y la documentación de referencia para obtener detalles sobre los valores y formatos.

Importa datos de autocompletado a la venta minorista

curl

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

  2. 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 a tu conjunto de datos de BigQuery.

    • dataset-id: el ID del conjunto de datos de BigQuery.
    • table-id: el ID de la tabla de BigQuery que contiene tus datos.
    • data-schema: Para la propiedad dataSchema, usa el valor suggestions (predeterminado), allowlist y denylist. Usarás el esquema de autocompletado de venta minorista.
    {
      "inputConfig":{
        "bigQuerySource": {
          "datasetId":"dataset-id",
          "tableId":"table-id",
          "dataSchema":"data-schema"
        }
      }
    }
    
  3. Importa la información de autocompletado a la venta minorista mediante una solicitud POST al método de REST CompletionData: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/v2alpha/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/completionData:import"
    

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

    {
      "name": "projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/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/v2alpha/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/operations/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/123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2alpha.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.v2alpha.ImportCompletionDataResponse",
      }
    }
    

Configura el acceso a tu conjunto de datos de BigQuery

Para configurar el acceso cuando tu conjunto de datos de BigQuery está en un proyecto diferente al de tu servicio de venta minorista, completa los siguientes pasos.

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

    Abrir la página IAM

  2. Selecciona tu proyecto de venta minorista.

  3. Busca la cuenta de servicio con el nombre Retail Service Account (Cuenta de servicio de venta minorista).

    Si no iniciaste una operación de importación con la venta minorista, 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, cloud-retail-customer-data-access@system.gserviceaccount.com).

  5. En IAM y administración y haz clic en Agregar.

  6. Ingresa el identificador de la cuenta de servicio de venta minorista y selecciona la función BigQuery > Visualizador de datos de BigQuery.

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

  7. Haz clic en Guardar.

Formato de datos de autocompletado

Tu archivo JSON debería verse como los siguientes ejemplos: Los saltos de línea son para facilitar la lectura; debes proporcionar una sugerencia completa en una sola línea. Cada sugerencia debe estar en su propia línea.

Campos obligatorios mínimos de las sugerencias:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

O el siguiente:

{
  "suggestion": "ABC",
  "frequency": "100"
}

Duración de la importación de datos de autocompletado

Por lo general, la importación desde BigQuery tarda alrededor de 10 horas. La operación de larga duración envía el conjunto de datos para la entrega de producción. Una vez que el conjunto de datos esté listo para entregarse, el campo done en el objeto de operación se marcará como verdadero. Antes de que la operación sea done, no se garantiza que se obtendrá la última sugerencia del conjunto de datos de importación.

Mantén actualizado tu conjunto de datos de autocompletado

Si planeas usar tu propio conjunto de datos subido, se recomienda mantenerlo actualizado con regularidad.

Actualización por lotes

Puedes usar el método de importación para actualizar por lotes el autocompletado. El procedimiento es el mismo que para la importación inicial; sigue los pasos en Importación de datos de autocompletado. Esto reemplazará todo el conjunto de datos importado.

Supervisa el estado de la importación

Mantener actualizado tu conjunto de datos es importante para obtener resultados de sugerencias de alta calidad cuando los uses. Debes supervisar las tasas de error de importación y tomar medidas si es necesario.

Esquema de autocompletado automático

Cuando importes un conjunto de datos de autocompletado desde BigQuery, usa el esquema de venta minorista a continuación para crear tablas de BigQuery con el formato correcto y cargarlas con tus datos de autocompletado.

Esquema para sugerencias

Este conjunto de datos se usa para sugerir frases con escritura anticipada.

Esquema para la lista de bloqueo

Este conjunto de datos se usa como una lista de bloqueo para evitar que se sugieran frases.

Esquema para la lista de entidades permitidas

Este conjunto de datos se usa para omitir los procesos posteriores, p. ej., la corrección ortográfica, en todas las frases de esta lista de entidades permitidas.