Crear un conjunto de productos y buscar productos

En esta guía de inicio rápido se muestra cómo crear y usar los tres tipos de recursos de Product Search de la API de Vision: un conjunto de productos, que contiene un grupo de productos, e imágenes de referencia asociadas a esos productos.

En esta guía de inicio rápido, crearás un conjunto de productos, productos y sus imágenes de referencia en un solo paso mediante la importación por lotes.

Una vez que se haya indexado el conjunto de productos, puedes consultarlo con Product Search de la API de Vision.

En esta guía de inicio rápido se explica cómo hacer lo siguiente:

  • Usar un archivo CSV y la importación en bloque para crear un conjunto de productos, productos e imágenes de referencia.
  • Enviar una solicitud a la API Product Search de Vision con una imagen almacenada en un segmento de Cloud Storage.

Antes de empezar

Si aún no lo has hecho, configura tu proyecto como se explica a continuación.

Configurar el proyecto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vision API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable vision.googleapis.com

  8. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Replace the following:

    • PROJECT_ID: your project ID.
    • USER_IDENTIFIER: the identifier for your user account—for example, myemail@example.com.
    • ROLE: the IAM role that you grant to your user account.

  9. Install the Google Cloud CLI.

  10. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  12. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  13. Verify that billing is enabled for your Google Cloud project.

  14. Enable the Vision API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable vision.googleapis.com

  15. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Replace the following:

    • PROJECT_ID: your project ID.
    • USER_IDENTIFIER: the identifier for your user account—for example, myemail@example.com.
    • ROLE: the IAM role that you grant to your user account.
    16.

    Establece variables de entorno:

    Para que te resulte más cómodo ejecutar las muestras de curl en esta guía de inicio rápido, define las siguientes variables de entorno:

    • PROJECT_ID es el ID de tu Google Cloud proyecto.
    • LOCATION_ID es la Google Cloud ubicación en la que se ejecutará tu tutorial. Por ejemplo, us-east1. Los identificadores de ubicación válidos son us-west1, us-east1, europe-west1 y asia-east1 .

    Usar un conjunto de datos

    En esta guía de inicio rápido, se utiliza un conjunto de datos de unas 100 entradas de categorías de producto apparel-v2. Este conjunto de datos disponible públicamente se encuentra en un segmento público de Cloud Storage en la siguiente ubicación:

    El formato CSV es el siguiente:

    gs://cloud-ai-vision-data/product-search-tutorial/images/filename1.jpg,image0,product_set0,product_id0,apparel-v2,,"style=women,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename2.jpg,image1,product_set0,product_id1,apparel-v2,,"style=men,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename3.jpg,image2,product_set0,product_id2,apparel-v2,,"style=women,category=dress",

    Usar la importación en bloque para crear un conjunto de productos, productos e imágenes de referencia

    Usa el siguiente comando curl para crear un conjunto de productos con productos e imágenes de referencia. Este conjunto se llama product_set0, un valor declarado en el archivo CSV de importación.

    Primero, crea un archivo JSON de solicitud llamado import_request.json y guárdalo en tu directorio de trabajo actual:

    import_request.json

    {
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

    Después de crear el archivo JSON de la solicitud, envíala:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @import_request.json \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets:import

    Una respuesta correcta contiene un objeto de operación de larga duración:

    {
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fa"
}

    La respuesta también contiene un ID de operación relativo (por ejemplo, 0a0aec86192599fa) que se puede usar para obtener el estado de la operación.

    Obtener el estado de una operación de importación

    Puedes usar el operation-id devuelto por la operación de importación para comprobar el estado de la operación de importación en bloque:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/locations/LOCATION_ID/operations/OPERATION_ID

    A continuación, se muestra un ejemplo de respuesta correcta:

    {
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fb",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2018-11-30T03:11:04.808114024Z",
    "endTime": "2018-11-30T03:11:38.624444324Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0/referenceImages/image0",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a0cbcf70ba11e89399d20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1/referenceImages/image1",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a1aea370ba11e888d4d20059124800.jpg"
      },
      ...
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id93/referenceImages/image93",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4697319970ba11e8a7bfd20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id94/referenceImages/image94",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4698596370ba11e8bf6ad20059124800.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

    Indexación

    El índice de búsqueda de productos se actualiza aproximadamente cada 30 minutos. Cuando se añaden o se eliminan imágenes, el cambio no se reflejará en las respuestas de Búsqueda de Productos hasta que se actualice el índice.

    Para comprobar que la indexación se ha completado correctamente, consulta el campo indexTime de un conjunto de productos.

    Listar conjuntos de productos y comprobar la indexación

    Puedes enumerar todos tus conjuntos de productos y usar el campo indexTime para verificar que la indexación se ha completado correctamente:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets

    Si la respuesta es correcta, se mostrarán todos los conjuntos de productos, incluido un ID de conjunto de productos (por ejemplo, product_set0), así como el campo indexTime, que indica cuándo se ha completado la indexación:

    {
  "productSets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

    Lista de productos

    Puede usar el PRODUCT_SET_ID devuelto de la lista de conjuntos de productos para enumerar todos los productos de su conjunto de productos:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID/products?pageSize=15

    Una respuesta correcta muestra los detalles del producto.

    En esta solicitud, se usa el parámetro de consulta opcional pageSize para definir la lista de resultados en 15 productos. El elemento nextPageToken de la respuesta también indica que hay más productos que mostrar. Puedes usar el token que se indica para obtener más resultados. Para obtener más información sobre cómo usar un pageToken, consulta Obtener y enumerar recursos.

    {
  "products": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "men"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    ...
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id21",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "dress"
        }
      ]
    }
  ],
  "nextPageToken": "1LqhSgZfM_uWKOxvog"
}

    Buscar productos coincidentes con Product Search de la API de Vision

    Una vez completada la indexación, puede buscar productos que coincidan con una imagen de muestra. En esta guía de inicio rápido, se usa una imagen almacenada en un segmento de Google Cloud Storage, como la siguiente.

    Una imagen de un vestido en un segmento de Cloud Storage.
    gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

    Buscar usando una imagen remota

    Usa la siguiente solicitud para buscar con la imagen almacenada en un segmento público de Cloud Storage.

    Primero, crea un archivo JSON de solicitud llamado search_request.json y guárdalo en el directorio de trabajo actual. Cambia los siguientes valores del JSON de la solicitud para que coincidan con la información de tu proyecto:

    • PROJECT_ID
    • LOCATION_ID
    • PRODUCT_SET_ID

    search_request.json

    {
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg"
        }
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH"
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID",
          "productCategories": [
            "apparel-v2"
          ],
          "filter": "style=womens OR style=women"
        }
      }
    }
  ]
}

    Después de crear el archivo JSON de la solicitud, envíala:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @search_request.json \
    https://vision.googleapis.com/v1/images:annotate

    Si la solicitud se realiza correctamente, se devuelve una lista de productos coincidentes, indicados por su ID de producto. Estos resultados se desglosan por productos individuales identificados por cuadros delimitadores si hay varios productos en una sola imagen.

    Para ver un ejemplo de detección de un solo producto y de varios productos en una imagen, consulta el artículo Comprender las respuestas de búsqueda y la multidetección.

    También se devuelve un campo score. Este campo indica la confianza con la que el servicio cree que el producto coincide con la imagen proporcionada, en una escala del 0 (sin confianza) al 1 (confianza total).

    El campo indexTime muestra la versión del índice en la que se está buscando. Los cambios en las imágenes que se hagan después de esa hora no se reflejarán en los resultados.

    ¡Enhorabuena! Has enviado tu primera solicitud images.annotate al servicio Product Search de la API Vision.

    Limpieza

    1. Optional: Revoke credentials from the gcloud CLI. 

      gcloud auth revoke

    2. Delete a Google Cloud project:

      gcloud projects delete PROJECT_ID

    Siguientes pasos