google-api-client 0.32.1 → 0.36.0

data/generated/google/apis/ml_v1/classes.rb

@@ -109,7 +109,10 @@ module Google
       end
       
       # Represents a hardware accelerator request config.
-      # Note that the AcceleratorConfig could be used in both Jobs and Versions.
+      # Note that the AcceleratorConfig can be used in both Jobs and Versions.
+      # Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and
+      # [accelerators for online
+      # prediction](/ml-engine/docs/machine-types-online-prediction#gpus).
       class GoogleCloudMlV1AcceleratorConfig
         include Google::Apis::Core::Hashable
       
@@ -151,9 +154,18 @@ module Google
         # increased load as well as scale back as traffic drops, always maintaining
         # at least `min_nodes`. You will be charged for the time in which additional
         # nodes are used.
-        # If not specified, `min_nodes` defaults to 0, in which case, when traffic
-        # to a model stops (and after a cool-down period), nodes will be shut down
-        # and no charges will be incurred until traffic to the model resumes.
+        # If `min_nodes` is not specified and AutoScaling is used with a [legacy
+        # (MLS1) machine type](/ml-engine/docs/machine-types-online-prediction),
+        # `min_nodes` defaults to 0, in which case, when traffic to a model stops
+        # (and after a cool-down period), nodes will be shut down and no charges will
+        # be incurred until traffic to the model resumes.
+        # If `min_nodes` is not specified and AutoScaling is used with a [Compute
+        # Engine (N1) machine type](/ml-engine/docs/machine-types-online-prediction),
+        # `min_nodes` defaults to 1. `min_nodes` must be at least 1 for use with a
+        # Compute Engine machine type.
+        # Note that you cannot use AutoScaling if your version uses
+        # [GPUs](#Version.FIELDS.accelerator_config). Instead, you must use
+        # ManualScaling.
         # You can set `min_nodes` when creating the model version, and you can also
         # update `min_nodes` for an existing version:
         # <pre>
@@ -165,7 +177,7 @@ module Google
         # `
         # </pre>
         # HTTP request:
-        # <pre>
+        # <pre style="max-width: 626px;">
         # PATCH
         # https://ml.googleapis.com/v1/`name=projects/*/models/*/versions/*`?update_mask=
         # autoScaling.minNodes
@@ -282,6 +294,87 @@ module Google
         end
       end
       
+      # Request for explanations to be issued against a trained model.
+      class GoogleCloudMlV1ExplainRequest
+        include Google::Apis::Core::Hashable
+      
+        # Message that represents an arbitrary HTTP body. It should only be used for
+        # payload formats that can't be represented as JSON, such as raw binary or
+        # an HTML page.
+        # This message can be used both in streaming and non-streaming API methods in
+        # the request as well as the response.
+        # It can be used as a top-level request field, which is convenient if one
+        # wants to extract parameters from either the URL or HTTP template into the
+        # request fields and also want access to the raw HTTP body.
+        # Example:
+        # message GetResourceRequest `
+        # // A unique request id.
+        # string request_id = 1;
+        # // The raw HTTP body is bound to this field.
+        # google.api.HttpBody http_body = 2;
+        # `
+        # service ResourceService `
+        # rpc GetResource(GetResourceRequest) returns (google.api.HttpBody);
+        # rpc UpdateResource(google.api.HttpBody) returns
+        # (google.protobuf.Empty);
+        # `
+        # Example with streaming methods:
+        # service CaldavService `
+        # rpc GetCalendar(stream google.api.HttpBody)
+        # returns (stream google.api.HttpBody);
+        # rpc UpdateCalendar(stream google.api.HttpBody)
+        # returns (stream google.api.HttpBody);
+        # `
+        # Use of this type only changes how the request and response bodies are
+        # handled, all other features will continue to work unchanged.
+        # Corresponds to the JSON property `httpBody`
+        # @return [Google::Apis::MlV1::GoogleApiHttpBody]
+        attr_accessor :http_body
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @http_body = args[:http_body] if args.key?(:http_body)
+        end
+      end
+      
+      # Message holding configuration options for explaining model predictions.
+      # Currently, the only supported mechanism to explain a model's prediction is
+      # through attributing its output back to its inputs which is essentially a
+      # credit assignment task. We support multiple attribution methods, some
+      # specific to particular frameworks like Tensorflow and XGBoost.
+      # Next idx: 7.
+      class GoogleCloudMlV1ExplanationConfig
+        include Google::Apis::Core::Hashable
+      
+        # Attributes credit by computing the Aumann-Shapley value taking advantage
+        # of the model's fully differentiable structure. Refer to this paper for
+        # more details: http://proceedings.mlr.press/v70/sundararajan17a.html
+        # Corresponds to the JSON property `integratedGradientsAttribution`
+        # @return [Google::Apis::MlV1::GoogleCloudMlV1IntegratedGradientsAttribution]
+        attr_accessor :integrated_gradients_attribution
+      
+        # An attribution method that approximates Shapley values for features that
+        # contribute to the label being predicted. A sampling strategy is used to
+        # approximate the value rather than considering all subsets of features.
+        # Corresponds to the JSON property `sampledShapleyAttribution`
+        # @return [Google::Apis::MlV1::GoogleCloudMlV1SampledShapleyAttribution]
+        attr_accessor :sampled_shapley_attribution
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @integrated_gradients_attribution = args[:integrated_gradients_attribution] if args.key?(:integrated_gradients_attribution)
+          @sampled_shapley_attribution = args[:sampled_shapley_attribution] if args.key?(:sampled_shapley_attribution)
+        end
+      end
+      
       # Returns service account information associated with a project.
       class GoogleCloudMlV1GetConfigResponse
         include Google::Apis::Core::Hashable
