google-cloud-discovery_engine-v1beta 0.27.0 → 0.28.0

data/lib/google/cloud/discovery_engine/v1beta/document_service/credentials.rb

@@ -26,7 +26,9 @@ module Google
           # Credentials for the DocumentService API.
           class Credentials < ::Google::Auth::Credentials
             self.scope = [
-              "https://www.googleapis.com/auth/cloud-platform"
+              "https://www.googleapis.com/auth/cloud-platform",
+              "https://www.googleapis.com/auth/discoveryengine.readwrite",
+              "https://www.googleapis.com/auth/discoveryengine.serving.readwrite"
             ]
             self.env_vars = [
               "GOOGLE_CLOUD_CREDENTIALS",

data/lib/google/cloud/discovery_engine/v1beta/document_service/rest/client.rb

@@ -454,7 +454,7 @@ module Google
               #     Otherwise, an `ALREADY_EXISTS` error is returned.
               #
               #     This field must conform to [RFC-1034](https://tools.ietf.org/html/rfc1034)
-              #     standard with a length limit of 63 characters. Otherwise, an
+              #     standard with a length limit of 128 characters. Otherwise, an
               #     `INVALID_ARGUMENT` error is returned.
               # @yield [result, operation] Access the result along with the TransportOperation object
               # @yieldparam result [::Google::Cloud::DiscoveryEngine::V1beta::Document]
@@ -714,7 +714,7 @@ module Google
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
               #
-              # @overload import_documents(inline_source: nil, gcs_source: nil, bigquery_source: nil, fhir_store_source: nil, spanner_source: nil, cloud_sql_source: nil, firestore_source: nil, alloy_db_source: nil, bigtable_source: nil, parent: nil, error_config: nil, reconciliation_mode: nil, update_mask: nil, auto_generate_ids: nil, id_field: nil)
+              # @overload import_documents(inline_source: nil, gcs_source: nil, bigquery_source: nil, fhir_store_source: nil, spanner_source: nil, cloud_sql_source: nil, firestore_source: nil, alloy_db_source: nil, bigtable_source: nil, parent: nil, error_config: nil, reconciliation_mode: nil, update_mask: nil, auto_generate_ids: nil, id_field: nil, force_refresh_content: nil)
               #   Pass arguments to `import_documents` 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).
@@ -827,8 +827,13 @@ module Google
               #     must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
               #     * {::Google::Cloud::DiscoveryEngine::V1beta::SpannerSource SpannerSource}.
               #     * {::Google::Cloud::DiscoveryEngine::V1beta::CloudSqlSource CloudSqlSource}.
-              #     * {::Google::Cloud::DiscoveryEngine::V1beta::FirestoreSource FirestoreSource}.
               #     * {::Google::Cloud::DiscoveryEngine::V1beta::BigtableSource BigtableSource}.
+              #   @param force_refresh_content [::Boolean]
+              #     Optional. Whether to force refresh the unstructured content of the
+              #     documents.
+              #
+              #     If set to `true`, the content part of the documents will be refreshed
+              #     regardless of the update status of the referencing content.
               # @yield [result, operation] Access the result along with the TransportOperation object
               # @yieldparam result [::Gapic::Operation]
               # @yieldparam operation [::Gapic::Rest::TransportOperation]

data/lib/google/cloud/discovery_engine/v1beta/document_service/rest/operations.rb

@@ -929,6 +929,13 @@ module Google
                                                             ["name", %r{^projects/[^/]+/locations/[^/]+/dataStores/[^/]+/?$}, false]
                                                           ]
                                                         )
+                                                        .with_bindings(
+                                                          uri_method: :get,
+                                                          uri_template: "/v1beta/{name}/operations",
+                                                          matches: [
+                                                            ["name", %r{^projects/[^/]+/locations/[^/]+/identityMappingStores/[^/]+/?$}, false]
+                                                          ]
+                                                        )
                                                         .with_bindings(
                                                           uri_method: :get,
                                                           uri_template: "/v1beta/{name}/operations",
@@ -1006,6 +1013,13 @@ module Google
                                                             ["name", %r{^projects/[^/]+/locations/[^/]+/collections/[^/]+/dataStores/[^/]+/siteSearchEngine/targetSites/operations/[^/]+/?$}, false]
                                                           ]
                                                         )
