This is the documentation for Recommendations AI only. To try Retail Search and the unified Retail console in the restricted GA phase, contact Cloud sales. If you are not planning to use Retail Search, remain on the Recommendations console until further notice.

If you are using the v1beta version of Recommendations AI, migrate to the Retail API version.

Method: projects.locations.catalogs.branches.products.import

Bulk import of multiple Products.

Request processing may be synchronous. No partial updating is supported. Non-existing items are created.

Note that it is possible for a subset of the Products to be successfully updated.

HTTP request

POST https://retail.googleapis.com/v2beta/{parent=projects/*/locations/*/catalogs/*/branches/*}/products:import

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. projects/1234/locations/global/catalogs/default_catalog/branches/default_branch

If no updateMask is specified, requires products.create permission. If updateMask is specified, requires products.update permission.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestId": string,
  "inputConfig": {
    object (ProductInputConfig)
  },
  "errorsConfig": {
    object (ImportErrorsConfig)
  },
  "updateMask": string,
  "reconciliationMode": enum (ReconciliationMode),
  "notificationPubsubTopic": string
}
Fields
requestId

string

Unique identifier provided by client, within the ancestor dataset scope. Ensures idempotency and used for request deduplication. Server-generated if unspecified. Up to 128 characters long and must match the pattern: [a-zA-Z0-9_]+. This is returned as [Operation.name][] in ImportMetadata.

Only supported when ImportProductsRequest.reconciliation_mode is set to FULL.
inputConfig

object (ProductInputConfig)

Required. The desired input location of the data.
errorsConfig

object (ImportErrorsConfig)

The desired location of errors incurred during the Import.
updateMask

string (FieldMask format)

Indicates which fields in the provided imported 'products' to update. If not set, will by default update all fields.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".
reconciliationMode

enum (ReconciliationMode)

The mode of reconciliation between existing products and the products to be imported. Defaults to ReconciliationMode.INCREMENTAL.
notificationPubsubTopic

string

Pub/Sub topic for receiving notification. If this field is set, when the import is finished, a notification will be sent to specified Pub/Sub topic. The message data will be JSON string of a Operation. Format of the Pub/Sub topic is projects/{project}/topics/{topic}.

Only supported when ImportProductsRequest.reconciliation_mode is set to FULL.

Response body

If successful, the response body contains an instance of Operation.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • retail.products.import

For more information, see the IAM documentation.

ProductInputConfig

The input config source for products.

JSON representation 
{

  // Union field source can be only one of the following:
  "productInlineSource": {
    object (ProductInlineSource)
  },
  "gcsSource": {
    object (GcsSource)
  },
  "bigQuerySource": {
    object (BigQuerySource)
  }
  // End of list of possible types for union field source.
}
Fields
Union field source. Required. The source of the input. source can be only one of the following:
productInlineSource

object (ProductInlineSource)

The Inline source for the input content for products.
gcsSource

object (GcsSource)

Google Cloud Storage location for the input content.
bigQuerySource

object (BigQuerySource)

BigQuery input source.

ProductInlineSource

The inline source for the input config for products.import method.

JSON representation 
{
  "products": [
    {
      object (Product)
    }
  ]
}
Fields
products[]

object (Product)

Required. A list of products to update/create. Each product must have a valid Product.id. Recommended max of 100 items.

ReconciliationMode

Indicates how imported products are reconciled with the existing products created or imported before.

Enums
RECONCILIATION_MODE_UNSPECIFIED Defaults to INCREMENTAL.
INCREMENTAL Inserts new products or updates existing products.
FULL

Calculates diff and replaces the entire product dataset. Existing products may be deleted if they are not present in the source location.

Can only be while using BigQuerySource.

Add the IAM permission "BigQuery Data Viewer" for cloud-retail-customer-data-access@system.gserviceaccount.com before using this feature otherwise an error is thrown.

This feature is only available for users who have Retail placements.search enabled. Please submit a form here to contact cloud sales if you are interested in using Retail placements.search.