@@ -478,6 +571,29 @@ module Google
         end
       end
       
+      # Attributes credit by computing the Aumann-Shapley value taking advantage
+      # of the model's fully differentiable structure. Refer to this paper for
+      # more details: http://proceedings.mlr.press/v70/sundararajan17a.html
+      class GoogleCloudMlV1IntegratedGradientsAttribution
+        include Google::Apis::Core::Hashable
+      
+        # Number of steps for approximating the path integral.
+        # A good value to start is 50 and gradually increase until the
+        # sum to diff property is met within the desired error range.
+        # Corresponds to the JSON property `numIntegralSteps`
+        # @return [Fixnum]
+        attr_accessor :num_integral_steps
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @num_integral_steps = args[:num_integral_steps] if args.key?(:num_integral_steps)
+        end
+      end
+      
       # Represents a training or prediction job.
       class GoogleCloudMlV1Job
         include Google::Apis::Core::Hashable
@@ -1176,7 +1292,10 @@ module Google
         include Google::Apis::Core::Hashable
       
         # Represents a hardware accelerator request config.
-        # Note that the AcceleratorConfig could be used in both Jobs and Versions.
+        # Note that the AcceleratorConfig can be used in both Jobs and Versions.
+        # Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and
+        # [accelerators for online
+        # prediction](/ml-engine/docs/machine-types-online-prediction#gpus).
         # Corresponds to the JSON property `acceleratorConfig`
         # @return [Google::Apis::MlV1::GoogleCloudMlV1AcceleratorConfig]
         attr_accessor :accelerator_config
@@ -1269,6 +1388,28 @@ module Google
         end
       end
       
+      # An attribution method that approximates Shapley values for features that
+      # contribute to the label being predicted. A sampling strategy is used to
+      # approximate the value rather than considering all subsets of features.
+      class GoogleCloudMlV1SampledShapleyAttribution
+        include Google::Apis::Core::Hashable
+      
+        # The number of feature permutations to consider when approximating the
+        # shapley values.
+        # Corresponds to the JSON property `numPaths`
+        # @return [Fixnum]
+        attr_accessor :num_paths
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @num_paths = args[:num_paths] if args.key?(:num_paths)
+        end
+      end
+      
       # Request message for the SetDefaultVersion request.
       class GoogleCloudMlV1SetDefaultVersionRequest
         include Google::Apis::Core::Hashable
@@ -1316,92 +1457,10 @@ module Google
         attr_accessor :master_config
       
         # Optional. Specifies the type of virtual machine to use for your training
-        # job's master worker.
+        # job's master worker. You must specify this field when `scaleTier` is set to
+        # `CUSTOM`.
+        # You can use certain Compute Engine machine types directly in this field.
         # The following types are supported:
