Class CatalogServiceClient (2.16.0)

Service for managing catalog configuration.

Equality

Instances of this class created via copy-construction or copy-assignment always compare equal. Instances created with equal std::shared_ptr<*Connection> objects compare equal. Objects that compare equal share the same underlying resources.

Performance

Creating a new instance of this class is a relatively expensive operation, new objects establish new connections to the service. In contrast, copy-construction, move-construction, and the corresponding assignment operations are relatively efficient as the copies share all underlying resources.

Thread Safety

Concurrent access to different instances of this class, even if they compare equal, is guaranteed to work. Two or more threads operating on the same instance of this class is not guaranteed to work. Since copy-construction and move-construction is a relatively efficient operation, consider using such a copy when using this class from multiple threads.

Constructors

CatalogServiceClient(CatalogServiceClient const &)

Copy and move support

Parameter
Name Description
CatalogServiceClient const &

CatalogServiceClient(CatalogServiceClient &&)

Copy and move support

Parameter
Name Description
CatalogServiceClient &&

CatalogServiceClient(std::shared_ptr< CatalogServiceConnection >, Options)

Parameters
Name Description
connection std::shared_ptr< CatalogServiceConnection >
opts Options

Operators

operator=(CatalogServiceClient const &)

Copy and move support

Parameter
Name Description
CatalogServiceClient const &
Returns
Type Description
CatalogServiceClient &

operator=(CatalogServiceClient &&)

Copy and move support

Parameter
Name Description
CatalogServiceClient &&
Returns
Type Description
CatalogServiceClient &

Functions

ListCatalogs(std::string const &, Options)

Lists all the Catalogs associated with the project.

Parameters
Name Description
parent std::string const &

Required. The account resource name with an associated location.
If the caller does not have permission to list Catalogs under this location, regardless of whether or not this location exists, a PERMISSION_DENIED error is returned.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StreamRange< google::cloud::retail::v2::Catalog >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.cloud.retail.v2.Catalog, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

ListCatalogs(google::cloud::retail::v2::ListCatalogsRequest, Options)

Lists all the Catalogs associated with the project.

Parameters
Name Description
request google::cloud::retail::v2::ListCatalogsRequest

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.ListCatalogsRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StreamRange< google::cloud::retail::v2::Catalog >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.cloud.retail.v2.Catalog, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

UpdateCatalog(google::cloud::retail::v2::Catalog const &, google::protobuf::FieldMask const &, Options)

Updates the Catalogs.

Parameters
Name Description
catalog google::cloud::retail::v2::Catalog const &

Required. The Catalog to update.
If the caller does not have permission to update the Catalog, regardless of whether or not it exists, a PERMISSION_DENIED error is returned.
If the Catalog to update does not exist, a NOT_FOUND error is returned.

update_mask google::protobuf::FieldMask const &

Indicates which fields in the provided Catalog to update.
If an unsupported or unknown field is provided, an INVALID_ARGUMENT error is returned.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::Catalog >

the result of the RPC. The response message type (google.cloud.retail.v2.Catalog) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateCatalog(google::cloud::retail::v2::UpdateCatalogRequest const &, Options)

Updates the Catalogs.

Parameters
Name Description
request google::cloud::retail::v2::UpdateCatalogRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.UpdateCatalogRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::Catalog >

the result of the RPC. The response message type (google.cloud.retail.v2.Catalog) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

SetDefaultBranch(std::string const &, Options)

Set a specified branch id as default branch.

API methods such as [SearchService.Search][google.cloud.retail.v2.SearchService.Search], [ProductService.GetProduct][google.cloud.retail.v2.ProductService.GetProduct], [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts] will treat requests using "default_branch" to the actual branch id set as default.