+                                                        .with_bindings(
+                                                          uri_method: :get,
+                                                          uri_template: "/v1beta/{name}",
+                                                          matches: [
+                                                            ["name", %r{^projects/[^/]+/locations/[^/]+/collections/[^/]+/engines/[^/]+/assistants/[^/]+/agents/[^/]+/operations/[^/]+/?$}, false]
+                                                          ]
+                                                        )
                                                         .with_bindings(
                                                           uri_method: :get,
                                                           uri_template: "/v1beta/{name}",
@@ -1048,6 +1062,13 @@ module Google
                                                             ["name", %r{^projects/[^/]+/locations/[^/]+/evaluations/[^/]+/operations/[^/]+/?$}, false]
                                                           ]
                                                         )
+                                                        .with_bindings(
+                                                          uri_method: :get,
+                                                          uri_template: "/v1beta/{name}",
+                                                          matches: [
+                                                            ["name", %r{^projects/[^/]+/locations/[^/]+/identityMappingStores/[^/]+/operations/[^/]+/?$}, false]
+                                                          ]
+                                                        )
                                                         .with_bindings(
                                                           uri_method: :get,
                                                           uri_template: "/v1beta/{name}",

data/lib/google/cloud/discovery_engine/v1beta/engine_service/client.rb

@@ -215,7 +215,7 @@ module Google
             # Service calls
 
             ##
-            # Creates a {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
+            # Creates an {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
             #
             # @overload create_engine(request, options = nil)
             #   Pass arguments to `create_engine` via a request object, either of type
@@ -322,7 +322,7 @@ module Google
             end
 
             ##
-            # Deletes a {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
+            # Deletes an {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
             #
             # @overload delete_engine(request, options = nil)
             #   Pass arguments to `delete_engine` via a request object, either of type
@@ -524,7 +524,7 @@ module Google
             end
 
             ##
-            # Gets a {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
+            # Gets an {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
             #
             # @overload get_engine(request, options = nil)
             #   Pass arguments to `get_engine` via a request object, either of type
@@ -711,7 +711,8 @@ module Google
             end
 
             ##
-            # Pauses the training of an existing engine. Only applicable if
+            # Pauses the training of an existing
+            # {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}. Only applicable if
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType SolutionType} is
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType::SOLUTION_TYPE_RECOMMENDATION SOLUTION_TYPE_RECOMMENDATION}.
             #
@@ -800,7 +801,8 @@ module Google
             end
 
             ##
-            # Resumes the training of an existing engine. Only applicable if
+            # Resumes the training of an existing
+            # {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}. Only applicable if
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType SolutionType} is
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType::SOLUTION_TYPE_RECOMMENDATION SOLUTION_TYPE_RECOMMENDATION}.
             #
@@ -889,7 +891,8 @@ module Google
             end
 
             ##
-            # Tunes an existing engine. Only applicable if
+            # Tunes an existing {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}.
+            # Only applicable if
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType SolutionType} is
             # {::Google::Cloud::DiscoveryEngine::V1beta::SolutionType::SOLUTION_TYPE_RECOMMENDATION SOLUTION_TYPE_RECOMMENDATION}.
             #
@@ -986,6 +989,207 @@ module Google
               raise ::Google::Cloud::Error.from_error(e)
             end
 