-        # <dl>
-        # <dt>standard</dt>
-        # <dd>
-        # A basic machine configuration suitable for training simple models with
-        # small to moderate datasets.
-        # </dd>
-        # <dt>large_model</dt>
-        # <dd>
-        # A machine with a lot of memory, specially suited for parameter servers
-        # when your model is large (having many hidden layers or layers with very
-        # large numbers of nodes).
-        # </dd>
-        # <dt>complex_model_s</dt>
-        # <dd>
-        # A machine suitable for the master and workers of the cluster when your
-        # model requires more computation than the standard machine can handle
-        # satisfactorily.
-        # </dd>
-        # <dt>complex_model_m</dt>
-        # <dd>
-        # A machine with roughly twice the number of cores and roughly double the
-        # memory of <i>complex_model_s</i>.
-        # </dd>
-        # <dt>complex_model_l</dt>
-        # <dd>
-        # A machine with roughly twice the number of cores and roughly double the
-        # memory of <i>complex_model_m</i>.
-        # </dd>
-        # <dt>standard_gpu</dt>
-        # <dd>
-        # A machine equivalent to <i>standard</i> that
-        # also includes a single NVIDIA Tesla K80 GPU. See more about
-        # <a href="/ml-engine/docs/tensorflow/using-gpus">using GPUs to
-        # train your model</a>.
-        # </dd>
-        # <dt>complex_model_m_gpu</dt>
-        # <dd>
-        # A machine equivalent to <i>complex_model_m</i> that also includes
-        # four NVIDIA Tesla K80 GPUs.
-        # </dd>
-        # <dt>complex_model_l_gpu</dt>
-        # <dd>
-        # A machine equivalent to <i>complex_model_l</i> that also includes
-        # eight NVIDIA Tesla K80 GPUs.
-        # </dd>
-        # <dt>standard_p100</dt>
-        # <dd>
-        # A machine equivalent to <i>standard</i> that
-        # also includes a single NVIDIA Tesla P100 GPU.
-        # </dd>
-        # <dt>complex_model_m_p100</dt>
-        # <dd>
-        # A machine equivalent to <i>complex_model_m</i> that also includes
-        # four NVIDIA Tesla P100 GPUs.
-        # </dd>
-        # <dt>standard_v100</dt>
-        # <dd>
-        # A machine equivalent to <i>standard</i> that
-        # also includes a single NVIDIA Tesla V100 GPU.
-        # </dd>
-        # <dt>large_model_v100</dt>
-        # <dd>
-        # A machine equivalent to <i>large_model</i> that
-        # also includes a single NVIDIA Tesla V100 GPU.
-        # </dd>
-        # <dt>complex_model_m_v100</dt>
-        # <dd>
-        # A machine equivalent to <i>complex_model_m</i> that
-        # also includes four NVIDIA Tesla V100 GPUs.
-        # </dd>
-        # <dt>complex_model_l_v100</dt>
-        # <dd>
-        # A machine equivalent to <i>complex_model_l</i> that
-        # also includes eight NVIDIA Tesla V100 GPUs.
-        # </dd>
-        # <dt>cloud_tpu</dt>
-        # <dd>
-        # A TPU VM including one Cloud TPU. See more about
-        # <a href="/ml-engine/docs/tensorflow/using-tpus">using TPUs to train
-        # your model</a>.
-        # </dd>
-        # </dl>
-        # You may also use certain Compute Engine machine types directly in this
-        # field. The following types are supported:
         # - `n1-standard-4`
         # - `n1-standard-8`
         # - `n1-standard-16`
@@ -1419,9 +1478,29 @@ module Google
         # - `n1-highcpu-32`
         # - `n1-highcpu-64`
         # - `n1-highcpu-96`
-        # See more about [using Compute Engine machine
-        # types](/ml-engine/docs/tensorflow/machine-types#compute-engine-machine-types).
-        # You must set this value when `scaleTier` is set to `CUSTOM`.
+        # Learn more about [using Compute Engine machine
+        # types](/ml-engine/docs/machine-types#compute-engine-machine-types).
+        # Alternatively, you can use the following legacy machine types:
+        # - `standard`
+        # - `large_model`
+        # - `complex_model_s`
+        # - `complex_model_m`
+        # - `complex_model_l`
+        # - `standard_gpu`
+        # - `complex_model_m_gpu`
+        # - `complex_model_l_gpu`
+        # - `standard_p100`
+        # - `complex_model_m_p100`
+        # - `standard_v100`
+        # - `large_model_v100`
+        # - `complex_model_m_v100`
+        # - `complex_model_l_v100`
+        # Learn more about [using legacy machine
+        # types](/ml-engine/docs/machine-types#legacy-machine-types).
+        # Finally, if you want to use a TPU for training, specify `cloud_tpu` in this
+        # field. Learn more about the [special configuration options for training
+        # with
+        # TPUs](/ml-engine/docs/tensorflow/using-tpus#configuring_a_custom_tpu_machine).
         # Corresponds to the JSON property `masterType`
         # @return [String]
         attr_accessor :master_type
