chore: regens API reference docs (#889)
diff --git a/docs/dyn/pubsub_v1.projects.subscriptions.html b/docs/dyn/pubsub_v1.projects.subscriptions.html
index 18b7f04..626bd82 100644
--- a/docs/dyn/pubsub_v1.projects.subscriptions.html
+++ b/docs/dyn/pubsub_v1.projects.subscriptions.html
@@ -75,10 +75,10 @@
<h1><a href="pubsub_v1.html">Cloud Pub/Sub API</a> . <a href="pubsub_v1.projects.html">projects</a> . <a href="pubsub_v1.projects.subscriptions.html">subscriptions</a></h1>
<h2>Instance Methods</h2>
<p class="toc_element">
- <code><a href="#acknowledge">acknowledge(subscription, body, x__xgafv=None)</a></code></p>
+ <code><a href="#acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Acknowledges the messages associated with the `ack_ids` in the</p>
<p class="toc_element">
- <code><a href="#create">create(name, body, x__xgafv=None)</a></code></p>
+ <code><a href="#create">create(name, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Creates a subscription to a given topic. See the</p>
<p class="toc_element">
<code><a href="#delete">delete(subscription, x__xgafv=None)</a></code></p>
@@ -87,7 +87,7 @@
<code><a href="#get">get(subscription, x__xgafv=None)</a></code></p>
<p class="firstline">Gets the configuration details of a subscription.</p>
<p class="toc_element">
- <code><a href="#getIamPolicy">getIamPolicy(resource, x__xgafv=None)</a></code></p>
+ <code><a href="#getIamPolicy">getIamPolicy(resource, options_requestedPolicyVersion=None, x__xgafv=None)</a></code></p>
<p class="firstline">Gets the access control policy for a resource.</p>
<p class="toc_element">
<code><a href="#list">list(project, pageSize=None, pageToken=None, x__xgafv=None)</a></code></p>
@@ -96,29 +96,29 @@
<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
<p class="firstline">Retrieves the next page of results.</p>
<p class="toc_element">
- <code><a href="#modifyAckDeadline">modifyAckDeadline(subscription, body, x__xgafv=None)</a></code></p>
+ <code><a href="#modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Modifies the ack deadline for a specific message. This method is useful</p>
<p class="toc_element">
- <code><a href="#modifyPushConfig">modifyPushConfig(subscription, body, x__xgafv=None)</a></code></p>
+ <code><a href="#modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Modifies the `PushConfig` for a specified subscription.</p>
<p class="toc_element">
- <code><a href="#patch">patch(name, body, x__xgafv=None)</a></code></p>
+ <code><a href="#patch">patch(name, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Updates an existing subscription. Note that certain properties of a</p>
<p class="toc_element">
- <code><a href="#pull">pull(subscription, body, x__xgafv=None)</a></code></p>
+ <code><a href="#pull">pull(subscription, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Pulls messages from the server. The server may return `UNAVAILABLE` if</p>
<p class="toc_element">
- <code><a href="#seek">seek(subscription, body, x__xgafv=None)</a></code></p>
+ <code><a href="#seek">seek(subscription, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Seeks an existing subscription to a point in time or to a given snapshot,</p>
<p class="toc_element">
- <code><a href="#setIamPolicy">setIamPolicy(resource, body, x__xgafv=None)</a></code></p>
+ <code><a href="#setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Sets the access control policy on the specified resource. Replaces any</p>
<p class="toc_element">
- <code><a href="#testIamPermissions">testIamPermissions(resource, body, x__xgafv=None)</a></code></p>
+ <code><a href="#testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</a></code></p>
<p class="firstline">Returns permissions that a caller has on the specified resource.</p>
<h3>Method Details</h3>
<div class="method">
- <code class="details" id="acknowledge">acknowledge(subscription, body, x__xgafv=None)</code>
+ <code class="details" id="acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</code>
<pre>Acknowledges the messages associated with the `ack_ids` in the
`AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages
from the subscription.
@@ -128,13 +128,13 @@
than once will not result in an error.
Args:
- subscription: string, The subscription whose message is being acknowledged.
+ subscription: string, Required. The subscription whose message is being acknowledged.
Format is `projects/{project}/subscriptions/{sub}`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the Acknowledge method.
- "ackIds": [ # The acknowledgment ID for the messages being acknowledged that was returned
+ "ackIds": [ # Required. The acknowledgment ID for the messages being acknowledged that was returned
# by the Pub/Sub system in the `Pull` response. Must not be empty.
"A String",
],
@@ -161,10 +161,10 @@
</div>
<div class="method">
- <code class="details" id="create">create(name, body, x__xgafv=None)</code>
+ <code class="details" id="create">create(name, body=None, x__xgafv=None)</code>
<pre>Creates a subscription to a given topic. See the
-<a href="https://cloud.google.com/pubsub/docs/admin#resource_names">
-resource name rules</a>.
+<a href="https://cloud.google.com/pubsub/docs/admin#resource_names">
+resource name rules</a>.
If the subscription already exists, returns `ALREADY_EXISTS`.
If the corresponding topic doesn't exist, returns `NOT_FOUND`.
@@ -177,17 +177,17 @@
for REST API requests, you must specify a name in the request.
Args:
- name: string, The name of the subscription. It must have the format
+ name: string, Required. The name of the subscription. It must have the format
`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
start with a letter, and contain only letters (`[A-Za-z]`), numbers
(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
in length, and it must not start with `"goog"`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # A subscription resource.
- "name": "A String", # The name of the subscription. It must have the format
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -196,7 +196,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -213,36 +213,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -259,10 +236,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -276,9 +276,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -304,7 +342,7 @@
An object of the form:
{ # A subscription resource.
- "name": "A String", # The name of the subscription. It must have the format
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -313,7 +351,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -330,36 +368,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -376,10 +391,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -393,9 +431,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -422,7 +498,7 @@
subscription or its topic unless the same topic is specified.
Args:
- subscription: string, The subscription to delete.
+ subscription: string, Required. The subscription to delete.
Format is `projects/{project}/subscriptions/{sub}`. (required)
x__xgafv: string, V1 error format.
Allowed values
@@ -449,7 +525,7 @@
<pre>Gets the configuration details of a subscription.
Args:
- subscription: string, The name of the subscription to get.
+ subscription: string, Required. The name of the subscription to get.
Format is `projects/{project}/subscriptions/{sub}`. (required)
x__xgafv: string, V1 error format.
Allowed values
@@ -460,7 +536,7 @@
An object of the form:
{ # A subscription resource.
- "name": "A String", # The name of the subscription. It must have the format
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -469,7 +545,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -486,36 +562,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -532,10 +585,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -549,9 +625,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -570,7 +684,7 @@
</div>
<div class="method">
- <code class="details" id="getIamPolicy">getIamPolicy(resource, x__xgafv=None)</code>
+ <code class="details" id="getIamPolicy">getIamPolicy(resource, options_requestedPolicyVersion=None, x__xgafv=None)</code>
<pre>Gets the access control policy for a resource.
Returns an empty policy if the resource exists and does not have a policy
set.
@@ -578,6 +692,14 @@
Args:
resource: string, REQUIRED: The resource for which the policy is being requested.
See the operation documentation for the appropriate value for this field. (required)
+ options_requestedPolicyVersion: integer, Optional. The policy format version to be returned.
+
+Valid values are 0, 1, and 3. Requests specifying an invalid value will be
+rejected.
+
+Requests for policies with any conditional bindings must specify version 3.
+Policies without any conditional bindings may specify any valid value or
+leave the field unset.
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
@@ -586,53 +708,72 @@
Returns:
An object of the form:
- { # 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` consists of a list of `bindings`. A `binding` binds a list of
- # `members` to a `role`, where the members can be user accounts, Google groups,
- # Google domains, and service accounts. A `role` is a named list of permissions
- # defined by IAM.
+ # 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; each `role` can be an IAM predefined role or a user-created
+ # custom role.
#
- # **JSON Example**
+ # 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": [
# {
- # "role": "roles/owner",
+ # "role": "roles/resourcemanager.organizationAdmin",
# "members": [
# "user:mike@example.com",
# "group:admins@example.com",
# "domain:google.com",
- # "serviceAccount:my-other-app@appspot.gserviceaccount.com"
+ # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
# ]
# },
# {
- # "role": "roles/viewer",
- # "members": ["user:sean@example.com"]
+ # "role": "roles/resourcemanager.organizationViewer",
+ # "members": ["user:eve@example.com"],
+ # "condition": {
+ # "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
# }
#
- # **YAML Example**
+ # **YAML example:**
#
# bindings:
# - members:
# - user:mike@example.com
# - group:admins@example.com
# - domain:google.com
- # - serviceAccount:my-other-app@appspot.gserviceaccount.com
- # role: roles/owner
+ # - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ # role: roles/resourcemanager.organizationAdmin
# - members:
- # - user:sean@example.com
- # role: roles/viewer
- #
+ # - user:eve@example.com
+ # role: roles/resourcemanager.organizationViewer
+ # condition:
+ # 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).
- "bindings": [ # Associates a list of `members` to a `role`.
- # `bindings` with no members will result in an error.
+ # [IAM documentation](https://cloud.google.com/iam/docs/).
+ "bindings": [ # 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.
{ # Associates `members` with a `role`.
"role": "A String", # Role that is assigned to `members`.
# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
@@ -646,7 +787,7 @@
# who is authenticated with a Google account or a service account.
#
# * `user:{emailid}`: An email address that represents a specific Google
- # account. For example, `alice@gmail.com` .
+ # account. For example, `alice@example.com` .
#
#
# * `serviceAccount:{emailid}`: An email address that represents a service
@@ -655,36 +796,78 @@
# * `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`.
#
"A String",
],
- "condition": { # Represents an expression text. Example: # The condition that is associated with this binding.
+ "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
# NOTE: An unsatisfied condition will not allow user access via current
# binding. Different bindings, including their conditions, are examined
# independently.
+ # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
+ # are documented at https://github.com/google/cel-spec.
#
- # title: "User account presence"
- # description: "Determines whether the request has a user account"
- # expression: "size(request.user) > 0"
- "location": "A String", # An optional string indicating the location of the expression for error
- # reporting, e.g. a file name and a position in the file.
- "expression": "A String", # Textual representation of an expression in
- # Common Expression Language syntax.
- #
- # The application context of the containing message determines which
- # well-known feature set of CEL is supported.
- "description": "A String", # An optional description of the expression. This is a longer text which
+ # Example (Comparison):
+ #
+ # title: "Summary size limit"
+ # description: "Determines if a summary is less than 100 chars"
+ # expression: "document.summary.size() < 100"
+ #
+ # Example (Equality):
+ #
+ # title: "Requestor is owner"
+ # description: "Determines if requestor is the document owner"
+ # expression: "document.owner == request.auth.claims.email"
+ #
+ # Example (Logic):
+ #
+ # title: "Public documents"
+ # description: "Determine whether the document should be publicly visible"
+ # expression: "document.type != 'private' && document.type != 'internal'"
+ #
+ # Example (Data Manipulation):
+ #
+ # title: "Notification string"
+ # description: "Create a notification string with a timestamp."
+ # expression: "'New message received at ' + string(document.create_time)"
+ #
+ # The exact variables and functions that may be referenced within an expression
+ # are determined by the service that evaluates it. See the service
+ # documentation for additional information.
+ "description": "A String", # Optional. Description of the expression. This is a longer text which
# describes the expression, e.g. when hovered over it in a UI.
- "title": "A String", # An optional title for the expression, i.e. a short string describing
+ "expression": "A String", # Textual representation of an expression in Common Expression Language
+ # syntax.
+ "location": "A String", # Optional. String indicating the location of the expression for error
+ # reporting, e.g. a file name and a position in the file.
+ "title": "A String", # Optional. Title for the expression, i.e. a short string describing
# its purpose. This can be used e.g. in UIs which allow to enter the
# expression.
},
},
],
- "version": 42, # Deprecated.
"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
# prevent simultaneous updates of a policy from overwriting each other.
# It is strongly suggested that systems make use of the `etag` in the
@@ -693,8 +876,31 @@
# 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 blindly.
+ # **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.
+ "version": 42, # Specifies the format of the policy.
+ #
+ # 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.
}</pre>
</div>
@@ -703,7 +909,7 @@
<pre>Lists matching subscriptions.
Args:
- project: string, The name of the project in which to list subscriptions.
+ project: string, Required. The name of the project in which to list subscriptions.
Format is `projects/{project-id}`. (required)
pageSize: integer, Maximum number of subscriptions to return.
pageToken: string, The value returned by the last `ListSubscriptionsResponse`; indicates that
@@ -723,7 +929,7 @@
# `ListSubscriptionsRequest` to get more subscriptions.
"subscriptions": [ # The subscriptions that match the request.
{ # A subscription resource.
- "name": "A String", # The name of the subscription. It must have the format
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -732,7 +938,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -749,36 +955,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -795,10 +978,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -812,9 +1018,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -849,7 +1093,7 @@
</div>
<div class="method">
- <code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription, body, x__xgafv=None)</code>
+ <code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</code>
<pre>Modifies the ack deadline for a specific message. This method is useful
to indicate that more time is needed to process a message by the
subscriber, or to make the message available for redelivery if the
@@ -857,13 +1101,13 @@
subscription-level `ackDeadlineSeconds` used for subsequent messages.
Args:
- subscription: string, The name of the subscription.
+ subscription: string, Required. The name of the subscription.
Format is `projects/{project}/subscriptions/{sub}`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the ModifyAckDeadline method.
- "ackDeadlineSeconds": 42, # The new ack deadline with respect to the time this request was sent to
+ "ackDeadlineSeconds": 42, # Required. The new ack deadline with respect to the time this request was sent to
# the Pub/Sub system. For example, if the value is 10, the new
# ack deadline will expire 10 seconds after the `ModifyAckDeadline` call
# was made. Specifying zero might immediately make the message available for
@@ -871,7 +1115,7 @@
# increase in the rate of message redeliveries (that is, duplicates).
# The minimum deadline you can specify is 0 seconds.
# The maximum deadline you can specify is 600 seconds (10 minutes).
- "ackIds": [ # List of acknowledgment IDs.
+ "ackIds": [ # Required. List of acknowledgment IDs.
"A String",
],
}
@@ -897,7 +1141,7 @@
</div>
<div class="method">
- <code class="details" id="modifyPushConfig">modifyPushConfig(subscription, body, x__xgafv=None)</code>
+ <code class="details" id="modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</code>
<pre>Modifies the `PushConfig` for a specified subscription.
This may be used to change a push subscription to a pull one (signified by
@@ -906,41 +1150,18 @@
continuously through the call regardless of changes to the `PushConfig`.
Args:
- subscription: string, The name of the subscription.
+ subscription: string, Required. The name of the subscription.
Format is `projects/{project}/subscriptions/{sub}`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the ModifyPushConfig method.
- "pushConfig": { # Configuration for a push delivery endpoint. # The push configuration for future deliveries.
+ "pushConfig": { # Configuration for a push delivery endpoint. # Required. The push configuration for future deliveries.
#
# An empty `pushConfig` indicates that the Pub/Sub system should
# stop pushing messages from the given subscription and allow
# messages to be pulled and acknowledged - effectively pausing
# the subscription if `Pull` or `StreamingPull` is not called.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -957,6 +1178,29 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
@@ -983,25 +1227,25 @@
</div>
<div class="method">
- <code class="details" id="patch">patch(name, body, x__xgafv=None)</code>
+ <code class="details" id="patch">patch(name, body=None, x__xgafv=None)</code>
<pre>Updates an existing subscription. Note that certain properties of a
subscription, such as its topic, are not modifiable.
Args:
- name: string, The name of the subscription. It must have the format
+ name: string, Required. The name of the subscription. It must have the format
`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
start with a letter, and contain only letters (`[A-Za-z]`), numbers
(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
in length, and it must not start with `"goog"`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the UpdateSubscription method.
- "updateMask": "A String", # Indicates which fields in the provided subscription to update.
+ "updateMask": "A String", # Required. Indicates which fields in the provided subscription to update.
# Must be specified and non-empty.
- "subscription": { # A subscription resource. # The updated subscription object.
- "name": "A String", # The name of the subscription. It must have the format
+ "subscription": { # A subscription resource. # Required. The updated subscription object.
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -1010,7 +1254,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -1027,36 +1271,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -1073,10 +1294,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -1090,9 +1334,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -1119,7 +1401,7 @@
An object of the form:
{ # A subscription resource.
- "name": "A String", # The name of the subscription. It must have the format
+ "name": "A String", # Required. The name of the subscription. It must have the format
# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
# start with a letter, and contain only letters (`[A-Za-z]`), numbers
# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
@@ -1128,7 +1410,7 @@
"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
# the subscriber to acknowledge receipt before resending the message. In the
# interval after the message is delivered and before it is acknowledged, it
- # is considered to be <i>outstanding</i>. During that time period, the
+ # is considered to be <i>outstanding</i>. During that time period, the
# message will not be redelivered (on a best-effort basis).
#
# For pull subscriptions, this value is used as the initial value for the ack
@@ -1145,36 +1427,13 @@
#
# If the subscriber never acknowledges the message, the Pub/Sub
# system will eventually redeliver the message.
- "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
- # managing labels</a>.
+ "labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
+ # managing labels</a>.
"a_key": "A String",
},
"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
# used to configure it. An empty `pushConfig` signifies that the subscriber
# will pull and ack messages using API methods.
- "attributes": { # Endpoint configuration attributes.
- #
- # Every endpoint has a set of API supported attributes that can be used to
- # control different aspects of the message delivery.
- #
- # The currently supported attribute is `x-goog-version`, which you can
- # use to change the format of the pushed message. This attribute
- # indicates the version of the data expected by the endpoint. This
- # controls the shape of the pushed message (i.e., its fields and metadata).
- # The endpoint version is based on the version of the Pub/Sub API.
- #
- # If not present during the `CreateSubscription` call, it will default to
- # the version of the API used to make such call. If not present during a
- # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
- # calls will always return a valid version, even if the subscription was
- # created without this attribute.
- #
- # The possible values for this attribute are:
- #
- # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
- # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
- "a_key": "A String",
- },
"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
# `Authorization` header in the HTTP request for every pushed message.
# [OpenID Connect
@@ -1191,10 +1450,33 @@
# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
# have the iam.serviceAccounts.actAs permission for the service account.
},
+ "attributes": { # Endpoint configuration attributes that can be used to control different
+ # aspects of the message delivery.
+ #
+ # The only currently supported attribute is `x-goog-version`, which you can
+ # use to change the format of the pushed message. This attribute
+ # indicates the version of the data expected by the endpoint. This
+ # controls the shape of the pushed message (i.e., its fields and metadata).
+ #
+ # If not present during the `CreateSubscription` call, it will default to
+ # the version of the Pub/Sub API used to make such call. If not present in a
+ # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ # calls will always return a valid version, even if the subscription was
+ # created without this attribute.
+ #
+ # The only supported values for the `x-goog-version` attribute are:
+ #
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ #
+ # For example:
+ # <pre><code>attributes { "x-goog-version": "v1" } </code></pre>
+ "a_key": "A String",
+ },
"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
# For example, a Webhook endpoint might use "https://example.com/push".
},
- "topic": "A String", # The name of the topic from which this subscription is receiving messages.
+ "topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.
# Format is `projects/{project}/topics/{topic}`.
# The value of this field will be `_deleted-topic_` if the topic has been
# deleted.
@@ -1208,9 +1490,47 @@
# messages are not expunged from the subscription's backlog, even if they are
# acknowledged, until they fall out of the `message_retention_duration`
# window. This must be true if you would like to
- # <a
- # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
- # Seek to a timestamp</a>.
+ # <a
+ # href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+ # Seek to a timestamp</a>.
+ "deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in
+ # this subscription. If dead_letter_policy is not set, dead lettering
+ # is disabled.
+ #
+ # The Cloud Pub/Sub service account associated with this subscriptions's
+ # parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Acknowledge() messages on this subscription.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
+ # dead lettered multiple times.
+ #
+ # If validation on any of the fields fails at subscription creation/updation,
+ # the create/update subscription request will fail.
+ "deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.
+ # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ # account associated with the enclosing subscription's parent project (i.e.,
+ # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ # permission to Publish() to this topic.
+ #
+ # The operation will fail if the topic does not exist.
+ # Users should ensure that there is a subscription attached to this topic
+ # since messages published to a topic with no subscriptions are lost.
+ "maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be
+ # between 5 and 100.
+ #
+ # The number of delivery attempts is defined as 1 + (the sum of number of
+ # NACKs and number of times the acknowledgement deadline has been exceeded
+ # for the message).
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ # client libraries may automatically extend ack_deadlines.
+ #
+ # This field will be honored on a best effort basis.
+ #
+ # If this parameter is 0, a default value of 5 is used.
+ },
"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.
# A subscription is considered active as long as any connected subscriber is
# successfully consuming messages from the subscription or is issuing
@@ -1229,24 +1549,28 @@
</div>
<div class="method">
- <code class="details" id="pull">pull(subscription, body, x__xgafv=None)</code>
+ <code class="details" id="pull">pull(subscription, body=None, x__xgafv=None)</code>
<pre>Pulls messages from the server. The server may return `UNAVAILABLE` if
there are too many concurrent pull requests pending for the given
subscription.
Args:
- subscription: string, The subscription from which messages should be pulled.
+ subscription: string, Required. The subscription from which messages should be pulled.
Format is `projects/{project}/subscriptions/{sub}`. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the `Pull` method.
- "returnImmediately": True or False, # If this field set to true, the system will respond immediately even if
+ "returnImmediately": True or False, # Optional. If this field set to true, the system will respond immediately even if
# it there are no messages available to return in the `Pull` response.
# Otherwise, the system may wait (for a bounded amount of time) until at
- # least one message is available, rather than returning no messages.
- "maxMessages": 42, # The maximum number of messages returned for this request. The Pub/Sub
- # system may return fewer than the number specified.
+ # least one message is available, rather than returning no messages. Warning:
+ # setting this field to `true` is discouraged because it adversely impacts
+ # the performance of `Pull` operations. We recommend that users do not set
+ # this field.
+ "maxMessages": 42, # Required. The maximum number of messages to return for this request. Must be a
+ # positive integer. The Pub/Sub system may return fewer than the number
+ # specified.
}
x__xgafv: string, V1 error format.
@@ -1268,11 +1592,12 @@
# message must contain either a non-empty data field or at least one attribute.
# Note that client libraries represent this object differently
# depending on the language. See the corresponding
- # <a href="https://cloud.google.com/pubsub/docs/reference/libraries">client
- # library documentation</a> for more information. See
- # <a href="https://cloud.google.com/pubsub/quotas">Quotas and limits</a>
+ # <a href="https://cloud.google.com/pubsub/docs/reference/libraries">client
+ # library documentation</a> for more information. See
+ # <a href="https://cloud.google.com/pubsub/quotas">Quotas and limits</a>
# for more information about message limits.
- "attributes": { # Optional attributes for this message.
+ "attributes": { # Attributes for this message. If this field is empty, the message must
+ # contain non-empty data.
"a_key": "A String",
},
"data": "A String", # The message data field. If this field is empty, the message must contain
@@ -1285,16 +1610,32 @@
# subscriber that receives a `PubsubMessage` via a `Pull` call or a push
# delivery. It must not be populated by the publisher in a `Publish` call.
},
+ "deliveryAttempt": 42, # Delivery attempt counter is 1 + (the sum of number of NACKs and number of
+ # ack_deadline exceeds) for this message.
+ #
+ # A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
+ # exceeds event is whenever a message is not acknowledged within
+ # ack_deadline. Note that ack_deadline is initially
+ # Subscription.ackDeadlineSeconds, but may get extended automatically by
+ # the client library.
+ #
+ # The first delivery of a given message will have this value as 1. The value
+ # is calculated at best effort and is approximate.
+ #
+ # If a DeadLetterPolicy is not set on the subscription, this will be 0.
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+ # API might be changed in backward-incompatible ways and is not recommended
+ # for production use. It is not subject to any SLA or deprecation policy.
},
],
}</pre>
</div>
<div class="method">
- <code class="details" id="seek">seek(subscription, body, x__xgafv=None)</code>
+ <code class="details" id="seek">seek(subscription, body=None, x__xgafv=None)</code>
<pre>Seeks an existing subscription to a point in time or to a given snapshot,
whichever is provided in the request. Snapshots are used in
-<a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
+<a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
operations, which allow
you to manage message acknowledgments in bulk. That is, you can set the
acknowledgment state of messages in an existing subscription to the state
@@ -1302,8 +1643,8 @@
must be on the same topic.
Args:
- subscription: string, The subscription to affect. (required)
- body: object, The request body. (required)
+ subscription: string, Required. The subscription to affect. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request for the `Seek` method.
@@ -1336,67 +1677,88 @@
</div>
<div class="method">
- <code class="details" id="setIamPolicy">setIamPolicy(resource, body, x__xgafv=None)</code>
+ <code class="details" id="setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</code>
<pre>Sets the access control policy on the specified resource. Replaces any
existing policy.
+Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and PERMISSION_DENIED
+
Args:
resource: string, REQUIRED: The resource for which the policy is being specified.
See the operation documentation for the appropriate value for this field. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request message for `SetIamPolicy` method.
- "policy": { # Defines an Identity and Access Management (IAM) policy. It is used to # REQUIRED: The complete policy to be applied to the `resource`. The size of
+ "policy": { # An Identity and Access Management (IAM) policy, which specifies access # 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.
- # specify access control policies for Cloud Platform resources.
+ # controls for Google Cloud resources.
#
#
- # A `Policy` consists of a list of `bindings`. A `binding` binds a list of
- # `members` to a `role`, where the members can be user accounts, Google groups,
- # Google domains, and service accounts. A `role` is a named list of permissions
- # defined by IAM.
+ # 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; each `role` can be an IAM predefined role or a user-created
+ # custom role.
#
- # **JSON Example**
+ # 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": [
# {
- # "role": "roles/owner",
+ # "role": "roles/resourcemanager.organizationAdmin",
# "members": [
# "user:mike@example.com",
# "group:admins@example.com",
# "domain:google.com",
- # "serviceAccount:my-other-app@appspot.gserviceaccount.com"
+ # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
# ]
# },
# {
- # "role": "roles/viewer",
- # "members": ["user:sean@example.com"]
+ # "role": "roles/resourcemanager.organizationViewer",
+ # "members": ["user:eve@example.com"],
+ # "condition": {
+ # "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
# }
#
- # **YAML Example**
+ # **YAML example:**
#
# bindings:
# - members:
# - user:mike@example.com
# - group:admins@example.com
# - domain:google.com
- # - serviceAccount:my-other-app@appspot.gserviceaccount.com
- # role: roles/owner
+ # - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ # role: roles/resourcemanager.organizationAdmin
# - members:
- # - user:sean@example.com
- # role: roles/viewer
- #
+ # - user:eve@example.com
+ # role: roles/resourcemanager.organizationViewer
+ # condition:
+ # 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).
- "bindings": [ # Associates a list of `members` to a `role`.
- # `bindings` with no members will result in an error.
+ # [IAM documentation](https://cloud.google.com/iam/docs/).
+ "bindings": [ # 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.
{ # Associates `members` with a `role`.
"role": "A String", # Role that is assigned to `members`.
# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
@@ -1410,7 +1772,7 @@
# who is authenticated with a Google account or a service account.
#
# * `user:{emailid}`: An email address that represents a specific Google
- # account. For example, `alice@gmail.com` .
+ # account. For example, `alice@example.com` .
#
#
# * `serviceAccount:{emailid}`: An email address that represents a service
@@ -1419,36 +1781,78 @@
# * `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`.
#
"A String",
],
- "condition": { # Represents an expression text. Example: # The condition that is associated with this binding.
+ "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
# NOTE: An unsatisfied condition will not allow user access via current
# binding. Different bindings, including their conditions, are examined
# independently.
+ # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
+ # are documented at https://github.com/google/cel-spec.
#
- # title: "User account presence"
- # description: "Determines whether the request has a user account"
- # expression: "size(request.user) > 0"
- "location": "A String", # An optional string indicating the location of the expression for error
- # reporting, e.g. a file name and a position in the file.
- "expression": "A String", # Textual representation of an expression in
- # Common Expression Language syntax.
- #
- # The application context of the containing message determines which
- # well-known feature set of CEL is supported.
- "description": "A String", # An optional description of the expression. This is a longer text which
+ # Example (Comparison):
+ #
+ # title: "Summary size limit"
+ # description: "Determines if a summary is less than 100 chars"
+ # expression: "document.summary.size() < 100"
+ #
+ # Example (Equality):
+ #
+ # title: "Requestor is owner"
+ # description: "Determines if requestor is the document owner"
+ # expression: "document.owner == request.auth.claims.email"
+ #
+ # Example (Logic):
+ #
+ # title: "Public documents"
+ # description: "Determine whether the document should be publicly visible"
+ # expression: "document.type != 'private' && document.type != 'internal'"
+ #
+ # Example (Data Manipulation):
+ #
+ # title: "Notification string"
+ # description: "Create a notification string with a timestamp."
+ # expression: "'New message received at ' + string(document.create_time)"
+ #
+ # The exact variables and functions that may be referenced within an expression
+ # are determined by the service that evaluates it. See the service
+ # documentation for additional information.
+ "description": "A String", # Optional. Description of the expression. This is a longer text which
# describes the expression, e.g. when hovered over it in a UI.
- "title": "A String", # An optional title for the expression, i.e. a short string describing
+ "expression": "A String", # Textual representation of an expression in Common Expression Language
+ # syntax.
+ "location": "A String", # Optional. String indicating the location of the expression for error
+ # reporting, e.g. a file name and a position in the file.
+ "title": "A String", # Optional. Title for the expression, i.e. a short string describing
# its purpose. This can be used e.g. in UIs which allow to enter the
# expression.
},
},
],
- "version": 42, # Deprecated.
"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
# prevent simultaneous updates of a policy from overwriting each other.
# It is strongly suggested that systems make use of the `etag` in the
@@ -1457,8 +1861,31 @@
# 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 blindly.
+ # **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.
+ "version": 42, # Specifies the format of the policy.
+ #
+ # 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.
},
}
@@ -1470,53 +1897,72 @@
Returns:
An object of the form:
- { # 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` consists of a list of `bindings`. A `binding` binds a list of
- # `members` to a `role`, where the members can be user accounts, Google groups,
- # Google domains, and service accounts. A `role` is a named list of permissions
- # defined by IAM.
+ # 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; each `role` can be an IAM predefined role or a user-created
+ # custom role.
#
- # **JSON Example**
+ # 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": [
# {
- # "role": "roles/owner",
+ # "role": "roles/resourcemanager.organizationAdmin",
# "members": [
# "user:mike@example.com",
# "group:admins@example.com",
# "domain:google.com",
- # "serviceAccount:my-other-app@appspot.gserviceaccount.com"
+ # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
# ]
# },
# {
- # "role": "roles/viewer",
- # "members": ["user:sean@example.com"]
+ # "role": "roles/resourcemanager.organizationViewer",
+ # "members": ["user:eve@example.com"],
+ # "condition": {
+ # "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
# }
#
- # **YAML Example**
+ # **YAML example:**
#
# bindings:
# - members:
# - user:mike@example.com
# - group:admins@example.com
# - domain:google.com
- # - serviceAccount:my-other-app@appspot.gserviceaccount.com
- # role: roles/owner
+ # - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ # role: roles/resourcemanager.organizationAdmin
# - members:
- # - user:sean@example.com
- # role: roles/viewer
- #
+ # - user:eve@example.com
+ # role: roles/resourcemanager.organizationViewer
+ # condition:
+ # 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).
- "bindings": [ # Associates a list of `members` to a `role`.
- # `bindings` with no members will result in an error.
+ # [IAM documentation](https://cloud.google.com/iam/docs/).
+ "bindings": [ # 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.
{ # Associates `members` with a `role`.
"role": "A String", # Role that is assigned to `members`.
# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
@@ -1530,7 +1976,7 @@
# who is authenticated with a Google account or a service account.
#
# * `user:{emailid}`: An email address that represents a specific Google
- # account. For example, `alice@gmail.com` .
+ # account. For example, `alice@example.com` .
#
#
# * `serviceAccount:{emailid}`: An email address that represents a service
@@ -1539,36 +1985,78 @@
# * `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`.
#
"A String",
],
- "condition": { # Represents an expression text. Example: # The condition that is associated with this binding.
+ "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
# NOTE: An unsatisfied condition will not allow user access via current
# binding. Different bindings, including their conditions, are examined
# independently.
+ # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
+ # are documented at https://github.com/google/cel-spec.
#
- # title: "User account presence"
- # description: "Determines whether the request has a user account"
- # expression: "size(request.user) > 0"
- "location": "A String", # An optional string indicating the location of the expression for error
- # reporting, e.g. a file name and a position in the file.
- "expression": "A String", # Textual representation of an expression in
- # Common Expression Language syntax.
- #
- # The application context of the containing message determines which
- # well-known feature set of CEL is supported.
- "description": "A String", # An optional description of the expression. This is a longer text which
+ # Example (Comparison):
+ #
+ # title: "Summary size limit"
+ # description: "Determines if a summary is less than 100 chars"
+ # expression: "document.summary.size() < 100"
+ #
+ # Example (Equality):
+ #
+ # title: "Requestor is owner"
+ # description: "Determines if requestor is the document owner"
+ # expression: "document.owner == request.auth.claims.email"
+ #
+ # Example (Logic):
+ #
+ # title: "Public documents"
+ # description: "Determine whether the document should be publicly visible"
+ # expression: "document.type != 'private' && document.type != 'internal'"
+ #
+ # Example (Data Manipulation):
+ #
+ # title: "Notification string"
+ # description: "Create a notification string with a timestamp."
+ # expression: "'New message received at ' + string(document.create_time)"
+ #
+ # The exact variables and functions that may be referenced within an expression
+ # are determined by the service that evaluates it. See the service
+ # documentation for additional information.
+ "description": "A String", # Optional. Description of the expression. This is a longer text which
# describes the expression, e.g. when hovered over it in a UI.
- "title": "A String", # An optional title for the expression, i.e. a short string describing
+ "expression": "A String", # Textual representation of an expression in Common Expression Language
+ # syntax.
+ "location": "A String", # Optional. String indicating the location of the expression for error
+ # reporting, e.g. a file name and a position in the file.
+ "title": "A String", # Optional. Title for the expression, i.e. a short string describing
# its purpose. This can be used e.g. in UIs which allow to enter the
# expression.
},
},
],
- "version": 42, # Deprecated.
"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
# prevent simultaneous updates of a policy from overwriting each other.
# It is strongly suggested that systems make use of the `etag` in the
@@ -1577,13 +2065,36 @@
# 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 blindly.
+ # **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.
+ "version": 42, # Specifies the format of the policy.
+ #
+ # 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.
}</pre>
</div>
<div class="method">
- <code class="details" id="testIamPermissions">testIamPermissions(resource, body, x__xgafv=None)</code>
+ <code class="details" id="testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</code>
<pre>Returns permissions that a caller has on the specified resource.
If the resource does not exist, this will return an empty set of
permissions, not a NOT_FOUND error.
@@ -1595,7 +2106,7 @@
Args:
resource: string, REQUIRED: The resource for which the policy detail is being requested.
See the operation documentation for the appropriate value for this field. (required)
- body: object, The request body. (required)
+ body: object, The request body.
The object takes the form of:
{ # Request message for `TestIamPermissions` method.