+            ##
+            # Gets the IAM access control policy for an
+            # {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}. A `NOT_FOUND` error
+            # is returned if the resource does not exist. An empty policy is returned if
+            # the resource exists but does not have a policy set on it.
+            #
+            # @overload get_iam_policy(request, options = nil)
+            #   Pass arguments to `get_iam_policy` via a request object, either of type
+            #   {::Google::Iam::V1::GetIamPolicyRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Iam::V1::GetIamPolicyRequest, ::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_iam_policy(resource: nil, options: nil)
+            #   Pass arguments to `get_iam_policy` 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 resource [::String]
+            #     REQUIRED: The resource for which the policy is being requested.
+            #     See the operation documentation for the appropriate value for this field.
+            #   @param options [::Google::Iam::V1::GetPolicyOptions, ::Hash]
+            #     OPTIONAL: A `GetPolicyOptions` object for specifying options to
+            #     `GetIamPolicy`.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Google::Iam::V1::Policy]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Google::Iam::V1::Policy]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            # @example Basic example
+            #   require "google/cloud/discovery_engine/v1beta"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::DiscoveryEngine::V1beta::EngineService::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Iam::V1::GetIamPolicyRequest.new
+            #
+            #   # Call the get_iam_policy method.
+            #   result = client.get_iam_policy request
+            #
+            #   # The returned object is of type Google::Iam::V1::Policy.
+            #   p result
+            #
+            def get_iam_policy request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Iam::V1::GetIamPolicyRequest
+
+              # 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_iam_policy.metadata.to_h
+
+              # Set x-goog-api-client, x-goog-user-project and x-goog-api-version 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::DiscoveryEngine::V1beta::VERSION
+              metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {}
+              if request.resource
+                header_params["resource"] = request.resource
+              end
+
+              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_iam_policy.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.get_iam_policy.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @engine_service_stub.call_rpc :get_iam_policy, request, options: options do |response, operation|
+                yield response, operation if block_given?
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
+            ##
+            # Sets the IAM access control policy for an
+            # {::Google::Cloud::DiscoveryEngine::V1beta::Engine Engine}. A `NOT_FOUND` error
+            # is returned if the resource does not exist.
+            #
+            # **Important:** When setting a policy directly on an Engine resource,
+            # the only recommended roles in the bindings are:
+            # `roles/discoveryengine.admin`,
+            # `roles/discoveryengine.agentspaceAdmin`,
+            # `roles/discoveryengine.user`,
+            # `roles/discoveryengine.agentspaceUser`,
+            # `roles/discoveryengine.viewer`,
+            # `roles/discoveryengine.agentspaceViewer`.
+            # Attempting to grant any other role will result in a warning in logging.
+            #
+            # @overload set_iam_policy(request, options = nil)
+            #   Pass arguments to `set_iam_policy` via a request object, either of type
+            #   {::Google::Iam::V1::SetIamPolicyRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Iam::V1::SetIamPolicyRequest, ::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_iam_policy(resource: nil, policy: nil, update_mask: nil)
+            #   Pass arguments to `set_iam_policy` 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 resource [::String]
+            #     REQUIRED: The resource for which the policy is being specified.
+            #     See the operation documentation for the appropriate value for this field.
+            #   @param policy [::Google::Iam::V1::Policy, ::Hash]
+            #     REQUIRED: The complete policy to be applied to the `resource`. The size of
+            #     the policy is limited to a few 10s of KB. An empty policy is a
+            #     valid policy but certain Cloud Platform services (such as Projects)
+            #     might reject them.
+            #   @param update_mask [::Google::Protobuf::FieldMask, ::Hash]
+            #     OPTIONAL: A FieldMask specifying which fields of the policy to modify. Only
+            #     the fields in the mask will be modified. If no mask is provided, the
+            #     following default mask is used:
+            #
+            #     `paths: "bindings, etag"`
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Google::Iam::V1::Policy]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Google::Iam::V1::Policy]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            # @example Basic example
+            #   require "google/cloud/discovery_engine/v1beta"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::DiscoveryEngine::V1beta::EngineService::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Iam::V1::SetIamPolicyRequest.new
+            #
+            #   # Call the set_iam_policy method.
+            #   result = client.set_iam_policy request
+            #
+            #   # The returned object is of type Google::Iam::V1::Policy.
+            #   p result
+            #
+            def set_iam_policy request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Iam::V1::SetIamPolicyRequest
+
+              # 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_iam_policy.metadata.to_h
+
+              # Set x-goog-api-client, x-goog-user-project and x-goog-api-version 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::DiscoveryEngine::V1beta::VERSION
+              metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {}
+              if request.resource
+                header_params["resource"] = request.resource
+              end
+
+              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_iam_policy.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.set_iam_policy.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @engine_service_stub.call_rpc :set_iam_policy, request, options: options do |response, operation|
+                yield response, operation if block_given?
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
             ##
             # Configuration class for the EngineService API.
             #
@@ -1211,6 +1415,16 @@ module Google
                 # @return [::Gapic::Config::Method]
                 #
                 attr_reader :tune_engine
+                ##
+                # RPC-specific configuration for `get_iam_policy`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :get_iam_policy
+                ##
+                # RPC-specific configuration for `set_iam_policy`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :set_iam_policy
 
                 # @private
                 def initialize parent_rpcs = nil
@@ -1230,6 +1444,10 @@ module Google
                   @resume_engine = ::Gapic::Config::Method.new resume_engine_config
                   tune_engine_config = parent_rpcs.tune_engine if parent_rpcs.respond_to? :tune_engine
                   @tune_engine = ::Gapic::Config::Method.new tune_engine_config
+                  get_iam_policy_config = parent_rpcs.get_iam_policy if parent_rpcs.respond_to? :get_iam_policy
+                  @get_iam_policy = ::Gapic::Config::Method.new get_iam_policy_config
+                  set_iam_policy_config = parent_rpcs.set_iam_policy if parent_rpcs.respond_to? :set_iam_policy
+                  @set_iam_policy = ::Gapic::Config::Method.new set_iam_policy_config
 
                   yield self if block_given?
                 end

data/lib/google/cloud/discovery_engine/v1beta/engine_service/credentials.rb