@@ -1453,8 +1532,8 @@ module Google
         # The supported values are the same as those described in the entry for
         # `master_type`.
         # This value must be consistent with the category of machine type that
-        # `masterType` uses. In other words, both must be AI Platform machine
-        # types or both must be Compute Engine machine types.
+        # `masterType` uses. In other words, both must be Compute Engine machine
+        # types or both must be legacy machine types.
         # This value must be present when `scaleTier` is set to `CUSTOM` and
         # `parameter_server_count` is greater than zero.
         # Corresponds to the JSON property `parameterServerType`
@@ -1497,6 +1576,14 @@ module Google
         # @return [String]
         attr_accessor :scale_tier
       
+        # Optional. Use 'chief' instead of 'master' in TF_CONFIG when Custom
+        # Container is used and evaluator is not specified.
+        # Defaults to false.
+        # Corresponds to the JSON property `useChiefInTfConfig`
+        # @return [Boolean]
+        attr_accessor :use_chief_in_tf_config
+        alias_method :use_chief_in_tf_config?, :use_chief_in_tf_config
+      
         # Represents the configuration for a replica in a cluster.
         # Corresponds to the JSON property `workerConfig`
         # @return [Google::Apis::MlV1::GoogleCloudMlV1ReplicaConfig]
@@ -1516,8 +1603,8 @@ module Google
         # The supported values are the same as those described in the entry for
         # `masterType`.
         # This value must be consistent with the category of machine type that
-        # `masterType` uses. In other words, both must be AI Platform machine
-        # types or both must be Compute Engine machine types.
+        # `masterType` uses. In other words, both must be Compute Engine machine
+        # types or both must be legacy machine types.
         # If you use `cloud_tpu` for this value, see special instructions for
         # [configuring a custom TPU
         # machine](/ml-engine/docs/tensorflow/using-tpus#
@@ -1548,6 +1635,7 @@ module Google
           @region = args[:region] if args.key?(:region)
           @runtime_version = args[:runtime_version] if args.key?(:runtime_version)
           @scale_tier = args[:scale_tier] if args.key?(:scale_tier)
+          @use_chief_in_tf_config = args[:use_chief_in_tf_config] if args.key?(:use_chief_in_tf_config)
           @worker_config = args[:worker_config] if args.key?(:worker_config)
           @worker_count = args[:worker_count] if args.key?(:worker_count)
           @worker_type = args[:worker_type] if args.key?(:worker_type)
@@ -1627,7 +1715,10 @@ module Google
         include Google::Apis::Core::Hashable
       
         # Represents a hardware accelerator request config.
-        # Note that the AcceleratorConfig could be used in both Jobs and Versions.
+        # Note that the AcceleratorConfig can be used in both Jobs and Versions.
+        # Learn more about [accelerators for training](/ml-engine/docs/using-gpus) and
+        # [accelerators for online
+        # prediction](/ml-engine/docs/machine-types-online-prediction#gpus).
         # Corresponds to the JSON property `acceleratorConfig`
         # @return [Google::Apis::MlV1::GoogleCloudMlV1AcceleratorConfig]
         attr_accessor :accelerator_config
@@ -1680,6 +1771,16 @@ module Google
         # @return [String]
         attr_accessor :etag
       
+        # Message holding configuration options for explaining model predictions.
+        # Currently, the only supported mechanism to explain a model's prediction is
+        # through attributing its output back to its inputs which is essentially a
+        # credit assignment task. We support multiple attribution methods, some
+        # specific to particular frameworks like Tensorflow and XGBoost.
+        # Next idx: 7.
+        # Corresponds to the JSON property `explanationConfig`
+        # @return [Google::Apis::MlV1::GoogleCloudMlV1ExplanationConfig]
+        attr_accessor :explanation_config
+      
         # Optional. The machine learning framework AI Platform uses to train
         # this version of the model. Valid values are `TENSORFLOW`, `SCIKIT_LEARN`,
         # `XGBOOST`. If you do not specify a framework, AI Platform
