Criar as imagens de referência e indexação

As imagens de referência são imagens que contêm várias vistas dos seus produtos. Aplicam-se as seguintes recomendações:

  • Certifique-se de que o tamanho do ficheiro não excede o tamanho máximo (20 MB).
  • Considere pontos de vista que realcem logicamente o produto e contenham informações visuais relevantes.
  • Crie imagens de referência que complementem os pontos de vista em falta. Por exemplo, se tiver apenas imagens do sapato direito de um par, forneça versões espelhadas desses ficheiros como o sapato esquerdo.
  • Carregue a imagem com a resolução mais alta disponível.
  • Mostre o produto num fundo branco.
  • Converter PNGs com fundos transparentes num fundo sólido.

As imagens têm de ser armazenadas num contentor do Cloud Storage. Se estiver a autenticar a chamada de criação de imagens com uma chave da API, o contentor tem de ser público. Se estiver a fazer a autenticação com uma conta de serviço, essa conta de serviço tem de ter acesso de leitura no contentor.

Criar uma única imagem de referência

Pode adicionar uma imagem de referência a um produto existente. Em seguida, isto permite-lhe pesquisar o produto pela imagem.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • LOCATION_ID: um identificador de localização válido. Os identificadores de localização válidos são: us-west1, us-east1, europe-west1 e asia-east1.
  • PRODUCT_ID: o ID do produto que está associado a uma imagem de referência. Este ID é definido aleatoriamente ou especificado pelo utilizador no momento da criação do produto.
  • CLOUD_STORAGE_IMAGE_URI: o caminho para um ficheiro de imagem válido num contentor do Cloud Storage. Tem de ter, pelo menos, privilégios de leitura para o ficheiro. Exemplo:
    • gs://storage-bucket/filename.jpg

Método HTTP e URL:

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages

Corpo JSON do pedido:

{
  "uri": "cloud-storage-image-uri",
  "boundingPolys": [
    {
      "vertices": [
        {
          "x": X_MIN,
          "y": Y_MIN
        },
        {
          "x": X_MAX,
          "y": Y_MIN
        },
        {
          "x": X_MAX,
          "y": Y_MAX
        },
        {
          "x": X_MIN,
          "y": Y_MAX
        }
      ]
    }
  ]
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages" | Select-Object -Expand Content

Se o pedido for bem-sucedido, o servidor devolve um código de estado HTTP 200 OK e a resposta no formato JSON.

Deverá ver uma saída semelhante à seguinte. O pedido de exemplo especificou um único boundingPoly na imagem. Os vértices da caixa limitadora não são normalizados. Os valores dos vértices são os valores de píxeis reais e não são relativos à imagem original e são dimensionados de 0 a 1. Estes vértices têm os seguintes valores: [(33,22),(282,22),(282,278),(33,278)].


{
  "name": "projects/project-id/locations/location-id/products/product-id/referenceImages/image-id",
  "uri": "gs://storage-bucket/filename.jpg",
  "boundingPolys": [
    {
      "vertices": [
        {
          "x": 33,
          "y": 22
        },
        {
          "x": 282,
          "y": 22
        },
        {
          "x": 282,
          "y": 278
        },
        {
          "x": 33,
          "y": 278
        }
      ]
    }
  ]
}

Go

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Go Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)

// createReferenceImage creates a reference image for a product.
func createReferenceImage(w io.Writer, projectID string, location string, productID string, referenceImageID string, gcsURI string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.CreateReferenceImageRequest{
		Parent: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
		ReferenceImage: &visionpb.ReferenceImage{
			Uri: gcsURI,
		},
		ReferenceImageId: referenceImageID,
	}

	resp, err := c.CreateReferenceImage(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateReferenceImage: %w", err)
	}

	fmt.Fprintf(w, "Reference image name: %s\n", resp.Name)
	fmt.Fprintf(w, "Reference image uri: %s\n", resp.Uri)

	return nil
}

Java

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Java Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

/**
 * Create a reference image.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param referenceImageId - Id of the image.
 * @param gcsUri - Google Cloud Storage path of the input image.
 * @throws IOException - on I/O errors.
 */
public static void createReferenceImage(
    String projectId,
    String computeRegion,
    String productId,
    String referenceImageId,
    String gcsUri)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product.
    String formattedParent = ProductName.format(projectId, computeRegion, productId);
    // Create a reference image.
    ReferenceImage referenceImage = ReferenceImage.newBuilder().setUri(gcsUri).build();

    ReferenceImage image =
        client.createReferenceImage(formattedParent, referenceImage, referenceImageId);
    // Display the reference image information.
    System.out.println(String.format("Reference image name: %s", image.getName()));
    System.out.println(String.format("Reference image uri: %s", image.getUri()));
  }
}

Node.js

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Node.js Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

const vision = require('@google-cloud/vision');

const client = new vision.ProductSearchClient();