@@ -26,7 +26,9 @@ module Google
           # Credentials for the EngineService API.
           class Credentials < ::Google::Auth::Credentials
             self.scope = [
-              "https://www.googleapis.com/auth/cloud-platform"
+              "https://www.googleapis.com/auth/cloud-platform",
+              "https://www.googleapis.com/auth/discoveryengine.readwrite",
+              "https://www.googleapis.com/auth/discoveryengine.serving.readwrite"
             ]
             self.env_vars = [
               "GOOGLE_CLOUD_CREDENTIALS",

data/lib/google/cloud/discovery_engine/v1beta/engine_service/paths.rb

@@ -24,6 +24,66 @@ module Google
         module EngineService
           # Path helper methods for the EngineService API.
           module Paths
+            ##
+            # Create a fully-qualified AgentGateway resource string.
+            #
+            # The resource will be in the following format:
+            #
+            # `projects/{project}/locations/{location}/agentGateways/{agent_gateway}`
+            #
+            # @param project [String]
+            # @param location [String]
+            # @param agent_gateway [String]
+            #
+            # @return [::String]
+            def agent_gateway_path project:, location:, agent_gateway:
+              raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+              raise ::ArgumentError, "location cannot contain /" if location.to_s.include? "/"
+
+              "projects/#{project}/locations/#{location}/agentGateways/#{agent_gateway}"
+            end
+
+            ##
+            # Create a fully-qualified CmekConfig resource string.
+            #
+            # @overload cmek_config_path(project:, location:)
+            #   The resource will be in the following format:
+            #
+            #   `projects/{project}/locations/{location}/cmekConfig`
+            #
+            #   @param project [String]
+            #   @param location [String]
+            #
+            # @overload cmek_config_path(project:, location:, cmek_config:)
+            #   The resource will be in the following format:
+            #
+            #   `projects/{project}/locations/{location}/cmekConfigs/{cmek_config}`
+            #
+            #   @param project [String]
+            #   @param location [String]
+            #   @param cmek_config [String]
+            #
+            # @return [::String]
+            def cmek_config_path **args
+              resources = {
+                "location:project" => (proc do |project:, location:|
+                  raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+
+                  "projects/#{project}/locations/#{location}/cmekConfig"
+                end),
+                "cmek_config:location:project" => (proc do |project:, location:, cmek_config:|
+                  raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+                  raise ::ArgumentError, "location cannot contain /" if location.to_s.include? "/"
+
+                  "projects/#{project}/locations/#{location}/cmekConfigs/#{cmek_config}"
+                end)
+              }
+
+              resource = resources[args.keys.sort.join(":")]
+              raise ::ArgumentError, "no resource found for values #{args.keys}" if resource.nil?
+              resource.call(**args)
+            end
+
             ##
             # Create a fully-qualified Collection resource string.
             #
@@ -43,6 +103,50 @@ module Google
               "projects/#{project}/locations/#{location}/collections/#{collection}"
             end
 
+            ##
+            # Create a fully-qualified CryptoKeyVersions resource string.
+            #
+            # The resource will be in the following format:
+            #
+            # `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}`
+            #
+            # @param project [String]
+            # @param location [String]
+            # @param key_ring [String]
+            # @param crypto_key [String]
+            # @param crypto_key_version [String]
+            #
+            # @return [::String]
+            def crypto_key_versions_path project:, location:, key_ring:, crypto_key:, crypto_key_version:
+              raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+              raise ::ArgumentError, "location cannot contain /" if location.to_s.include? "/"
+              raise ::ArgumentError, "key_ring cannot contain /" if key_ring.to_s.include? "/"
+              raise ::ArgumentError, "crypto_key cannot contain /" if crypto_key.to_s.include? "/"
+
+              "projects/#{project}/locations/#{location}/keyRings/#{key_ring}/cryptoKeys/#{crypto_key}/cryptoKeyVersions/#{crypto_key_version}"
+            end
+
+            ##
+            # Create a fully-qualified CryptoKeys resource string.
+            #
+            # The resource will be in the following format:
+            #
+            # `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`
+            #
+            # @param project [String]
+            # @param location [String]
+            # @param key_ring [String]
+            # @param crypto_key [String]
+            #
+            # @return [::String]
+            def crypto_keys_path project:, location:, key_ring:, crypto_key:
+              raise ::ArgumentError, "project cannot contain /" if project.to_s.include? "/"
+              raise ::ArgumentError, "location cannot contain /" if location.to_s.include? "/"
+              raise ::ArgumentError, "key_ring cannot contain /" if key_ring.to_s.include? "/"
+
+              "projects/#{project}/locations/#{location}/keyRings/#{key_ring}/cryptoKeys/#{crypto_key}"
+            end
+
             ##
             # Create a fully-qualified Engine resource string.
             #