@@ -1688,6 +1789,10 @@ module Google
         # of the model to 1.4 or greater.
         # Do **not** specify a framework if you're deploying a [custom
         # prediction routine](/ml-engine/docs/tensorflow/custom-prediction-routines).
+        # If you specify a [Compute Engine (N1) machine
+        # type](/ml-engine/docs/machine-types-online-prediction) in the
+        # `machineType` field, you must specify `TENSORFLOW`
+        # for the framework.
         # Corresponds to the JSON property `framework`
         # @return [String]
         attr_accessor :framework
@@ -1717,19 +1822,29 @@ module Google
         attr_accessor :last_use_time
       
         # Optional. The type of machine on which to serve the model. Currently only
-        # applies to online prediction service.
-        # <dl>
-        # <dt>mls1-c1-m2</dt>
-        # <dd>
-        # The <b>default</b> machine type, with 1 core and 2 GB RAM. The deprecated
-        # name for this machine type is "mls1-highmem-1".
-        # </dd>
-        # <dt>mls1-c4-m2</dt>
-        # <dd>
-        # In <b>Beta</b>. This machine type has 4 cores and 2 GB RAM. The
-        # deprecated name for this machine type is "mls1-highcpu-4".
-        # </dd>
-        # </dl>
+        # applies to online prediction service. If this field is not specified, it
+        # defaults to `mls1-c1-m2`.
+        # Online prediction supports the following machine types:
+        # * `mls1-c1-m2`
+        # * `mls1-c4-m2`
+        # * `n1-standard-2`
+        # * `n1-standard-4`
+        # * `n1-standard-8`
+        # * `n1-standard-16`
+        # * `n1-standard-32`
+        # * `n1-highmem-2`
+        # * `n1-highmem-4`
+        # * `n1-highmem-8`
+        # * `n1-highmem-16`
+        # * `n1-highmem-32`
+        # * `n1-highcpu-2`
+        # * `n1-highcpu-4`
+        # * `n1-highcpu-8`
+        # * `n1-highcpu-16`
+        # * `n1-highcpu-32`
+        # `mls1-c1-m2` is generally available. All other machine types are available
+        # in beta. Learn more about the [differences between machine
+        # types](/ml-engine/docs/machine-types-online-prediction).
         # Corresponds to the JSON property `machineType`
         # @return [String]
         attr_accessor :machine_type
@@ -1769,9 +1884,11 @@ module Google
         # Specify this field if and only if you are deploying a [custom prediction
         # routine (beta)](/ml-engine/docs/tensorflow/custom-prediction-routines).
         # If you specify this field, you must set
-        # [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater.
+        # [`runtimeVersion`](#Version.FIELDS.runtime_version) to 1.4 or greater and
+        # you must set `machineType` to a [legacy (MLS1)
+        # machine type](/ml-engine/docs/machine-types-online-prediction).
         # The following code sample provides the Predictor interface:
-        # ```py
+        # <pre style="max-width: 626px;">
         # class Predictor(object):
         # """Interface for constructing custom predictors."""
         # def predict(self, instances, **kwargs):
@@ -1799,7 +1916,7 @@ module Google
         # An instance implementing this Predictor class.
         # """
         # raise NotImplementedError()
-        # ```
+        # </pre>
         # Learn more about [the Predictor interface and custom prediction
         # routines](/ml-engine/docs/tensorflow/custom-prediction-routines).
         # Corresponds to the JSON property `predictionClass`
@@ -1860,6 +1977,7 @@ module Google
           @description = args[:description] if args.key?(:description)
           @error_message = args[:error_message] if args.key?(:error_message)
           @etag = args[:etag] if args.key?(:etag)
+          @explanation_config = args[:explanation_config] if args.key?(:explanation_config)
           @framework = args[:framework] if args.key?(:framework)
           @is_default = args[:is_default] if args.key?(:is_default)
           @labels = args[:labels] if args.key?(:labels)
