products

Creates, updates, deletes, gets or lists a products resource.

Overview

Name	products
Type	Resource
Id	google.vision.products

Fields

The following fields are returned by SELECT queries:

projects_locations_product_sets_products_list

Successful response

Name	Datatype	Description
name	string	The resource name of the product. Format is: projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID. This field is ignored when creating a product.
description	string	User-provided metadata to be stored with this product. Must be at most 4096 characters long.
displayName	string	The user-provided name for this Product. Must not be empty. Must be at most 4096 characters long.
productCategory	string	Immutable. The category for the product identified by the reference image. This should be one of "homegoods-v2", "apparel-v2", "toys-v2", "packagedgoods-v1" or "general-v1". The legacy categories "homegoods", "apparel", and "toys" are still supported, but these should not be used for new products.
productLabels	array	Key-value pairs that can be attached to a product. At query time, constraints can be specified based on the product_labels. Note that integer values can be provided as strings, e.g. "1199". Only strings with integer values can match a range-based restriction which is to be supported soon. Multiple values can be assigned to the same key. One product may have up to 500 product_labels. Notice that the total number of distinct product_labels over all products in one ProductSet cannot exceed 1M, otherwise the product search pipeline will refuse to work for that ProductSet.

projects_locations_products_get

Successful response

Name	Datatype	Description
name	string	The resource name of the product. Format is: projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID. This field is ignored when creating a product.
description	string	User-provided metadata to be stored with this product. Must be at most 4096 characters long.
displayName	string	The user-provided name for this Product. Must not be empty. Must be at most 4096 characters long.
productCategory	string	Immutable. The category for the product identified by the reference image. This should be one of "homegoods-v2", "apparel-v2", "toys-v2", "packagedgoods-v1" or "general-v1". The legacy categories "homegoods", "apparel", and "toys" are still supported, but these should not be used for new products.
productLabels	array	Key-value pairs that can be attached to a product. At query time, constraints can be specified based on the product_labels. Note that integer values can be provided as strings, e.g. "1199". Only strings with integer values can match a range-based restriction which is to be supported soon. Multiple values can be assigned to the same key. One product may have up to 500 product_labels. Notice that the total number of distinct product_labels over all products in one ProductSet cannot exceed 1M, otherwise the product search pipeline will refuse to work for that ProductSet.

projects_locations_products_list

Successful response

Name	Datatype	Description
name	string	The resource name of the product. Format is: projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID. This field is ignored when creating a product.
description	string	User-provided metadata to be stored with this product. Must be at most 4096 characters long.
displayName	string	The user-provided name for this Product. Must not be empty. Must be at most 4096 characters long.
productCategory	string	Immutable. The category for the product identified by the reference image. This should be one of "homegoods-v2", "apparel-v2", "toys-v2", "packagedgoods-v1" or "general-v1". The legacy categories "homegoods", "apparel", and "toys" are still supported, but these should not be used for new products.
productLabels	array	Key-value pairs that can be attached to a product. At query time, constraints can be specified based on the product_labels. Note that integer values can be provided as strings, e.g. "1199". Only strings with integer values can match a range-based restriction which is to be supported soon. Multiple values can be assigned to the same key. One product may have up to 500 product_labels. Notice that the total number of distinct product_labels over all products in one ProductSet cannot exceed 1M, otherwise the product search pipeline will refuse to work for that ProductSet.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
projects_locations_product_sets_products_list	select	projectsId, locationsId, productSetsId	pageSize, pageToken	Lists the Products in a ProductSet, in an unspecified order. If the ProductSet does not exist, the products field of the response will be empty. Possible errors: * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1.
projects_locations_products_get	select	projectsId, locationsId, productsId		Gets information associated with a Product. Possible errors: * Returns NOT_FOUND if the Product does not exist.
projects_locations_products_list	select	projectsId, locationsId	pageSize, pageToken	Lists products in an unspecified order. Possible errors: * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1.
projects_locations_products_create	insert	projectsId, locationsId	productId	Creates and returns a new product resource. Possible errors: * Returns INVALID_ARGUMENT if display_name is missing or longer than 4096 characters. * Returns INVALID_ARGUMENT if description is longer than 4096 characters. * Returns INVALID_ARGUMENT if product_category is missing or invalid.
projects_locations_products_patch	update	projectsId, locationsId, productsId	updateMask	Makes changes to a Product resource. Only the display_name, description, and labels fields can be updated right now. If labels are updated, the change will not be reflected in queries until the next index time. Possible errors: * Returns NOT_FOUND if the Product does not exist. * Returns INVALID_ARGUMENT if display_name is present in update_mask but is missing from the request or longer than 4096 characters. * Returns INVALID_ARGUMENT if description is present in update_mask but is longer than 4096 characters. * Returns INVALID_ARGUMENT if product_category is present in update_mask.
projects_locations_products_delete	delete	projectsId, locationsId, productsId		Permanently deletes a product and its reference images. Metadata of the product and all its images will be deleted right away, but search queries against ProductSets containing the product may still work until all related caches are refreshed.
projects_locations_products_purge	exec	projectsId, locationsId		Asynchronous API to delete all Products in a ProductSet or all Products that are in no ProductSet. If a Product is a member of the specified ProductSet in addition to other ProductSets, the Product will still be deleted. It is recommended to not delete the specified ProductSet until after this operation has completed. It is also recommended to not add any of the Products involved in the batch delete to a new ProductSet while this operation is running because those Products may still end up deleted. It's not possible to undo the PurgeProducts operation. Therefore, it is recommended to keep the csv files used in ImportProductSets (if that was how you originally built the Product Set) before starting PurgeProducts, in case you need to re-import the data after deletion. If the plan is to purge all of the Products from a ProductSet and then re-use the empty ProductSet to re-import new Products into the empty ProductSet, you must wait until the PurgeProducts operation has finished for that ProductSet. The google.longrunning.Operation API can be used to keep track of the progress and results of the request. Operation.metadata contains BatchOperationMetadata. (progress)

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
locationsId	string
productSetsId	string
productsId	string
projectsId	string
pageSize	integer (int32)
pageToken	string
productId	string
updateMask	string (google-fieldmask)

