google-cloud-retail-v2 0.3.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd84ee8b8cb6402aa583b3e9c4547a5fc1a289e166e65545ddb713576f1d880c
-  data.tar.gz: fea5c7cc85fec5aeee31730266cf8c99dd8fe5b3ee52963e58ecde4002291149
+  metadata.gz: b07d919181d8706e180a703f7cecd52fb464e69cfa4fd0ede43cf5b351a0e88e
+  data.tar.gz: 04bee385524f62ef1d40025669309f5d094b228e5ec833805baad6bacd1d2365
 SHA512:
-  metadata.gz: fbc4ce6666a59e6c4cb03e2d912f030bcbdad8928bc89150f28e06edcd98b5517a7e414a9b22a05168ea79f3f8eab96c70afb7510e20b42cb05aecd749c3b778
-  data.tar.gz: 542f628eeccc024f038b23ec2540117fdd0b1810cfa64ff0400fd0bde837c8ddcacbcec9ff5ff4670e86d297dd65149b5ad3c217a6cacd49569501ccbcbc32d0
+  metadata.gz: f41c60eb5f15c54e8f4ac41a94be47f87013ece357de71a7699a3b6a8af7ddb0f5d955092c446df68c06ea1aad20d162aca6aa5785680ecf619af408e494a284
+  data.tar.gz: 536710d9c52c19162bc9a2effd65d2f7861b1b81a50ad3c659a4b1d4034a9acbfbcdb4a205a4de36df434a338ceb076ee68de0566cc29d259449568d876c557f

data/AUTHENTICATION.md

@@ -66,11 +66,11 @@ The environment variables that google-cloud-retail-v2
 checks for credentials are configured on the service Credentials class (such as
 {::Google::Cloud::Retail::V2::CatalogService::Credentials}):
 
-1. `RETAIL_CREDENTIALS` - Path to JSON file, or JSON contents
-2. `RETAIL_KEYFILE` - Path to JSON file, or JSON contents
-3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
-4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
-5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+* `RETAIL_CREDENTIALS` - Path to JSON file, or JSON contents
+* `RETAIL_KEYFILE` - Path to JSON file, or JSON contents
+* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
 
 ```ruby
 require "google/cloud/retail/v2"
@@ -82,8 +82,8 @@ client = ::Google::Cloud::Retail::V2::CatalogService::Client.new
 
 ### Configuration
 
-The **Credentials JSON** can be configured instead of placing them in
-environment variables. Either on an individual client initialization:
+The path to the **Credentials JSON** file can be configured instead of storing
+it in an environment variable. Either on an individual client initialization:
 
 ```ruby
 require "google/cloud/retail/v2"
@@ -93,7 +93,7 @@ client = ::Google::Cloud::Retail::V2::CatalogService::Client.new do |config|
 end
 ```
 
-Or configured globally for all clients:
+Or globally for all clients:
 
 ```ruby
 require "google/cloud/retail/v2"

data/README.md

@@ -33,7 +33,7 @@ In order to use this library, you first need to go through the following steps:
 require "google/cloud/retail/v2"
 
 client = ::Google::Cloud::Retail::V2::CatalogService::Client.new
