Crie um conjunto de produtos e pesquise produtos

Este guia de início rápido demonstra como criar e usar os três tipos de recursos da API Vision Product Search: um conjunto de produtos que contém um grupo de produtos e imagens de referência associadas a esses produtos.

Neste início rápido, vai criar um conjunto de produtos, produtos e as respetivas imagens de referência num único passo através da importação em lote.

Depois de o conjunto de produtos ter sido indexado, pode consultar o conjunto de produtos através da API Vision Product Search.

Este guia de início rápido explica o processo de:

  • Usar um CSV e a importação em massa para criar um conjunto de produtos, produtos e imagens de referência.
  • Fazer um pedido à API Vision Product Search com uma imagem armazenada num contentor do Cloud Storage.

Antes de começar

Se ainda não o fez, configure o seu projeto conforme explicado abaixo.

Configure o seu projeto

  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. Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    • 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: 

    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. Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  11. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  12. Create or select a Google Cloud project.

    • 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: 

    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.

    Defina variáveis de ambiente

    Para tornar mais conveniente a execução dos exemplos curl neste início rápido, defina as seguintes variáveis de ambiente, em que:

    • PROJECT_ID é o ID do seu Google Cloud projeto.
    • LOCATION_ID é a Google Cloud localização que vai executar o seu tutorial, por exemplo, us-east1. Os identificadores de localização válidos são: us-west1, us-east1, europe-west1 e asia-east1 .

    Usar um conjunto de dados

    Neste guia de início rápido, usa um conjunto de dados de aproximadamente 100 entradas de apparel-v2categoria de produtoapparel-v2. Este conjunto de dados disponível publicamente está localizado num contentor do Cloud Storage público em:

    O formato CSV é o seguinte:

    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",

    Use a importação em massa para criar um conjunto de produtos, produtos e imagens de referência

    Use o seguinte comando curl para criar um novo conjunto de produtos com produtos e imagens de referência. Este conjunto chama-se product_set0, um valor declarado no CSV de importação.

    Primeiro, crie um ficheiro JSON de pedido denominado import_request.json e guarde-o no diretório de trabalho atual:

    import_request.json

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

    Depois de criar o ficheiro JSON de pedido, envie o pedido:

    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

    Uma resposta bem-sucedida contém um objeto de operação de longa duração:

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

    A resposta também contém um ID da operação relativo (por exemplo, 0a0aec86192599fa) que pode ser usado para obter o estado da operação.

    Obtenha o estado da operação de importação

    Pode usar o operation-id devolvido pela operação de importação para verificar o estado da operação de importação em massa:

    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

    Uma resposta bem-sucedida tem o seguinte aspeto:

    {
  "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": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

    Indexar

    O índice de produtos da Pesquisa de produtos é atualizado aproximadamente a cada 30 minutos. Quando as imagens são adicionadas ou eliminadas, a alteração não é refletida nas suas respostas da Pesquisa de produtos até à próxima atualização do índice.

    Para se certificar de que a indexação foi concluída com êxito, verifique o campo indexTime de um conjunto de produtos.

    Liste conjuntos de produtos e verifique a indexação

    Pode listar todos os seus conjuntos de produtos e usar o campo indexTime para verificar se a indexação foi concluída com êxito:

    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

    Uma resposta bem-sucedida apresenta todos os seus conjuntos de produtos, incluindo um ID do conjunto de produtos (por exemplo, product_set0), bem como o campo indexTime, que indica quando a indexação foi concluída:

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

    Liste produtos

    Pode usar o PRODUCT_SET_ID devolvido da lista de conjuntos de produtos para listar todos os produtos no seu conjunto de produtos:

    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

    Uma resposta bem-sucedida apresenta os detalhes do produto.

    Neste pedido, usa o parâmetro de consulta opcional pageSize para definir a lista de resultados para 15 produtos. O elemento nextPageToken na resposta também indica que existem mais produtos a apresentar. Pode usar o token indicado para obter mais resultados. Para mais informações sobre a utilização de um pageToken, consulte o artigo Obter e listar 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"
}

    Pesquise produtos correspondentes com a API Vision Product Search

    Após a conclusão da indexação, pode pesquisar produtos que correspondam a uma imagem de exemplo. Neste início rápido, usa uma imagem armazenada num contentor do Google Cloud Storage, como a seguinte imagem.

    Uma imagem de um vestido num contentor do Cloud Storage.
    gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

    Pesquise através de uma imagem remota

    Use o seguinte pedido para pesquisar através da imagem armazenada num contentor do Cloud Storage público.

    Primeiro, crie um ficheiro JSON de pedido denominado search_request.json e guarde-o no diretório de trabalho atual. Altere os seguintes valores no JSON do pedido para corresponderem às informações do seu projeto:

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

    Depois de criar o ficheiro JSON de pedido, envie o pedido:

    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

    Um pedido bem-sucedido devolve uma lista de produtos correspondentes, indicados pelo respetivo ID do produto. Estes resultados são ainda discriminados por produtos individuais identificados por caixas delimitadoras se existirem vários produtos numa única imagem.

    Para ver um exemplo de deteção de um único produto e deteção múltipla de produtos numa imagem, consulte Compreender as respostas de pesquisa e a deteção múltipla.

    Também é devolvido um campo score. Este campo indica a confiança com que o serviço considera que o produto corresponde à imagem fornecida, numa escala de 0 (sem confiança) a 1 (confiança total).

    O campo indexTime mostra a versão do índice que está a ser pesquisada. As alterações às imagens feitas após esta hora não são refletidas nos resultados.

    Parabéns! Fez o seu primeiro pedido images.annotate ao serviço Product Search da API Vision.

    Limpar

    1. Optional: Revoke credentials from the gcloud CLI. 

      gcloud auth revoke

    2. Delete a Google Cloud project:

      gcloud projects delete PROJECT_ID

    O que se segue?