async function createReferenceImage() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const referenceImageId = 'Id of the reference image';
  // const gcsUri = 'Google Cloud Storage path of the input image';

  const formattedParent = client.productPath(projectId, location, productId);

  const referenceImage = {
    uri: gcsUri,
  };

  const request = {
    parent: formattedParent,
    referenceImage: referenceImage,
    referenceImageId: referenceImageId,
  };

  const [response] = await client.createReferenceImage(request);
  console.log(`response.name: ${response.name}`);
  console.log(`response.uri: ${response.uri}`);
}
createReferenceImage();

Python

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Python Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

from google.cloud import vision

def create_reference_image(
    project_id, location, product_id, reference_image_id, gcs_uri
):
    """Create a reference image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        reference_image_id: Id of the reference image.
        gcs_uri: Google Cloud Storage path of the input image.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id
    )

    # Create a reference image.
    reference_image = vision.ReferenceImage(uri=gcs_uri)

    # The response is the reference image with `name` populated.
    image = client.create_reference_image(
        parent=product_path,
        reference_image=reference_image,
        reference_image_id=reference_image_id,
    )

    # Display the reference image information.
    print(f"Reference image name: {image.name}")
    print(f"Reference image uri: {image.uri}")


Idiomas adicionais

C#: Siga as instruções de configuração do C# na página das bibliotecas cliente e, em seguida, aceda à documentação de referência da API Vision Product Search para .NET.

PHP: Siga as instruções de configuração do PHP na página das bibliotecas de cliente e, em seguida, visite a documentação de referência da API Vision Product Search para PHP.

Ruby: Siga as instruções de configuração do Ruby na página das bibliotecas cliente e, em seguida, visite a documentação de referência da API Vision Product Search para Ruby.

Criar várias imagens de referência com a importação em massa

Também pode criar imagens de referência ao mesmo tempo que cria um conjunto de produtos e vários produtos.

Crie imagens de referência em massa transmitindo a localização do Cloud Storage de um ficheiro CSV ao método import. Assim, o ficheiro CSV e as imagens para as quais aponta têm de estar num contentor do Cloud Storage.

Se estiver a autenticar a chamada de importação em massa com uma chave da API, este ficheiro de origem CSV tem de ser público.

Se estiver a fazer a autenticação com uma conta de serviço, essa conta de serviço tem de ter acesso de leitura ao ficheiro de origem CSV.

Formato CSV

image-uri,[image-id],product-set-id,product-id,product-category,[product-display-name],[label(s)],[bounding-poly]

Consulte o tópico de instruções sobre o formato CSV para ver informações mais detalhadas sobre a formatação do seu CSV.

Pedido de criação em massa

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • LOCATION_ID: um identificador de localização válido. Os identificadores de localização válidos são: us-west1, us-east1, europe-west1 e asia-east1.
  • STORAGE_PATH: um diretório/recipiente do Cloud Storage onde o ficheiro CSV de entrada está armazenado. O utilizador que faz o pedido tem de ter, pelo menos, autorização de leitura para o contentor.

Método HTTP e URL:

POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets:import

Corpo JSON do pedido:

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "storage-path"
    }
  }
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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 @request.json \
"https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets:import"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets:import" | Select-Object -Expand Content

Deverá ver uma saída semelhante à seguinte. Pode usar o ID da operação (f10f34e32c40a710, neste caso) para obter o estado da tarefa. Por exemplo, consulte o artigo Obter o estado de uma operação:

{
  "name": "projects/project-id/locations/location-id/operations/f10f34e32c40a710"
}

Após a conclusão da operação de longa duração, pode obter os detalhes da operação de importação. A resposta deve ser semelhante à seguinte:

{
  "name": "locations/location-id/operations/f10f34e32c40a710",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2019-12-06T21:16:04.476466873Z",
    "endTime": "2019-12-06T21:16:40.594258084Z"
  },
  "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://my-storage-bucket/img_039.jpg"
      },
      {
        "name": "projects/project-id/locations/location-id/products/product_id1/referenceImages/image1",
        "uri": "gs://my-storage-bucket/img_105.jpg"
      },
      {
        "name": "projects/project-id/locations/location-id/products/product_id2/referenceImages/image2",
        "uri": "gs://my-storage-bucket/img_224.jpg"
      },
      {
        "name": "projects/project-id/locations/location-id/products/product_id3/referenceImages/image3",
        "uri": "gs://my-storage-bucket/img_385.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      {},
      {}
    ]
  }
}

Go

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Go Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.



import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	"cloud.google.com/go/vision/v2/apiv1/visionpb"
)


// importProductSets creates a product set using information in a csv file on GCS.
func importProductSets(w io.Writer, projectID string, location string, gcsURI string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %w", err)
	}
	defer c.Close()

	req := &visionpb.ImportProductSetsRequest{
		Parent: fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		InputConfig: &visionpb.ImportProductSetsInputConfig{
			Source: &visionpb.ImportProductSetsInputConfig_GcsSource{
				GcsSource: &visionpb.ImportProductSetsGcsSource{
					CsvFileUri: gcsURI,
				},
			},
		},
	}

	op, err := c.ImportProductSets(ctx, req)
	if err != nil {
		return fmt.Errorf("ImportProductSets: %w", err)
	}

	fmt.Fprintf(w, "Processing operation name: %s\n", op.Name())

	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %w", err)
	}

	fmt.Fprintf(w, "processing done.\n")

	for i, status := range resp.Statuses {
		// `0` is the coee for OK in google.rpc.code
		fmt.Fprintf(w, "Status of processing line %d of the csv: %d\n", i, status.Code)

		if status.Code == 0 {
			fmt.Fprintf(w, "Reference image name: %s\n", resp.ReferenceImages[i].Name)
		} else {
			fmt.Fprintf(w, "Status code not OK: %s\n", status.Message)
		}
	}

	return nil
}

Java

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Java Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

/**
 * Import images of different products in the product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param gcsUri - Google Cloud Storage URI.Target files must be in Product Search CSV format.
 * @throws Exception - on client errors.
 */
public static void importProductSets(String projectId, String computeRegion, String gcsUri)
    throws Exception {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // A resource that represents Google Cloud Platform location.
    String formattedParent = LocationName.format(projectId, computeRegion);
    Builder gcsSource = ImportProductSetsGcsSource.newBuilder().setCsvFileUri(gcsUri);

    // Set the input configuration along with Google Cloud Storage URI
    ImportProductSetsInputConfig inputConfig =
        ImportProductSetsInputConfig.newBuilder().setGcsSource(gcsSource).build();

    // Import the product sets from the input URI.
    OperationFuture<ImportProductSetsResponse, BatchOperationMetadata> response =
        client.importProductSetsAsync(formattedParent, inputConfig);

    System.out.println(String.format("Processing operation name: %s", response.getName()));
    ImportProductSetsResponse results = response.get();
    System.out.println("Processing done.");
    System.out.println("Results of the processing:");

    for (int i = 0; i < results.getStatusesCount(); i++) {
      System.out.println(
          String.format(
              "Status of processing line %s of the csv: %s", i, results.getStatuses(i)));
      // Check the status of reference image.
      if (results.getStatuses(i).getCode() == 0) {
        ReferenceImage referenceImage = results.getReferenceImages(i);
        System.out.println(referenceImage);
      } else {
        System.out.println("No reference image.");
      }
    }
  }
}

Node.js

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Node.js Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');
// Creates a client
const client = new vision.ProductSearchClient();

async function importProductSets() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const gcsUri = 'Google Cloud Storage URI. Target files must be in Product Search CSV format';

  // A resource that represents Google Cloud Platform location.
  const projectLocation = client.locationPath(projectId, location);

  // Set the input configuration along with Google Cloud Storage URI
  const inputConfig = {
    gcsSource: {
      csvFileUri: gcsUri,
    },
  };

  // Import the product sets from the input URI.
  const [response, operation] = await client.importProductSets({
    parent: projectLocation,
    inputConfig: inputConfig,
  });

  console.log('Processing operation name: ', operation.name);

  // synchronous check of operation status
  const [result] = await response.promise();
  console.log('Processing done.');
  console.log('Results of the processing:');

  for (const i in result.statuses) {
    console.log(
      'Status of processing ',
      i,
      'of the csv:',
      result.statuses[i]
    );

    // Check the status of reference image
    if (result.statuses[i].code === 0) {
      console.log(result.referenceImages[i]);
    } else {
      console.log('No reference image.');
    }
  }
}
importProductSets();

Python

Para saber como instalar e usar a biblioteca cliente da API Vision Product Search, consulte as bibliotecas cliente da API Vision Product Search. Para mais informações, consulte a documentação de referência da API Python Product Search da API Vision.

Para se autenticar na API Vision Product Search, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

def import_product_sets(project_id, location, gcs_uri):
    """Import images of different products in the product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        gcs_uri: Google Cloud Storage URI.
            Target files must be in Product Search CSV format.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = f"projects/{project_id}/locations/{location}"

    # Set the input configuration along with Google Cloud Storage URI
    gcs_source = vision.ImportProductSetsGcsSource(csv_file_uri=gcs_uri)
    input_config = vision.ImportProductSetsInputConfig(gcs_source=gcs_source)

    # Import the product sets from the input URI.
    response = client.import_product_sets(
        parent=location_path, input_config=input_config
    )

    print(f"Processing operation name: {response.operation.name}")
    # synchronous check of operation status
    result = response.result()
    print("Processing done.")

    for i, status in enumerate(result.statuses):
        print("Status of processing line {} of the csv: {}".format(i, status))
        # Check the status of reference image
        # `0` is the code for OK in google.rpc.Code.
        if status.code == 0:
            reference_image = result.reference_images[i]
            print(reference_image)
        else:
            print(f"Status code not OK: {status.message}")


Idiomas adicionais

C#: Siga as instruções de configuração do C# na página das bibliotecas cliente e, em seguida, aceda à documentação de referência da API Vision Product Search para .NET.

PHP: Siga as instruções de configuração do PHP na página das bibliotecas de cliente e, em seguida, visite a documentação de referência da API Vision Product Search para PHP.

Ruby: Siga as instruções de configuração do Ruby na página das bibliotecas cliente e, em seguida, visite a documentação de referência da API Vision Product Search para Ruby.

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.