-request = my_create_request
+request = ::Google::Cloud::Retail::V2::ListCatalogsRequest.new # (request fields as keyword arguments...)
 response = client.list_catalogs request
 ```
 

data/lib/google/cloud/retail/v2.rb

@@ -17,8 +17,10 @@
 # Auto-generated by gapic-generator-ruby. DO NOT EDIT!
 
 require "google/cloud/retail/v2/catalog_service"
+require "google/cloud/retail/v2/completion_service"
 require "google/cloud/retail/v2/prediction_service"
 require "google/cloud/retail/v2/product_service"
+require "google/cloud/retail/v2/search_service"
 require "google/cloud/retail/v2/user_event_service"
 require "google/cloud/retail/v2/version"
 

data/lib/google/cloud/retail/v2/catalog_pb.rb

@@ -6,6 +6,8 @@ require 'google/protobuf'
 require 'google/api/annotations_pb'
 require 'google/api/field_behavior_pb'
 require 'google/api/resource_pb'
+require 'google/cloud/retail/v2/common_pb'
+require 'google/cloud/retail/v2/import_config_pb'
 Google::Protobuf::DescriptorPool.generated_pool.build do
   add_file("google/cloud/retail/v2/catalog.proto", :syntax => :proto3) do
     add_message "google.cloud.retail.v2.ProductLevelConfig" do

data/lib/google/cloud/retail/v2/catalog_service/client.rb

@@ -41,13 +41,12 @@ module Google
             # See {::Google::Cloud::Retail::V2::CatalogService::Client::Configuration}
             # for a description of the configuration fields.
             #
-            # ## Example
+            # @example
             #
-            # To modify the configuration for all CatalogService clients:
-            #
-            #     ::Google::Cloud::Retail::V2::CatalogService::Client.configure do |config|
-            #       config.timeout = 10.0
-            #     end
+            #   # Modify the configuration for all CatalogService clients
+            #   ::Google::Cloud::Retail::V2::CatalogService::Client.configure do |config|
+            #     config.timeout = 10.0
+            #   end
             #
             # @yield [config] Configure the Client client.
             # @yieldparam config [Client::Configuration]
@@ -67,10 +66,7 @@ module Google
 
                 default_config.timeout = 60.0
                 default_config.retry_policy = {
-                  initial_delay: 0.1,
-                max_delay: 60.0,
-                multiplier: 1.3,
-                retry_codes: [14, 4]
+                  initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [14, 4]
                 }
 
                 default_config
@@ -102,19 +98,15 @@ module Google
             ##
             # Create a new CatalogService client object.
             #
-            # ## Examples
-            #
-            # To create a new CatalogService client with the default
-            # configuration:
+            # @example
             #
-            #     client = ::Google::Cloud::Retail::V2::CatalogService::Client.new
+            #   # Create a client using the default configuration
+            #   client = ::Google::Cloud::Retail::V2::CatalogService::Client.new
             #
-            # To create a new CatalogService client with a custom
-            # configuration:
-            #
-            #     client = ::Google::Cloud::Retail::V2::CatalogService::Client.new do |config|
-            #       config.timeout = 10.0
-            #     end
+            #   # Create a client using a custom configuration
+            #   client = ::Google::Cloud::Retail::V2::CatalogService::Client.new do |config|
+            #     config.timeout = 10.0
+            #   end
             #
             # @yield [config] Configure the CatalogService client.
             # @yieldparam config [Client::Configuration]
@@ -134,14 +126,13 @@ module Google
 
               # Create credentials
               credentials = @config.credentials
-              # Use self-signed JWT if the scope and endpoint are unchanged from default,
+              # Use self-signed JWT if the endpoint is unchanged from default,
               # but only if the default endpoint does not have a region prefix.
-              enable_self_signed_jwt = @config.scope == Client.configure.scope &&
-                                       @config.endpoint == Client.configure.endpoint &&
+              enable_self_signed_jwt = @config.endpoint == Client.configure.endpoint &&
                                        !@config.endpoint.split(".").first.include?("-")
               credentials ||= Credentials.default scope: @config.scope,
                                                   enable_self_signed_jwt: enable_self_signed_jwt
-              if credentials.is_a?(String) || credentials.is_a?(Hash)
+              if credentials.is_a?(::String) || credentials.is_a?(::Hash)
                 credentials = Credentials.new credentials, scope: @config.scope
               end
               @quota_project_id = @config.quota_project
@@ -236,7 +227,9 @@ module Google
               options.apply_defaults timeout:      @config.rpcs.list_catalogs.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.list_catalogs.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @catalog_service_stub.call_rpc :list_catalogs, request, options: options do |response, operation|
@@ -277,10 +270,7 @@ module Google
             #     a NOT_FOUND error is returned.
             #   @param update_mask [::Google::Protobuf::FieldMask, ::Hash]
             #     Indicates which fields in the provided
-            #     {::Google::Cloud::Retail::V2::Catalog Catalog} to update. If not set, will only
-            #     update the
-            #     {::Google::Cloud::Retail::V2::Catalog#product_level_config Catalog.product_level_config}
-            #     field, which is also the only currently supported field to update.
+            #     {::Google::Cloud::Retail::V2::Catalog Catalog} to update.
             #
             #     If an unsupported or unknown field is provided, an INVALID_ARGUMENT error
             #     is returned.
@@ -319,7 +309,9 @@ module Google
               options.apply_defaults timeout:      @config.rpcs.update_catalog.timeout,
                                      metadata:     metadata,
                                      retry_policy: @config.rpcs.update_catalog.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
                                      retry_policy: @config.retry_policy
 
               @catalog_service_stub.call_rpc :update_catalog, request, options: options do |response, operation|
@@ -330,6 +322,198 @@ module Google
               raise ::Google::Cloud::Error.from_error(e)
             end
 
+            ##
+            # Set a specified branch id as default branch. API methods such as
+            # {::Google::Cloud::Retail::V2::SearchService::Client#search SearchService.Search},
+            # {::Google::Cloud::Retail::V2::ProductService::Client#get_product ProductService.GetProduct},
+            # {::Google::Cloud::Retail::V2::ProductService::Client#list_products 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
+            # {::Google::Cloud::Retail::V2::SearchRequest#branch SearchRequest.branch} to
+            # `projects/*/locations/*/catalogs/*/branches/default_branch` is equivalent
+            # to setting
+            # {::Google::Cloud::Retail::V2::SearchRequest#branch 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 {::Google::Cloud::Retail::V2::SearchRequest#branch 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}.
+            #
+            # This feature is only available for users who have Retail Search enabled.
+            # Contact Retail Support (retail-search-support@google.com) if you are
+            # interested in using Retail Search.
+            #
+            # @overload set_default_branch(request, options = nil)
+            #   Pass arguments to `set_default_branch` via a request object, either of type
+            #   {::Google::Cloud::Retail::V2::SetDefaultBranchRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Cloud::Retail::V2::SetDefaultBranchRequest, ::Hash]
+            #     A request object representing the call parameters. Required. To specify no
+            #     parameters, or to keep all the default parameter values, pass an empty Hash.
+            #   @param options [::Gapic::CallOptions, ::Hash]
+            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+            #
+            # @overload set_default_branch(catalog: nil, branch_id: nil, note: nil)
+            #   Pass arguments to `set_default_branch` via keyword arguments. Note that at
+            #   least one keyword argument is required. To specify no parameters, or to keep all
+            #   the default parameter values, pass an empty Hash as a request object (see above).
+            #
+            #   @param catalog [::String]
+            #     Full resource name of the catalog, such as
+            #     `projects/*/locations/global/catalogs/default_catalog`.
+            #   @param branch_id [::String]
+            #     The final component of the resource name of a branch.
+            #
+            #     This field must be one of "0", "1" or "2". Otherwise, an INVALID_ARGUMENT
+            #     error is returned.
+            #   @param note [::String]
+            #     Some note on this request, this can be retrieved by
+            #     {::Google::Cloud::Retail::V2::CatalogService::Client#get_default_branch CatalogService.GetDefaultBranch}
+            #     before next valid default branch set occurs.
+            #
+            #     This field must be a UTF-8 encoded string with a length limit of 1,000
+            #     characters. Otherwise, an INVALID_ARGUMENT error is returned.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Google::Protobuf::Empty]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Google::Protobuf::Empty]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            def set_default_branch request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::Retail::V2::SetDefaultBranchRequest
+
+              # Converts hash and nil to an options object
+              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+              # Customize the options with defaults
+              metadata = @config.rpcs.set_default_branch.metadata.to_h
+
+              # Set x-goog-api-client and x-goog-user-project headers
+              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+                lib_name: @config.lib_name, lib_version: @config.lib_version,
+                gapic_version: ::Google::Cloud::Retail::V2::VERSION
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {
+                "catalog" => request.catalog
+              }
+              request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
+              metadata[:"x-goog-request-params"] ||= request_params_header
+
+              options.apply_defaults timeout:      @config.rpcs.set_default_branch.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.set_default_branch.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @catalog_service_stub.call_rpc :set_default_branch, request, options: options do |response, operation|
+                yield response, operation if block_given?
+                return response
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
+            ##
+            # Get which branch is currently default branch set by
+            # {::Google::Cloud::Retail::V2::CatalogService::Client#set_default_branch CatalogService.SetDefaultBranch}
+            # method under a specified parent catalog.
+            #
+            # This feature is only available for users who have Retail Search enabled.
+            # Contact Retail Support (retail-search-support@google.com) if you are
+            # interested in using Retail Search.
+            #
+            # @overload get_default_branch(request, options = nil)
+            #   Pass arguments to `get_default_branch` via a request object, either of type
+            #   {::Google::Cloud::Retail::V2::GetDefaultBranchRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Cloud::Retail::V2::GetDefaultBranchRequest, ::Hash]
+            #     A request object representing the call parameters. Required. To specify no
+            #     parameters, or to keep all the default parameter values, pass an empty Hash.
+            #   @param options [::Gapic::CallOptions, ::Hash]
+            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+            #
+            # @overload get_default_branch(catalog: nil)
+            #   Pass arguments to `get_default_branch` via keyword arguments. Note that at
+            #   least one keyword argument is required. To specify no parameters, or to keep all
+            #   the default parameter values, pass an empty Hash as a request object (see above).
+            #
+            #   @param catalog [::String]
+            #     The parent catalog resource name, such as
+            #     `projects/*/locations/global/catalogs/default_catalog`.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Google::Cloud::Retail::V2::GetDefaultBranchResponse]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Google::Cloud::Retail::V2::GetDefaultBranchResponse]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            def get_default_branch request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::Retail::V2::GetDefaultBranchRequest
+
+              # Converts hash and nil to an options object
+              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+              # Customize the options with defaults
+              metadata = @config.rpcs.get_default_branch.metadata.to_h
+
+              # Set x-goog-api-client and x-goog-user-project headers
+              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+                lib_name: @config.lib_name, lib_version: @config.lib_version,
+                gapic_version: ::Google::Cloud::Retail::V2::VERSION
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {
+                "catalog" => request.catalog
+              }
+              request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
+              metadata[:"x-goog-request-params"] ||= request_params_header
+
+              options.apply_defaults timeout:      @config.rpcs.get_default_branch.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.get_default_branch.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @catalog_service_stub.call_rpc :get_default_branch, request, options: options do |response, operation|
+                yield response, operation if block_given?
+                return response
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
             ##
             # Configuration class for the CatalogService API.
             #
@@ -343,22 +527,21 @@ module Google
             # Configuration can be applied globally to all clients, or to a single client
             # on construction.
             #
-            # # Examples
-            #
-            # To modify the global config, setting the timeout for list_catalogs
-            # to 20 seconds, and all remaining timeouts to 10 seconds:
-            #
-            #     ::Google::Cloud::Retail::V2::CatalogService::Client.configure do |config|
-            #       config.timeout = 10.0
-            #       config.rpcs.list_catalogs.timeout = 20.0
-            #     end
+            # @example
             #
-            # To apply the above configuration only to a new client:
+            #   # Modify the global config, setting the timeout for
+            #   # list_catalogs to 20 seconds,
+            #   # and all remaining timeouts to 10 seconds.
+            #   ::Google::Cloud::Retail::V2::CatalogService::Client.configure do |config|
+            #     config.timeout = 10.0
+            #     config.rpcs.list_catalogs.timeout = 20.0
+            #   end
             #
-            #     client = ::Google::Cloud::Retail::V2::CatalogService::Client.new do |config|
-            #       config.timeout = 10.0
-            #       config.rpcs.list_catalogs.timeout = 20.0
-            #     end
+            #   # Apply the above configuration only to a new client.
+            #   client = ::Google::Cloud::Retail::V2::CatalogService::Client.new do |config|
+            #     config.timeout = 10.0
+            #     config.rpcs.list_catalogs.timeout = 20.0
+            #   end
             #
             # @!attribute [rw] endpoint
             #   The hostname or hostname:port of the service endpoint.
@@ -476,6 +659,16 @@ module Google
                 # @return [::Gapic::Config::Method]
                 #
                 attr_reader :update_catalog
+                ##
+                # RPC-specific configuration for `set_default_branch`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :set_default_branch
+                ##
+                # RPC-specific configuration for `get_default_branch`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :get_default_branch
 
                 # @private
                 def initialize parent_rpcs = nil
@@ -483,6 +676,10 @@ module Google
                   @list_catalogs = ::Gapic::Config::Method.new list_catalogs_config
                   update_catalog_config = parent_rpcs.update_catalog if parent_rpcs.respond_to? :update_catalog
                   @update_catalog = ::Gapic::Config::Method.new update_catalog_config
+                  set_default_branch_config = parent_rpcs.set_default_branch if parent_rpcs.respond_to? :set_default_branch
+                  @set_default_branch = ::Gapic::Config::Method.new set_default_branch_config
+                  get_default_branch_config = parent_rpcs.get_default_branch if parent_rpcs.respond_to? :get_default_branch
+                  @get_default_branch = ::Gapic::Config::Method.new get_default_branch_config
 
                   yield self if block_given?
                 end

data/lib/google/cloud/retail/v2/catalog_service/paths.rb

@@ -24,6 +24,27 @@ module Google
         module CatalogService
           # Path helper methods for the CatalogService API.
           module Paths
+            ##
+            # Create a fully-qualified Branch resource string.
+            #
+            # The resource will be in the following format:
+            #
+            # `projects/{project}/locations/{location}/catalogs/{catalog}/branches/{branch}`
+            #
+            # @param project [String]
+            # @param location [String]
+            # @param catalog [String]
+            # @param branch [String]
+            #
+            # @return [::String]
+            def branch_path project:, location:, catalog:, branch:
+              raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+              raise ::ArgumentError, "location cannot contain /" if location.to_s.include? "/"
+              raise ::ArgumentError, "catalog cannot contain /" if catalog.to_s.include? "/"
+
+              "projects/#{project}/locations/#{location}/catalogs/#{catalog}/branches/#{branch}"
+            end
+
             ##
             # Create a fully-qualified Catalog resource string.
             #