@@ -2017,6 +2135,23 @@ module Google
         # account. For example, `my-other-app@appspot.gserviceaccount.com`.
         # * `group:`emailid``: An email address that represents a Google group.
         # For example, `admins@example.com`.
+        # * `deleted:user:`emailid`?uid=`uniqueid``: An email address (plus unique
+        # identifier) representing a user that has been recently deleted. For
+        # example,`alice@example.com?uid=123456789012345678901`. If the user is
+        # recovered, this value reverts to `user:`emailid`` and the recovered user
+        # retains the role in the binding.
+        # * `deleted:serviceAccount:`emailid`?uid=`uniqueid``: An email address (plus
+        # unique identifier) representing a service account that has been recently
+        # deleted. For example,
+        # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
+        # If the service account is undeleted, this value reverts to
+        # `serviceAccount:`emailid`` and the undeleted service account retains the
+        # role in the binding.
+        # * `deleted:group:`emailid`?uid=`uniqueid``: An email address (plus unique
+        # identifier) representing a Google group that has been recently
+        # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
+        # the group is recovered, this value reverts to `group:`emailid`` and the
+        # recovered group retains the role in the binding.
         # * `domain:`domain``: The G Suite domain (primary) that represents all the
         # users of that domain. For example, `google.com` or `example.com`.
         # Corresponds to the JSON property `members`
@@ -2041,16 +2176,18 @@ module Google
         end
       end
       
-      # Defines an Identity and Access Management (IAM) policy. It is used to
-      # specify access control policies for Cloud Platform resources.
+      # An Identity and Access Management (IAM) policy, which specifies access
+      # controls for Google Cloud resources.
       # A `Policy` is a collection of `bindings`. A `binding` binds one or more
       # `members` to a single `role`. Members can be user accounts, service accounts,
       # Google groups, and domains (such as G Suite). A `role` is a named list of
-      # permissions (defined by IAM or configured by users). A `binding` can
-      # optionally specify a `condition`, which is a logic expression that further
-      # constrains the role binding based on attributes about the request and/or
-      # target resource.
-      # **JSON Example**
+      # permissions; each `role` can be an IAM predefined role or a user-created
+      # custom role.
+      # Optionally, a `binding` can specify a `condition`, which is a logical
+      # expression that allows access to a resource only if the expression evaluates
+      # to `true`. A condition can add constraints based on attributes of the
+      # request, the resource, or both.
+      # **JSON example:**
       # `
       # "bindings": [
       # `
@@ -2068,13 +2205,15 @@ module Google
       # "condition": `
       # "title": "expirable access",
       # "description": "Does not grant access after Sep 2020",
-      # "expression": "request.time <
-      # timestamp('2020-10-01T00:00:00.000Z')",
+      # "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')
+      # ",
       # `
       # `
-      # ]
+      # ],
+      # "etag": "BwWWja0YfJA=",
+      # "version": 3
       # `
-      # **YAML Example**
+      # **YAML example:**
       # bindings:
       # - members:
       # - user:mike@example.com
@@ -2089,8 +2228,10 @@ module Google
       # title: expirable access
       # description: Does not grant access after Sep 2020
       # expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+      # - etag: BwWWja0YfJA=
+      # - version: 3
       # For a description of IAM and its features, see the
-      # [IAM developer's guide](https://cloud.google.com/iam/docs).
+      # [IAM documentation](https://cloud.google.com/iam/docs/).
       class GoogleIamV1Policy
         include Google::Apis::Core::Hashable
       
@@ -2099,9 +2240,9 @@ module Google
         # @return [Array<Google::Apis::MlV1::GoogleIamV1AuditConfig>]
         attr_accessor :audit_configs
       
-        # Associates a list of `members` to a `role`. Optionally may specify a
-        # `condition` that determines when binding is in effect.
-        # `bindings` with no members will result in an error.
+        # Associates a list of `members` to a `role`. Optionally, may specify a
+        # `condition` that determines how and when the `bindings` are applied. Each
+        # of the `bindings` must contain at least one member.
         # Corresponds to the JSON property `bindings`
         # @return [Array<Google::Apis::MlV1::GoogleIamV1Binding>]
         attr_accessor :bindings
@@ -2113,25 +2254,31 @@ module Google
         # conditions: An `etag` is returned in the response to `getIamPolicy`, and
         # systems are expected to put that etag in the request to `setIamPolicy` to
         # ensure that their change will be applied to the same version of the policy.
