Esta página foi traduzida pela API Cloud Translation.
Switch to English

Início rápido

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 conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de 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. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. Ative a Vision API.

    Ative a API

  5. Crie uma conta de serviço:

    1. No Console do Cloud, acesse a página Criar conta de serviço.

      Acesse Criar conta de serviço
    2. Selecione um projeto.
    3. No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

    4. Clique em Criar.
    5. Clique no campo Selecionar um papel.

      Em Acesso rápido, clique em Básico e em Proprietário.

    6. Clique em Continuar.
    7. Clique em Concluído para terminar a criação da conta de serviço.

      Não feche a janela do navegador. Você vai usá-lo na próxima etapa.

  6. Crie uma chave de conta de serviço:

    1. No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
    2. Clique em Chaves.
    3. Clique em Adicionar chave e em Criar nova chave.
    4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
    5. Clique em Fechar.
  7. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Definir variáveis de ambiente

Para que a execução das amostras de curl neste tópico seja feita da forma mais conveniente, defina as seguintes variáveis de ambiente, em que:

  • project-id é o ID do seu projeto do Google Cloud Platform (GCP).
  • region-name é o local do GCP que executará o tutorial, por exemplo, us-east1. Os identificadores de local válidos são: us-west1, us-east1, europe-west1 e asia-east1.
export PROJECT_ID=project-id
export LOCATION_ID=region-name

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 application-default print-access-token) \
-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 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 application-default print-access-token)" \
-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 de produtos da Pesquisa de produtos é atualizado aproximadamente a cada 30 minutos. Quando as imagens forem adicionadas ou excluídas, a alteração não se refletirá nas respostas do Product Search até o índice ser atualizado na próxima vez.

Para garantir que a indexação foi concluída com êxito, verifique o campo indexTime de um 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 application-default print-access-token)" \
-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 um ID do conjunto de produtos (por exemplo, product_set0) e o campo indexTime indicando 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 application-default print-access-token)" \
-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. Consulte Como ver e listar recursos para saber mais sobre como usar um pageToken.

{
  "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 amostra. Neste guia de início rápido, use uma imagem armazenada em um bucket do Google Cloud Storage, como a imagem abaixo.

imagem de vestido no 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:

  • my-project-id
  • my-location-id
  • my-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 application-default print-access-token) \
-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 códigos dos produtos. Esses resultados são subdivididos por produtos individuais, identificados por caixas delimitadoras, se houver vários produtos em uma única imagem.

Consulte o tópico Noções básicas sobre respostas de pesquisa e detecção múltipla para ver um exemplo de detecção de um único produto e de multi-detecção de produtos em uma imagem.

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.

Limpeza

Para evitar cobranças desnecessárias do Google Cloud Platform, use o Console do Cloud para excluir o projeto se ele não for mais necessário.

A seguir