For example, if projects/*/locations/*/catalogs/*/branches/1 is set as default, setting [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to projects/*/locations/*/catalogs/*/branches/default_branch is equivalent to setting [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to projects/*/locations/*/catalogs/*/branches/1.

Using multiple branches can be useful when developers would like to have a staging branch to test and verify for future usage. When it becomes ready, developers switch on the staging branch using this API while keeping using projects/*/locations/*/catalogs/*/branches/default_branch as [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to route the traffic to this staging branch.

CAUTION: If you have live predict/search traffic, switching the default branch could potentially cause outages if the ID space of the new branch is very different from the old one.

More specifically:

  • PredictionService will only return product IDs from branch {newBranch}.
  • SearchService will only return product IDs from branch {newBranch} (if branch is not explicitly set).
  • UserEventService will only join events with products from branch {newBranch}.
Parameters
Name Description
catalog std::string const &

Full resource name of the catalog, such as projects/*/locations/global/catalogs/default_catalog.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
Status

a Status object. If the request failed, the status contains the details of the failure.

SetDefaultBranch(google::cloud::retail::v2::SetDefaultBranchRequest const &, Options)

Set a specified branch id as default branch.

API methods such as [SearchService.Search][google.cloud.retail.v2.SearchService.Search], [ProductService.GetProduct][google.cloud.retail.v2.ProductService.GetProduct], [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts] will treat requests using "default_branch" to the actual branch id set as default.

For example, if projects/*/locations/*/catalogs/*/branches/1 is set as default, setting [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to projects/*/locations/*/catalogs/*/branches/default_branch is equivalent to setting [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to projects/*/locations/*/catalogs/*/branches/1.

Using multiple branches can be useful when developers would like to have a staging branch to test and verify for future usage. When it becomes ready, developers switch on the staging branch using this API while keeping using projects/*/locations/*/catalogs/*/branches/default_branch as [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to route the traffic to this staging branch.

CAUTION: If you have live predict/search traffic, switching the default branch could potentially cause outages if the ID space of the new branch is very different from the old one.

More specifically:

  • PredictionService will only return product IDs from branch {newBranch}.
  • SearchService will only return product IDs from branch {newBranch} (if branch is not explicitly set).
  • UserEventService will only join events with products from branch {newBranch}.
Parameters
Name Description
request google::cloud::retail::v2::SetDefaultBranchRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.SetDefaultBranchRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
Status

a Status object. If the request failed, the status contains the details of the failure.

GetDefaultBranch(std::string const &, Options)

Get which branch is currently default branch set by CatalogService.SetDefaultBranch method under a specified parent catalog.

Parameters
Name Description
catalog std::string const &

The parent catalog resource name, such as projects/*/locations/global/catalogs/default_catalog.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::GetDefaultBranchResponse >

the result of the RPC. The response message type (google.cloud.retail.v2.GetDefaultBranchResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetDefaultBranch(google::cloud::retail::v2::GetDefaultBranchRequest const &, Options)

Get which branch is currently default branch set by CatalogService.SetDefaultBranch method under a specified parent catalog.

Parameters
Name Description
request google::cloud::retail::v2::GetDefaultBranchRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.GetDefaultBranchRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::GetDefaultBranchResponse >

the result of the RPC. The response message type (google.cloud.retail.v2.GetDefaultBranchResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetCompletionConfig(std::string const &, Options)

Gets a CompletionConfig.

Parameters
Name Description
name std::string const &

Required. Full CompletionConfig resource name. Format: projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/completionConfig
opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::CompletionConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.CompletionConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetCompletionConfig(google::cloud::retail::v2::GetCompletionConfigRequest const &, Options)

Gets a CompletionConfig.

Parameters
Name Description
request google::cloud::retail::v2::GetCompletionConfigRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.GetCompletionConfigRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::CompletionConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.CompletionConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateCompletionConfig(google::cloud::retail::v2::CompletionConfig const &, google::protobuf::FieldMask const &, Options)

Updates the CompletionConfigs.

Parameters
Name Description
completion_config google::cloud::retail::v2::CompletionConfig const &

Required. The CompletionConfig to update.
If the caller does not have permission to update the CompletionConfig, then a PERMISSION_DENIED error is returned.
If the CompletionConfig to update does not exist, a NOT_FOUND error is returned.

update_mask google::protobuf::FieldMask const &

Indicates which fields in the provided CompletionConfig to update. The following are the only supported fields:

  • [CompletionConfig.matching_order][google.cloud.retail.v2.CompletionConfig.matching_order]
  • [CompletionConfig.max_suggestions][google.cloud.retail.v2.CompletionConfig.max_suggestions]
  • [CompletionConfig.min_prefix_length][google.cloud.retail.v2.CompletionConfig.min_prefix_length]
  • [CompletionConfig.auto_learning][google.cloud.retail.v2.CompletionConfig.auto_learning]
    If not set, all supported fields are updated.
opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::CompletionConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.CompletionConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateCompletionConfig(google::cloud::retail::v2::UpdateCompletionConfigRequest const &, Options)

Updates the CompletionConfigs.

Parameters
Name Description
request google::cloud::retail::v2::UpdateCompletionConfigRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.UpdateCompletionConfigRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::CompletionConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.CompletionConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetAttributesConfig(std::string const &, Options)

Gets an AttributesConfig.

Parameters
Name Description
name std::string const &

Required. Full AttributesConfig resource name. Format: projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig
opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetAttributesConfig(google::cloud::retail::v2::GetAttributesConfigRequest const &, Options)

Gets an AttributesConfig.

Parameters
Name Description
request google::cloud::retail::v2::GetAttributesConfigRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.GetAttributesConfigRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateAttributesConfig(google::cloud::retail::v2::AttributesConfig const &, google::protobuf::FieldMask const &, Options)

Updates the AttributesConfig.

The catalog attributes in the request will be updated in the catalog, or inserted if they do not exist. Existing catalog attributes not included in the request will remain unchanged. Attributes that are assigned to products, but do not exist at the catalog level, are always included in the response. The product attribute is assigned default values for missing catalog attribute fields, e.g., searchable and dynamic facetable options.

Parameters
Name Description
attributes_config google::cloud::retail::v2::AttributesConfig const &

Required. The AttributesConfig to update.

update_mask google::protobuf::FieldMask const &

Indicates which fields in the provided AttributesConfig to update. The following is the only supported field:

  • [AttributesConfig.catalog_attributes][google.cloud.retail.v2.AttributesConfig.catalog_attributes]
    If not set, all supported fields are updated.
opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateAttributesConfig(google::cloud::retail::v2::UpdateAttributesConfigRequest const &, Options)

Updates the AttributesConfig.

The catalog attributes in the request will be updated in the catalog, or inserted if they do not exist. Existing catalog attributes not included in the request will remain unchanged. Attributes that are assigned to products, but do not exist at the catalog level, are always included in the response. The product attribute is assigned default values for missing catalog attribute fields, e.g., searchable and dynamic facetable options.

Parameters
Name Description
request google::cloud::retail::v2::UpdateAttributesConfigRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.UpdateAttributesConfigRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

AddCatalogAttribute(google::cloud::retail::v2::AddCatalogAttributeRequest const &, Options)

Adds the specified CatalogAttribute to the AttributesConfig.

If the CatalogAttribute to add already exists, an ALREADY_EXISTS error is returned.

Parameters
Name Description
request google::cloud::retail::v2::AddCatalogAttributeRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.AddCatalogAttributeRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

RemoveCatalogAttribute(google::cloud::retail::v2::RemoveCatalogAttributeRequest const &, Options)

Removes the specified CatalogAttribute from the AttributesConfig.

If the CatalogAttribute to remove does not exist, a NOT_FOUND error is returned.

Parameters
Name Description
request google::cloud::retail::v2::RemoveCatalogAttributeRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.RemoveCatalogAttributeRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

ReplaceCatalogAttribute(google::cloud::retail::v2::ReplaceCatalogAttributeRequest const &, Options)

Replaces the specified CatalogAttribute in the AttributesConfig by updating the catalog attribute with the same CatalogAttribute.key.

If the CatalogAttribute to replace does not exist, a NOT_FOUND error is returned.

Parameters
Name Description
request google::cloud::retail::v2::ReplaceCatalogAttributeRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.retail.v2.ReplaceCatalogAttributeRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

Optional. Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::cloud::retail::v2::AttributesConfig >

the result of the RPC. The response message type (google.cloud.retail.v2.AttributesConfig) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.