Criar um conjunto de produtos e pesquisar produtos

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

Neste guia de início rápido, você criará um conjunto de produtos, produtos e as imagens de referência deles em uma única etapa por meio da importação em lote.

Depois que o conjunto de produtos tiver sido indexado, será possível consultá-lo usando a Pesquisa de produtos da API Vision.

Este guia de início rápido detalha os seguintes processos:

  • usar um CSV e uma importação em massa para criar um conjunto de produtos, produtos e imagens de referência;
  • fazer uma solicitação para a Pesquisa de produtos da API do Vision com uma imagem armazenada em um bucket do Cloud Storage.

Antes de começar

Configure seu projeto como explicado abaixo, se ainda não tiver feito isso.

Criar o projeto

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a Google Cloud CLI.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

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

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto do:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto do que você está criando.

    • Selecione o Google Cloud projeto do que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto do.

  6. Verifique se o faturamento está ativado para o Google Cloud projeto.

  7. Ative a API Vision:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable vision.googleapis.com

  8. Conceda papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM: roles/storage.objectViewer 

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

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • USER_IDENTIFIER: o identificador da sua conta de usuário. Por exemplo, myemail@example.com.
    • ROLE: o papel do IAM que você concede à sua conta de usuário.

  9. Instale a Google Cloud CLI.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

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

    gcloud init

  12. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto do:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto do que você está criando.

    • Selecione o Google Cloud projeto do que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto do.

  13. Verifique se o faturamento está ativado para o Google Cloud projeto.

  14. Ative a API Vision:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable vision.googleapis.com

  15. Conceda papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM: roles/storage.objectViewer 

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

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • USER_IDENTIFIER: o identificador da sua conta de usuário. Por exemplo, myemail@example.com.
    • ROLE: o papel do IAM que você concede à sua conta de usuário.
    16.

Como usar um conjunto de dados

Neste guia de início rápido, use um conjunto de dados de aproximadamente 100 entradas da categoria dos produtos apparel-v2. Esse conjunto de dados disponível ao público está localizado em um bucket público do Cloud Storage 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",

Usar 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. Esse conjunto recebe o nome product_set0, um valor declarado no CSV de importação.

Primeiro, crie um arquivo JSON de solicitação chamado import_request.json e salve-o no diretório de trabalho atual.

import_request.json

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

Após criar o arquivo JSON de solicitação, envie a solicitação:

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

Substitua:

  • LOCATION_ID: o local em que o tutorial será executado, por exemplo, us-east1. Os identificadores de local válidos são: us-west1, us-east1, europe-west1 e asia-east1.

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 de operação relativo (por exemplo, 0a0aec86192599fa) que pode ser usado para ver o status da operação.

Receber o status da operação de importação

Você pode usar o OPERATION_ID retornado da operação de importação para verificar o status 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

Veja um exemplo de uma resposta bem-sucedida:

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

Indexação

O índice da Pesquisa de Produtos é atualizado aproximadamente todos os dias. Quando houver adição ou exclusão de imagens, essas mudanças só vão aparecer nas respostas da Pesquisa de Produtos quando o índice for atualizado.

Para saber se a indexação foi realizada, verifique o campo indexTime do conjunto de produtos.

Listar conjuntos de produtos e verificar a indexação

Liste todos os seus conjuntos de produtos e use o campo indexTime para conferir se a indexação foi concluída:

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 relaciona todos os seus conjuntos de produtos, incluindo o ID do conjunto (por exemplo, product_set0) e 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": {}
    }
  ]
}

Listar produtos

Você pode usar o PRODUCT_SET_ID retornado 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 lista os detalhes do produto.

Nessa solicitação, use o parâmetro de consulta opcional pageSize para definir a lista de resultados como 15 produtos. O nextPageToken na resposta também indica que há mais produtos para listar. É possível usar o token listado para recuperar mais resultados. Para mais informações sobre como usar um pageToken, consulte Como receber 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"
}

Pesquisar produtos correspondentes com o Product Search da API Vision

Depois que a indexação for concluída, será possível pesquisar produtos que correspondam a uma imagem de exemplo. Neste guia de início rápido, você usa uma imagem armazenada em um bucket do Google Cloud Storage, como a imagem a seguir.

A imagem de um vestido em um bucket do Cloud Storage.
gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

Pesquisar usando uma imagem remota

Use a seguinte solicitação para pesquisar usando a imagem armazenada em um bucket público do Cloud Storage.

Primeiro, crie um arquivo JSON de solicitação chamado search_request.json e salve-o no diretório de trabalho atual. Altere os seguintes valores no JSON da solicitação para corresponder à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"
        }
      }
    }
  ]
}

Após criar o arquivo JSON de solicitação, envie a solicitação:

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

Uma solicitação bem-sucedida retorna uma lista de produtos correspondentes, indicada pelos respectivos IDs. Esses resultados são subdivididos por produtos individuais, identificados por caixas delimitadoras, caso haja vários produtos em uma única imagem. Uma solicitação bem-sucedida retorna uma lista de produtos correspondentes, indicada pelos respectivos IDs. Esses resultados são subdivididos por produtos individuais, identificados por caixas delimitadoras, se houver vários produtos em uma única imagem.

Confira um exemplo de detecção de um ou vários produtos em uma imagem em Noções básicas sobre as respostas de pesquisa e a detecção múltipla.

Um campo score também é retornado. Esse campo indica a confiança do serviço de que o produto corresponde à imagem fornecida, em uma escala de 0 (nenhuma confiança) a 1 (confiança total).

O campo indexTime mostra qual versão do índice está sendo pesquisada. As alterações de imagem feitas após esse horário não aparecerão nos resultados.

Parabéns! Você fez sua primeira solicitação de images.annotate ao serviço de Pesquisa de produtos da API do Vision.

Limpar

  1. Opcional: revogar credenciais da CLI gcloud. 

    gcloud auth revoke

  2. Excluir um Google Cloud projeto do:

    gcloud projects delete PROJECT_ID

A seguir