-        # If no `etag` is provided in the call to `setIamPolicy`, then the existing
-        # policy is overwritten. Due to blind-set semantics of an etag-less policy,
-        # 'setIamPolicy' will not fail even if either of incoming or stored policy
-        # does not meet the version requirements.
+        # **Important:** If you use IAM Conditions, you must include the `etag` field
+        # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
+        # you to overwrite a version `3` policy with a version `1` policy, and all of
+        # the conditions in the version `3` policy are lost.
         # Corresponds to the JSON property `etag`
         # NOTE: Values are automatically base64 encoded/decoded in the client library.
         # @return [String]
         attr_accessor :etag
       
         # Specifies the format of the policy.
-        # Valid values are 0, 1, and 3. Requests specifying an invalid value will be
-        # rejected.
-        # Operations affecting conditional bindings must specify version 3. This can
-        # be either setting a conditional policy, modifying a conditional binding,
-        # or removing a conditional binding from the stored conditional policy.
-        # Operations on non-conditional policies may specify any valid value or
-        # leave the field unset.
-        # If no etag is provided in the call to `setIamPolicy`, any version
-        # compliance checks on the incoming and/or stored policy is skipped.
+        # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
+        # are rejected.
+        # Any operation that affects conditional role bindings must specify version
+        # `3`. This requirement applies to the following operations:
+        # * Getting a policy that includes a conditional role binding
+        # * Adding a conditional role binding to a policy
+        # * Changing a conditional role binding in a policy
+        # * Removing any role binding, with or without a condition, from a policy
+        # that includes conditions
+        # **Important:** If you use IAM Conditions, you must include the `etag` field
+        # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
+        # you to overwrite a version `3` policy with a version `1` policy, and all of
+        # the conditions in the version `3` policy are lost.
+        # If a policy does not include any conditions, operations on that policy may
+        # specify any valid version or leave the field unset.
         # Corresponds to the JSON property `version`
         # @return [Fixnum]
         attr_accessor :version
@@ -2153,16 +2300,18 @@ module Google
       class GoogleIamV1SetIamPolicyRequest
         include Google::Apis::Core::Hashable
       
-        # Defines an Identity and Access Management (IAM) policy. It is used to
-        # specify access control policies for Cloud Platform resources.
+        # An Identity and Access Management (IAM) policy, which specifies access
+        # controls for Google Cloud resources.
         # A `Policy` is a collection of `bindings`. A `binding` binds one or more
         # `members` to a single `role`. Members can be user accounts, service accounts,
         # Google groups, and domains (such as G Suite). A `role` is a named list of
-        # permissions (defined by IAM or configured by users). A `binding` can
-        # optionally specify a `condition`, which is a logic expression that further
-        # constrains the role binding based on attributes about the request and/or
-        # target resource.
-        # **JSON Example**
+        # permissions; each `role` can be an IAM predefined role or a user-created
+        # custom role.
+        # Optionally, a `binding` can specify a `condition`, which is a logical
+        # expression that allows access to a resource only if the expression evaluates
+        # to `true`. A condition can add constraints based on attributes of the
+        # request, the resource, or both.
+        # **JSON example:**
         # `
         # "bindings": [
         # `
@@ -2180,13 +2329,15 @@ module Google
         # "condition": `
         # "title": "expirable access",
         # "description": "Does not grant access after Sep 2020",
-        # "expression": "request.time <
-        # timestamp('2020-10-01T00:00:00.000Z')",
+        # "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')
+        # ",
         # `
         # `
-        # ]
+        # ],
+        # "etag": "BwWWja0YfJA=",
+        # "version": 3
         # `
-        # **YAML Example**
+        # **YAML example:**
         # bindings:
         # - members:
         # - user:mike@example.com
@@ -2201,8 +2352,10 @@ module Google
         # title: expirable access
         # description: Does not grant access after Sep 2020
         # expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+        # - etag: BwWWja0YfJA=
+        # - version: 3
         # For a description of IAM and its features, see the
-        # [IAM developer's guide](https://cloud.google.com/iam/docs).
+        # [IAM documentation](https://cloud.google.com/iam/docs/).
         # Corresponds to the JSON property `policy`
         # @return [Google::Apis::MlV1::GoogleIamV1Policy]
         attr_accessor :policy