Google Cloud Retail

Common errors

• ImportError: cannot import name 'RetailServiceClient' from 'google.cloud.retail'

  cause Attempting to import the client class from the top-level `google.cloud.retail` package instead of its versioned submodule.
  fix Change the import statement to specify the API version: `from google.cloud.retail_v2 import RetailServiceClient`.

• google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or explicitly create credentials and pass them to the client.

  cause The client library could not find valid Google Cloud credentials in the environment or user's configuration.
  fix Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or run `gcloud auth application-default login` in your terminal to set up user credentials.

• google.api_core.exceptions.NotFound: 404 Not Found: Requested entity was not found.

  cause The resource specified in the request (e.g., project, location, catalog, product) does not exist or the authenticated user does not have permission to access it.
  fix Verify that the `project_number`, `location_id`, and other resource identifiers are correct and that the Google Cloud Retail API is enabled for the specified project. Check IAM permissions for the principal making the request.

• google.api_core.exceptions.InvalidArgument: 400 Request contains an invalid argument.

  cause A field in the request payload (e.g., product data, configuration settings) does not conform to the API's requirements, or a resource name is malformed.
  fix Carefully review the API documentation for the specific method being called to ensure all required fields are present and correctly formatted. Pay close attention to resource name formats and enum values.

Warnings

• gotcha Google Cloud client libraries often use versioned imports (e.g., `_v2`, `_v2beta`). Using the wrong version or attempting to import from the root `google.cloud.retail` directly will result in an `ImportError`.
  Fix: Always import `RetailServiceClient` and `types` from the specific API version submodule, such as `from google.cloud.retail_v2 import RetailServiceClient, types`.
• gotcha Many Retail API operations (e.g., `import_products`, `tune_model`, `create_product`) are long-running operations (LROs) that return an `Operation` object. You must poll this object to check its status and retrieve the final result, as the initial call does not block until completion.
  Fix: After calling an LRO method, use `operation.result()` to wait for completion and retrieve the result, or `operation.done()` and `operation.metadata()` for asynchronous polling. Consult the method's documentation for the expected response type.
• gotcha Authentication is typically handled automatically via `google-auth`, but requires `GOOGLE_APPLICATION_CREDENTIALS` environment variable for service accounts, or `gcloud auth application-default login` for user credentials. Failure to set this up correctly leads to `DefaultCredentialsError`.
  Fix: Ensure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid service account key file, or run `gcloud auth application-default login` in your terminal for user-based authentication. Confirm the authenticated principal has sufficient IAM permissions for the Retail API.
• gotcha Resource names in Google Cloud Retail API (e.g., for products, catalogs, branches) follow a specific format like `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/branches/{branch_id}/products/{product_id}`. Incorrectly formatted resource names can lead to `InvalidArgument` or `NotFound` errors.
  Fix: Always construct resource names using the client's helper methods, such as `client.catalog_path(...)`, `client.product_path(...)`, or carefully follow the documented format for each API call.

Install

• pip install google-cloud-retail Install stable version

Imports

• RetailServiceClient
  wrong:

  from google.cloud.retail import RetailServiceClient

  correct:

  from google.cloud.retail_v2 import RetailServiceClient

  The client class is typically versioned (e.g., `_v2`) and resides within the versioned submodule, not directly under the top-level package.
• types
  wrong:

  from google.cloud.retail import types

  correct:

  from google.cloud.retail_v2 import types

  API message types (e.g., `types.Product`, `types.Catalog`) are also found within the versioned submodule.

Quickstart

This quickstart demonstrates how to initialize the `RetailServiceClient` and list the catalogs configured for a Google Cloud project. It uses environment variables for project configuration and handles potential authentication issues. Replace `YOUR_PROJECT_NUMBER` or set `GCP_PROJECT_NUMBER` environment variable.

import os
from google.cloud.retail_v2 import RetailServiceClient

# Ensure GOOGLE_APPLICATION_CREDENTIALS is set or gcloud is authenticated
# For local development, run: gcloud auth application-default login

project_number = os.environ.get('GCP_PROJECT_NUMBER', 'YOUR_PROJECT_NUMBER') # e.g., '1234567890'
location_id = 'global' # or a specific region, e.g., 'us-central1'

try:
    client = RetailServiceClient()
    parent = f"projects/{project_number}/locations/{location_id}"
    
    print(f"Listing catalogs for parent: {parent}")
    response = client.list_catalogs(parent=parent)
    
    found_catalogs = False
    for catalog in response:
        print(f"  Catalog name: {catalog.name}, Display name: {catalog.display_name}")
        found_catalogs = True
    
    if not found_catalogs:
        print("No catalogs found. Ensure the project number and location are correct and the Retail API is enabled.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Make sure 'GCP_PROJECT_NUMBER' environment variable is set or replace 'YOUR_PROJECT_NUMBER'.")
    print("Also, ensure the Google Cloud Retail API is enabled for your project.")