SELECT examples

projects_locations_product_sets_products_list

Lists the Products in a ProductSet, in an unspecified order. If the ProductSet does not exist, the products field of the response will be empty. Possible errors: * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1.

SELECT
name,
description,
displayName,
productCategory,
productLabels
FROM google.vision.products
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND productSetsId = '{{ productSetsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

projects_locations_products_get

Gets information associated with a Product. Possible errors: * Returns NOT_FOUND if the Product does not exist.

SELECT
name,
description,
displayName,
productCategory,
productLabels
FROM google.vision.products
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND productsId = '{{ productsId }}' -- required;

projects_locations_products_list

Lists products in an unspecified order. Possible errors: * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1.

SELECT
name,
description,
displayName,
productCategory,
productLabels
FROM google.vision.products
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

INSERT examples

projects_locations_products_create

Creates and returns a new product resource. Possible errors: * Returns INVALID_ARGUMENT if display_name is missing or longer than 4096 characters. * Returns INVALID_ARGUMENT if description is longer than 4096 characters. * Returns INVALID_ARGUMENT if product_category is missing or invalid.

INSERT INTO google.vision.products (
data__name,
data__displayName,
data__description,
data__productCategory,
data__productLabels,
projectsId,
locationsId,
productId
)
SELECT 
'{{ name }}',
'{{ displayName }}',
'{{ description }}',
'{{ productCategory }}',
'{{ productLabels }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ productId }}'
RETURNING
name,
description,
displayName,
productCategory,
productLabels
;

Manifest

# Description fields are for documentation purposes
- name: products
  props:
    - name: projectsId
      value: string
      description: Required parameter for the products resource.
    - name: locationsId
      value: string
      description: Required parameter for the products resource.
    - name: name
      value: string
      description: >
        The resource name of the product. Format is: `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. This field is ignored when creating a product.
        
    - name: displayName
      value: string
      description: >
        The user-provided name for this Product. Must not be empty. Must be at most 4096 characters long.
        
    - name: description
      value: string
      description: >
        User-provided metadata to be stored with this product. Must be at most 4096 characters long.
        
    - name: productCategory
      value: string
      description: >
        Immutable. The category for the product identified by the reference image. This should be one of "homegoods-v2", "apparel-v2", "toys-v2", "packagedgoods-v1" or "general-v1". The legacy categories "homegoods", "apparel", and "toys" are still supported, but these should not be used for new products.
        
    - name: productLabels
      value: array
      description: >
        Key-value pairs that can be attached to a product. At query time, constraints can be specified based on the product_labels. Note that integer values can be provided as strings, e.g. "1199". Only strings with integer values can match a range-based restriction which is to be supported soon. Multiple values can be assigned to the same key. One product may have up to 500 product_labels. Notice that the total number of distinct product_labels over all products in one ProductSet cannot exceed 1M, otherwise the product search pipeline will refuse to work for that ProductSet.
        
    - name: productId
      value: string

UPDATE examples

projects_locations_products_patch

Makes changes to a Product resource. Only the display_name, description, and labels fields can be updated right now. If labels are updated, the change will not be reflected in queries until the next index time. Possible errors: * Returns NOT_FOUND if the Product does not exist. * Returns INVALID_ARGUMENT if display_name is present in update_mask but is missing from the request or longer than 4096 characters. * Returns INVALID_ARGUMENT if description is present in update_mask but is longer than 4096 characters. * Returns INVALID_ARGUMENT if product_category is present in update_mask.

UPDATE google.vision.products
SET 
data__name = '{{ name }}',
data__displayName = '{{ displayName }}',
data__description = '{{ description }}',
data__productCategory = '{{ productCategory }}',
data__productLabels = '{{ productLabels }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND productsId = '{{ productsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
description,
displayName,
productCategory,
productLabels;

DELETE examples

projects_locations_products_delete

Permanently deletes a product and its reference images. Metadata of the product and all its images will be deleted right away, but search queries against ProductSets containing the product may still work until all related caches are refreshed.

DELETE FROM google.vision.products
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND productsId = '{{ productsId }}' --required;

Lifecycle Methods

projects_locations_products_purge

Asynchronous API to delete all Products in a ProductSet or all Products that are in no ProductSet. If a Product is a member of the specified ProductSet in addition to other ProductSets, the Product will still be deleted. It is recommended to not delete the specified ProductSet until after this operation has completed. It is also recommended to not add any of the Products involved in the batch delete to a new ProductSet while this operation is running because those Products may still end up deleted. It's not possible to undo the PurgeProducts operation. Therefore, it is recommended to keep the csv files used in ImportProductSets (if that was how you originally built the Product Set) before starting PurgeProducts, in case you need to re-import the data after deletion. If the plan is to purge all of the Products from a ProductSet and then re-use the empty ProductSet to re-import new Products into the empty ProductSet, you must wait until the PurgeProducts operation has finished for that ProductSet. The google.longrunning.Operation API can be used to keep track of the progress and results of the request. Operation.metadata contains BatchOperationMetadata. (progress)

EXEC google.vision.products.projects_locations_products_purge 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required 
@@json=
'{
"productSetPurgeConfig": "{{ productSetPurgeConfig }}", 
"deleteOrphanProducts": {{ deleteOrphanProducts }}, 
"force": {{ force }}
}';