Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / c72efbc6b71c963997c5728d471c04ab33d95e4f / . / docs / dyn / pubsub_v1.projects.subscriptions.html
blob: 36216c6f41213304f1dd9aa565b4c567b6149152 [file] [log] [blame]
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]75<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>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]76<h2>Instance Methods</h2>
77<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]78 <code><a href="#acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]79<p class="firstline">Acknowledges the messages associated with the `ack_ids` in the</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]80<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]81 <code><a href="#create">create(name, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]82<p class="firstline">Creates a subscription to a given topic. See the</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]83<p class="toc_element">
Thomas Coffee2f245372017-03-27 10:39:26 -0700[diff] [blame]84 <code><a href="#delete">delete(subscription, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]85<p class="firstline">Deletes an existing subscription. All messages retained in the subscription</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]86<p class="toc_element">
Thomas Coffee2f245372017-03-27 10:39:26 -0700[diff] [blame]87 <code><a href="#get">get(subscription, x__xgafv=None)</a></code></p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]88<p class="firstline">Gets the configuration details of a subscription.</p>
89<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]90 <code><a href="#getIamPolicy">getIamPolicy(resource, options_requestedPolicyVersion=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]91<p class="firstline">Gets the access control policy for a resource.</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]92<p class="toc_element">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]93 <code><a href="#list">list(project, pageToken=None, pageSize=None, x__xgafv=None)</a></code></p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]94<p class="firstline">Lists matching subscriptions.</p>
95<p class="toc_element">
96 <code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
97<p class="firstline">Retrieves the next page of results.</p>
98<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]99 <code><a href="#modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]100<p class="firstline">Modifies the ack deadline for a specific message. This method is useful</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]101<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]102 <code><a href="#modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]103<p class="firstline">Modifies the `PushConfig` for a specified subscription.</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]104<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]105 <code><a href="#patch">patch(name, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]106<p class="firstline">Updates an existing subscription. Note that certain properties of a</p>
107<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]108 <code><a href="#pull">pull(subscription, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]109<p class="firstline">Pulls messages from the server. The server may return `UNAVAILABLE` if</p>
110<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]111 <code><a href="#seek">seek(subscription, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]112<p class="firstline">Seeks an existing subscription to a point in time or to a given snapshot,</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]113<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]114 <code><a href="#setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]115<p class="firstline">Sets the access control policy on the specified resource. Replaces any</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]116<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]117 <code><a href="#testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</a></code></p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]118<p class="firstline">Returns permissions that a caller has on the specified resource.</p>
119<h3>Method Details</h3>
120<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]121 <code class="details" id="acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]122 <pre>Acknowledges the messages associated with the `ack_ids` in the
123`AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages
124from the subscription.
125
126Acknowledging a message whose ack deadline has expired may succeed,
127but such a message may be redelivered later. Acknowledging a message more
128than once will not result in an error.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]129
130Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]131 subscription: string, Required. The subscription whose message is being acknowledged.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]132Format is `projects/{project}/subscriptions/{sub}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]133 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]134 The object takes the form of:
135
136{ # Request for the Acknowledge method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]137 &quot;ackIds&quot;: [ # Required. The acknowledgment ID for the messages being acknowledged that was returned
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]138 # by the Pub/Sub system in the `Pull` response. Must not be empty.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]139 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]140 ],
141 }
142
143 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]144 Allowed values
145 1 - v1 error format
146 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]147
148Returns:
149 An object of the form:
150
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]151 { # A generic empty message that you can re-use to avoid defining duplicated
152 # empty messages in your APIs. A typical example is to use it as the request
153 # or the response type of an API method. For instance:
154 #
155 # service Foo {
156 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
157 # }
158 #
159 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]160 }</pre>
161</div>
162
163<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]164 <code class="details" id="create">create(name, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]165 <pre>Creates a subscription to a given topic. See the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]166&lt;a href=&quot;https://cloud.google.com/pubsub/docs/admin#resource_names&quot;&gt;
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]167resource name rules&lt;/a&gt;.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]168If the subscription already exists, returns `ALREADY_EXISTS`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]169If the corresponding topic doesn&#x27;t exist, returns `NOT_FOUND`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]170
171If the name is not provided in the request, the server will assign a random
172name for this subscription on the same project as the topic, conforming
173to the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]174[resource name
175format](https://cloud.google.com/pubsub/docs/admin#resource_names). The
176generated name is populated in the returned Subscription object. Note that
177for REST API requests, you must specify a name in the request.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]178
179Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]180 name: string, Required. The name of the subscription. It must have the format
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]181`&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]182start with a letter, and contain only letters (`[A-Za-z]`), numbers
183(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
184plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]185in length, and it must not start with `&quot;goog&quot;`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]186 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]187 The object takes the form of:
188
189{ # A subscription resource.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]190 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
191 # used to configure it. An empty `pushConfig` signifies that the subscriber
192 # will pull and ack messages using API methods.
193 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
194 # aspects of the message delivery.
195 #
196 # The only currently supported attribute is `x-goog-version`, which you can
197 # use to change the format of the pushed message. This attribute
198 # indicates the version of the data expected by the endpoint. This
199 # controls the shape of the pushed message (i.e., its fields and metadata).
200 #
201 # If not present during the `CreateSubscription` call, it will default to
202 # the version of the Pub/Sub API used to make such call. If not present in a
203 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
204 # calls will always return a valid version, even if the subscription was
205 # created without this attribute.
206 #
207 # The only supported values for the `x-goog-version` attribute are:
208 #
209 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
210 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
211 #
212 # For example:
213 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]214 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]215 },
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]216 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
217 # For example, a Webhook endpoint might use `https://example.com/push`.
218 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
219 # `Authorization` header in the HTTP request for every pushed message.
220 # [OpenID Connect
221 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
222 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
223 # identifies the recipients that the JWT is intended for. The audience
224 # value is a single case-sensitive string. Having multiple values (array)
225 # for the audience field is not supported. More info about the OIDC JWT
226 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
227 # Note: if not specified, the Push endpoint URL will be used.
228 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
229 # email](https://cloud.google.com/iam/docs/service-accounts)
230 # to be used for generating the OIDC token. The caller (for
231 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
232 # have the iam.serviceAccounts.actAs permission for the service account.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]233 },
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]234 },
235 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
236 # then only `PubsubMessage`s whose `attributes` field matches the filter are
237 # delivered on this subscription. If empty, then no messages are filtered
238 # out.
239 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
240 # API might be changed in backward-incompatible ways and is not recommended
241 # for production use. It is not subject to any SLA or deprecation policy.
242 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
243 # the subscriber to acknowledge receipt before resending the message. In the
244 # interval after the message is delivered and before it is acknowledged, it
245 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
246 # message will not be redelivered (on a best-effort basis).
247 #
248 # For pull subscriptions, this value is used as the initial value for the ack
249 # deadline. To override this value for a given message, call
250 # `ModifyAckDeadline` with the corresponding `ack_id` if using
251 # non-streaming pull or send the `ack_id` in a
252 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
253 # The minimum custom deadline you can specify is 10 seconds.
254 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
255 # If this parameter is 0, a default value of 10 seconds is used.
256 #
257 # For push delivery, this value is also used to set the request timeout for
258 # the call to the push endpoint.
259 #
260 # If the subscriber never acknowledges the message, the Pub/Sub
261 # system will eventually redeliver the message.
262 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
263 # from the moment a message is published.
264 # If `retain_acked_messages` is true, then this also configures the retention
265 # of acknowledged messages, and thus configures how far back in time a `Seek`
266 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
267 # minutes.
268 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
269 # messages are not expunged from the subscription&#x27;s backlog, even if they are
270 # acknowledged, until they fall out of the `message_retention_duration`
271 # window. This must be true if you would like to
272 # &lt;a
273 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
274 # Seek to a timestamp&lt;/a&gt;.
275 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
276 # managing labels&lt;/a&gt;.
277 &quot;a_key&quot;: &quot;A String&quot;,
278 },
279 &quot;deadLetterPolicy&quot;: { # 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
280 # this subscription. If dead_letter_policy is not set, dead lettering
281 # is disabled.
282 #
283 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
284 # parent project (i.e.,
285 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
286 # permission to Acknowledge() messages on this subscription.
287 # dead lettered multiple times.
288 #
289 # If validation on any of the fields fails at subscription creation/updation,
290 # the create/update subscription request will fail.
291 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
292 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
293 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]294 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]295 # permission to Publish() to this topic.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]296 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]297 # The operation will fail if the topic does not exist.
298 # Users should ensure that there is a subscription attached to this topic
299 # since messages published to a topic with no subscriptions are lost.
300 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
301 # between 5 and 100.
302 #
303 # The number of delivery attempts is defined as 1 + (the sum of number of
304 # NACKs and number of times the acknowledgement deadline has been exceeded
305 # for the message).
306 #
307 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
308 # client libraries may automatically extend ack_deadlines.
309 #
310 # This field will be honored on a best effort basis.
311 #
312 # If this parameter is 0, a default value of 5 is used.
313 },
314 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
315 # A subscription is considered active as long as any connected subscriber is
316 # successfully consuming messages from the subscription or is issuing
317 # operations on the subscription. If `expiration_policy` is not set, a
318 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
319 # value for `expiration_policy.ttl` is 1 day.
320 # automatic resource deletion).
321 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
322 # resource expires if it is not active for a period of `ttl`. The definition
323 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
324 # and maximum allowed values for `ttl` depend on the type of the associated
325 # resource, as well. If `ttl` is not set, the associated resource never
326 # expires.
327 },
328 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
329 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
330 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
331 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
332 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
333 # in length, and it must not start with `&quot;goog&quot;`.
334 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
335 # Format is `projects/{project}/topics/{topic}`.
336 # The value of this field will be `_deleted-topic_` if the topic has been
337 # deleted.
338}
339
340 x__xgafv: string, V1 error format.
341 Allowed values
342 1 - v1 error format
343 2 - v2 error format
344
345Returns:
346 An object of the form:
347
348 { # A subscription resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]349 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]350 # used to configure it. An empty `pushConfig` signifies that the subscriber
351 # will pull and ack messages using API methods.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]352 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]353 # aspects of the message delivery.
354 #
355 # The only currently supported attribute is `x-goog-version`, which you can
356 # use to change the format of the pushed message. This attribute
357 # indicates the version of the data expected by the endpoint. This
358 # controls the shape of the pushed message (i.e., its fields and metadata).
359 #
360 # If not present during the `CreateSubscription` call, it will default to
361 # the version of the Pub/Sub API used to make such call. If not present in a
362 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
363 # calls will always return a valid version, even if the subscription was
364 # created without this attribute.
365 #
366 # The only supported values for the `x-goog-version` attribute are:
367 #
368 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
369 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
370 #
371 # For example:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]372 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
373 &quot;a_key&quot;: &quot;A String&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]374 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]375 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
376 # For example, a Webhook endpoint might use `https://example.com/push`.
377 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
378 # `Authorization` header in the HTTP request for every pushed message.
379 # [OpenID Connect
380 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
381 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
382 # identifies the recipients that the JWT is intended for. The audience
383 # value is a single case-sensitive string. Having multiple values (array)
384 # for the audience field is not supported. More info about the OIDC JWT
385 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
386 # Note: if not specified, the Push endpoint URL will be used.
387 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
388 # email](https://cloud.google.com/iam/docs/service-accounts)
389 # to be used for generating the OIDC token. The caller (for
390 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
391 # have the iam.serviceAccounts.actAs permission for the service account.
392 },
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]393 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]394 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
395 # then only `PubsubMessage`s whose `attributes` field matches the filter are
396 # delivered on this subscription. If empty, then no messages are filtered
397 # out.
398 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
399 # API might be changed in backward-incompatible ways and is not recommended
400 # for production use. It is not subject to any SLA or deprecation policy.
401 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
402 # the subscriber to acknowledge receipt before resending the message. In the
403 # interval after the message is delivered and before it is acknowledged, it
404 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
405 # message will not be redelivered (on a best-effort basis).
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]406 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]407 # For pull subscriptions, this value is used as the initial value for the ack
408 # deadline. To override this value for a given message, call
409 # `ModifyAckDeadline` with the corresponding `ack_id` if using
410 # non-streaming pull or send the `ack_id` in a
411 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
412 # The minimum custom deadline you can specify is 10 seconds.
413 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
414 # If this parameter is 0, a default value of 10 seconds is used.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]415 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]416 # For push delivery, this value is also used to set the request timeout for
417 # the call to the push endpoint.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]418 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]419 # If the subscriber never acknowledges the message, the Pub/Sub
420 # system will eventually redeliver the message.
421 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]422 # from the moment a message is published.
423 # If `retain_acked_messages` is true, then this also configures the retention
424 # of acknowledged messages, and thus configures how far back in time a `Seek`
425 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
426 # minutes.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]427 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
428 # messages are not expunged from the subscription&#x27;s backlog, even if they are
429 # acknowledged, until they fall out of the `message_retention_duration`
430 # window. This must be true if you would like to
431 # &lt;a
432 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
433 # Seek to a timestamp&lt;/a&gt;.
434 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
435 # managing labels&lt;/a&gt;.
436 &quot;a_key&quot;: &quot;A String&quot;,
437 },
438 &quot;deadLetterPolicy&quot;: { # 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
439 # this subscription. If dead_letter_policy is not set, dead lettering
440 # is disabled.
441 #
442 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
443 # parent project (i.e.,
444 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
445 # permission to Acknowledge() messages on this subscription.
446 # dead lettered multiple times.
447 #
448 # If validation on any of the fields fails at subscription creation/updation,
449 # the create/update subscription request will fail.
450 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
451 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
452 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]453 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]454 # permission to Publish() to this topic.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]455 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]456 # The operation will fail if the topic does not exist.
457 # Users should ensure that there is a subscription attached to this topic
458 # since messages published to a topic with no subscriptions are lost.
459 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
460 # between 5 and 100.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]461 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]462 # The number of delivery attempts is defined as 1 + (the sum of number of
463 # NACKs and number of times the acknowledgement deadline has been exceeded
464 # for the message).
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]465 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]466 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
467 # client libraries may automatically extend ack_deadlines.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]468 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]469 # This field will be honored on a best effort basis.
470 #
471 # If this parameter is 0, a default value of 5 is used.
472 },
473 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
474 # A subscription is considered active as long as any connected subscriber is
475 # successfully consuming messages from the subscription or is issuing
476 # operations on the subscription. If `expiration_policy` is not set, a
477 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
478 # value for `expiration_policy.ttl` is 1 day.
479 # automatic resource deletion).
480 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
481 # resource expires if it is not active for a period of `ttl`. The definition
482 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
483 # and maximum allowed values for `ttl` depend on the type of the associated
484 # resource, as well. If `ttl` is not set, the associated resource never
485 # expires.
486 },
487 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
488 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
489 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
490 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
491 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
492 # in length, and it must not start with `&quot;goog&quot;`.
493 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
494 # Format is `projects/{project}/topics/{topic}`.
495 # The value of this field will be `_deleted-topic_` if the topic has been
496 # deleted.
497 }</pre>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]498</div>
499
500<div class="method">
Thomas Coffee2f245372017-03-27 10:39:26 -0700[diff] [blame]501 <code class="details" id="delete">delete(subscription, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]502 <pre>Deletes an existing subscription. All messages retained in the subscription
503are immediately dropped. Calls to `Pull` after deletion will return
504`NOT_FOUND`. After a subscription is deleted, a new one may be created with
505the same name, but the new one has no association with the old
506subscription or its topic unless the same topic is specified.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]507
508Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]509 subscription: string, Required. The subscription to delete.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]510Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]511 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]512 Allowed values
513 1 - v1 error format
514 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]515
516Returns:
517 An object of the form:
518
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]519 { # A generic empty message that you can re-use to avoid defining duplicated
520 # empty messages in your APIs. A typical example is to use it as the request
521 # or the response type of an API method. For instance:
522 #
523 # service Foo {
524 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
525 # }
526 #
527 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]528 }</pre>
529</div>
530
531<div class="method">
Thomas Coffee2f245372017-03-27 10:39:26 -0700[diff] [blame]532 <code class="details" id="get">get(subscription, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]533 <pre>Gets the configuration details of a subscription.
534
535Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]536 subscription: string, Required. The name of the subscription to get.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]537Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]538 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]539 Allowed values
540 1 - v1 error format
541 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]542
543Returns:
544 An object of the form:
545
546 { # A subscription resource.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]547 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
548 # used to configure it. An empty `pushConfig` signifies that the subscriber
549 # will pull and ack messages using API methods.
550 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
551 # aspects of the message delivery.
552 #
553 # The only currently supported attribute is `x-goog-version`, which you can
554 # use to change the format of the pushed message. This attribute
555 # indicates the version of the data expected by the endpoint. This
556 # controls the shape of the pushed message (i.e., its fields and metadata).
557 #
558 # If not present during the `CreateSubscription` call, it will default to
559 # the version of the Pub/Sub API used to make such call. If not present in a
560 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
561 # calls will always return a valid version, even if the subscription was
562 # created without this attribute.
563 #
564 # The only supported values for the `x-goog-version` attribute are:
565 #
566 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
567 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
568 #
569 # For example:
570 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]571 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]572 },
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]573 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
574 # For example, a Webhook endpoint might use `https://example.com/push`.
575 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
576 # `Authorization` header in the HTTP request for every pushed message.
577 # [OpenID Connect
578 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
579 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
580 # identifies the recipients that the JWT is intended for. The audience
581 # value is a single case-sensitive string. Having multiple values (array)
582 # for the audience field is not supported. More info about the OIDC JWT
583 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
584 # Note: if not specified, the Push endpoint URL will be used.
585 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
586 # email](https://cloud.google.com/iam/docs/service-accounts)
587 # to be used for generating the OIDC token. The caller (for
588 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
589 # have the iam.serviceAccounts.actAs permission for the service account.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]590 },
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]591 },
592 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
593 # then only `PubsubMessage`s whose `attributes` field matches the filter are
594 # delivered on this subscription. If empty, then no messages are filtered
595 # out.
596 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
597 # API might be changed in backward-incompatible ways and is not recommended
598 # for production use. It is not subject to any SLA or deprecation policy.
599 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
600 # the subscriber to acknowledge receipt before resending the message. In the
601 # interval after the message is delivered and before it is acknowledged, it
602 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
603 # message will not be redelivered (on a best-effort basis).
604 #
605 # For pull subscriptions, this value is used as the initial value for the ack
606 # deadline. To override this value for a given message, call
607 # `ModifyAckDeadline` with the corresponding `ack_id` if using
608 # non-streaming pull or send the `ack_id` in a
609 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
610 # The minimum custom deadline you can specify is 10 seconds.
611 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
612 # If this parameter is 0, a default value of 10 seconds is used.
613 #
614 # For push delivery, this value is also used to set the request timeout for
615 # the call to the push endpoint.
616 #
617 # If the subscriber never acknowledges the message, the Pub/Sub
618 # system will eventually redeliver the message.
619 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
620 # from the moment a message is published.
621 # If `retain_acked_messages` is true, then this also configures the retention
622 # of acknowledged messages, and thus configures how far back in time a `Seek`
623 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
624 # minutes.
625 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
626 # messages are not expunged from the subscription&#x27;s backlog, even if they are
627 # acknowledged, until they fall out of the `message_retention_duration`
628 # window. This must be true if you would like to
629 # &lt;a
630 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
631 # Seek to a timestamp&lt;/a&gt;.
632 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
633 # managing labels&lt;/a&gt;.
634 &quot;a_key&quot;: &quot;A String&quot;,
635 },
636 &quot;deadLetterPolicy&quot;: { # 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
637 # this subscription. If dead_letter_policy is not set, dead lettering
638 # is disabled.
639 #
640 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
641 # parent project (i.e.,
642 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
643 # permission to Acknowledge() messages on this subscription.
644 # dead lettered multiple times.
645 #
646 # If validation on any of the fields fails at subscription creation/updation,
647 # the create/update subscription request will fail.
648 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
649 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
650 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]651 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]652 # permission to Publish() to this topic.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]653 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]654 # The operation will fail if the topic does not exist.
655 # Users should ensure that there is a subscription attached to this topic
656 # since messages published to a topic with no subscriptions are lost.
657 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
658 # between 5 and 100.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]659 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]660 # The number of delivery attempts is defined as 1 + (the sum of number of
661 # NACKs and number of times the acknowledgement deadline has been exceeded
662 # for the message).
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]663 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]664 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
665 # client libraries may automatically extend ack_deadlines.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]666 #
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]667 # This field will be honored on a best effort basis.
668 #
669 # If this parameter is 0, a default value of 5 is used.
670 },
671 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
672 # A subscription is considered active as long as any connected subscriber is
673 # successfully consuming messages from the subscription or is issuing
674 # operations on the subscription. If `expiration_policy` is not set, a
675 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
676 # value for `expiration_policy.ttl` is 1 day.
677 # automatic resource deletion).
678 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
679 # resource expires if it is not active for a period of `ttl`. The definition
680 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
681 # and maximum allowed values for `ttl` depend on the type of the associated
682 # resource, as well. If `ttl` is not set, the associated resource never
683 # expires.
684 },
685 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
686 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
687 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
688 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
689 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
690 # in length, and it must not start with `&quot;goog&quot;`.
691 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
692 # Format is `projects/{project}/topics/{topic}`.
693 # The value of this field will be `_deleted-topic_` if the topic has been
694 # deleted.
695 }</pre>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]696</div>
697
698<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]699 <code class="details" id="getIamPolicy">getIamPolicy(resource, options_requestedPolicyVersion=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]700 <pre>Gets the access control policy for a resource.
701Returns an empty policy if the resource exists and does not have a policy
702set.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]703
704Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]705 resource: string, REQUIRED: The resource for which the policy is being requested.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]706See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]707 options_requestedPolicyVersion: integer, Optional. The policy format version to be returned.
708
709Valid values are 0, 1, and 3. Requests specifying an invalid value will be
710rejected.
711
712Requests for policies with any conditional bindings must specify version 3.
713Policies without any conditional bindings may specify any valid value or
714leave the field unset.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]715
716To learn which resources support conditions in their IAM policies, see the
717[IAM
718documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]719 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]720 Allowed values
721 1 - v1 error format
722 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]723
724Returns:
725 An object of the form:
726
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]727 { # An Identity and Access Management (IAM) policy, which specifies access
728 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]729 #
730 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]731 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
732 # `members` to a single `role`. Members can be user accounts, service accounts,
733 # Google groups, and domains (such as G Suite). A `role` is a named list of
734 # permissions; each `role` can be an IAM predefined role or a user-created
735 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]736 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]737 # For some types of Google Cloud resources, a `binding` can also specify a
738 # `condition`, which is a logical expression that allows access to a resource
739 # only if the expression evaluates to `true`. A condition can add constraints
740 # based on attributes of the request, the resource, or both. To learn which
741 # resources support conditions in their IAM policies, see the
742 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]743 #
744 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]745 #
746 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]747 # &quot;bindings&quot;: [
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]748 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]749 # &quot;role&quot;: &quot;roles/resourcemanager.organizationAdmin&quot;,
750 # &quot;members&quot;: [
751 # &quot;user:mike@example.com&quot;,
752 # &quot;group:admins@example.com&quot;,
753 # &quot;domain:google.com&quot;,
754 # &quot;serviceAccount:my-project-id@appspot.gserviceaccount.com&quot;
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]755 # ]
756 # },
757 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]758 # &quot;role&quot;: &quot;roles/resourcemanager.organizationViewer&quot;,
759 # &quot;members&quot;: [
760 # &quot;user:eve@example.com&quot;
761 # ],
762 # &quot;condition&quot;: {
763 # &quot;title&quot;: &quot;expirable access&quot;,
764 # &quot;description&quot;: &quot;Does not grant access after Sep 2020&quot;,
765 # &quot;expression&quot;: &quot;request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]766 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]767 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]768 # ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]769 # &quot;etag&quot;: &quot;BwWWja0YfJA=&quot;,
770 # &quot;version&quot;: 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]771 # }
772 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]773 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]774 #
775 # bindings:
776 # - members:
777 # - user:mike@example.com
778 # - group:admins@example.com
779 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]780 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
781 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]782 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]783 # - user:eve@example.com
784 # role: roles/resourcemanager.organizationViewer
785 # condition:
786 # title: expirable access
787 # description: Does not grant access after Sep 2020
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]788 # expression: request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]789 # - etag: BwWWja0YfJA=
790 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]791 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]792 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]793 # [IAM documentation](https://cloud.google.com/iam/docs/).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]794 &quot;bindings&quot;: [ # Associates a list of `members` to a `role`. Optionally, may specify a
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]795 # `condition` that determines how and when the `bindings` are applied. Each
796 # of the `bindings` must contain at least one member.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]797 { # Associates `members` with a `role`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]798 &quot;condition&quot;: { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
799 #
800 # If the condition evaluates to `true`, then this binding applies to the
801 # current request.
802 #
803 # If the condition evaluates to `false`, then this binding does not apply to
804 # the current request. However, a different role binding might grant the same
805 # role to one or more of the members in this binding.
806 #
807 # To learn which resources support conditions in their IAM policies, see the
808 # [IAM
809 # documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
810 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
811 # are documented at https://github.com/google/cel-spec.
812 #
813 # Example (Comparison):
814 #
815 # title: &quot;Summary size limit&quot;
816 # description: &quot;Determines if a summary is less than 100 chars&quot;
817 # expression: &quot;document.summary.size() &lt; 100&quot;
818 #
819 # Example (Equality):
820 #
821 # title: &quot;Requestor is owner&quot;
822 # description: &quot;Determines if requestor is the document owner&quot;
823 # expression: &quot;document.owner == request.auth.claims.email&quot;
824 #
825 # Example (Logic):
826 #
827 # title: &quot;Public documents&quot;
828 # description: &quot;Determine whether the document should be publicly visible&quot;
829 # expression: &quot;document.type != &#x27;private&#x27; &amp;&amp; document.type != &#x27;internal&#x27;&quot;
830 #
831 # Example (Data Manipulation):
832 #
833 # title: &quot;Notification string&quot;
834 # description: &quot;Create a notification string with a timestamp.&quot;
835 # expression: &quot;&#x27;New message received at &#x27; + string(document.create_time)&quot;
836 #
837 # The exact variables and functions that may be referenced within an expression
838 # are determined by the service that evaluates it. See the service
839 # documentation for additional information.
840 &quot;location&quot;: &quot;A String&quot;, # Optional. String indicating the location of the expression for error
841 # reporting, e.g. a file name and a position in the file.
842 &quot;title&quot;: &quot;A String&quot;, # Optional. Title for the expression, i.e. a short string describing
843 # its purpose. This can be used e.g. in UIs which allow to enter the
844 # expression.
845 &quot;description&quot;: &quot;A String&quot;, # Optional. Description of the expression. This is a longer text which
846 # describes the expression, e.g. when hovered over it in a UI.
847 &quot;expression&quot;: &quot;A String&quot;, # Textual representation of an expression in Common Expression Language
848 # syntax.
849 },
850 &quot;members&quot;: [ # Specifies the identities requesting access for a Cloud Platform resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]851 # `members` can have the following values:
852 #
853 # * `allUsers`: A special identifier that represents anyone who is
854 # on the internet; with or without a Google account.
855 #
856 # * `allAuthenticatedUsers`: A special identifier that represents anyone
857 # who is authenticated with a Google account or a service account.
858 #
859 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]860 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]861 #
862 #
863 # * `serviceAccount:{emailid}`: An email address that represents a service
864 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
865 #
866 # * `group:{emailid}`: An email address that represents a Google group.
867 # For example, `admins@example.com`.
868 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]869 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
870 # identifier) representing a user that has been recently deleted. For
871 # example, `alice@example.com?uid=123456789012345678901`. If the user is
872 # recovered, this value reverts to `user:{emailid}` and the recovered user
873 # retains the role in the binding.
874 #
875 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
876 # unique identifier) representing a service account that has been recently
877 # deleted. For example,
878 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
879 # If the service account is undeleted, this value reverts to
880 # `serviceAccount:{emailid}` and the undeleted service account retains the
881 # role in the binding.
882 #
883 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
884 # identifier) representing a Google group that has been recently
885 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
886 # the group is recovered, this value reverts to `group:{emailid}` and the
887 # recovered group retains the role in the binding.
888 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]889 #
890 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]891 # users of that domain. For example, `google.com` or `example.com`.
892 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]893 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]894 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]895 &quot;role&quot;: &quot;A String&quot;, # Role that is assigned to `members`.
896 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]897 },
898 ],
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]899 &quot;etag&quot;: &quot;A String&quot;, # `etag` is used for optimistic concurrency control as a way to help
900 # prevent simultaneous updates of a policy from overwriting each other.
901 # It is strongly suggested that systems make use of the `etag` in the
902 # read-modify-write cycle to perform policy updates in order to avoid race
903 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
904 # systems are expected to put that etag in the request to `setIamPolicy` to
905 # ensure that their change will be applied to the same version of the policy.
906 #
907 # **Important:** If you use IAM Conditions, you must include the `etag` field
908 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
909 # you to overwrite a version `3` policy with a version `1` policy, and all of
910 # the conditions in the version `3` policy are lost.
911 &quot;version&quot;: 42, # Specifies the format of the policy.
912 #
913 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
914 # are rejected.
915 #
916 # Any operation that affects conditional role bindings must specify version
917 # `3`. This requirement applies to the following operations:
918 #
919 # * Getting a policy that includes a conditional role binding
920 # * Adding a conditional role binding to a policy
921 # * Changing a conditional role binding in a policy
922 # * Removing any role binding, with or without a condition, from a policy
923 # that includes conditions
924 #
925 # **Important:** If you use IAM Conditions, you must include the `etag` field
926 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
927 # you to overwrite a version `3` policy with a version `1` policy, and all of
928 # the conditions in the version `3` policy are lost.
929 #
930 # If a policy does not include any conditions, operations on that policy may
931 # specify any valid version or leave the field unset.
932 #
933 # To learn which resources support conditions in their IAM policies, see the
934 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]935 }</pre>
936</div>
937
938<div class="method">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]939 <code class="details" id="list">list(project, pageToken=None, pageSize=None, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]940 <pre>Lists matching subscriptions.
941
942Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]943 project: string, Required. The name of the project in which to list subscriptions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]944Format is `projects/{project-id}`. (required)
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]945 pageToken: string, The value returned by the last `ListSubscriptionsResponse`; indicates that
946this is a continuation of a prior `ListSubscriptions` call, and that the
947system should return the next page of data.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]948 pageSize: integer, Maximum number of subscriptions to return.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]949 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]950 Allowed values
951 1 - v1 error format
952 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]953
954Returns:
955 An object of the form:
956
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]957 { # Response for the `ListSubscriptions` method.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]958 &quot;subscriptions&quot;: [ # The subscriptions that match the request.
959 { # A subscription resource.
960 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
961 # used to configure it. An empty `pushConfig` signifies that the subscriber
962 # will pull and ack messages using API methods.
963 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
964 # aspects of the message delivery.
965 #
966 # The only currently supported attribute is `x-goog-version`, which you can
967 # use to change the format of the pushed message. This attribute
968 # indicates the version of the data expected by the endpoint. This
969 # controls the shape of the pushed message (i.e., its fields and metadata).
970 #
971 # If not present during the `CreateSubscription` call, it will default to
972 # the version of the Pub/Sub API used to make such call. If not present in a
973 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
974 # calls will always return a valid version, even if the subscription was
975 # created without this attribute.
976 #
977 # The only supported values for the `x-goog-version` attribute are:
978 #
979 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
980 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
981 #
982 # For example:
983 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
984 &quot;a_key&quot;: &quot;A String&quot;,
985 },
986 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
987 # For example, a Webhook endpoint might use `https://example.com/push`.
988 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
989 # `Authorization` header in the HTTP request for every pushed message.
990 # [OpenID Connect
991 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
992 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
993 # identifies the recipients that the JWT is intended for. The audience
994 # value is a single case-sensitive string. Having multiple values (array)
995 # for the audience field is not supported. More info about the OIDC JWT
996 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
997 # Note: if not specified, the Push endpoint URL will be used.
998 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
999 # email](https://cloud.google.com/iam/docs/service-accounts)
1000 # to be used for generating the OIDC token. The caller (for
1001 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
1002 # have the iam.serviceAccounts.actAs permission for the service account.
1003 },
1004 },
1005 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
1006 # then only `PubsubMessage`s whose `attributes` field matches the filter are
1007 # delivered on this subscription. If empty, then no messages are filtered
1008 # out.
1009 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
1010 # API might be changed in backward-incompatible ways and is not recommended
1011 # for production use. It is not subject to any SLA or deprecation policy.
1012 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
1013 # the subscriber to acknowledge receipt before resending the message. In the
1014 # interval after the message is delivered and before it is acknowledged, it
1015 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
1016 # message will not be redelivered (on a best-effort basis).
1017 #
1018 # For pull subscriptions, this value is used as the initial value for the ack
1019 # deadline. To override this value for a given message, call
1020 # `ModifyAckDeadline` with the corresponding `ack_id` if using
1021 # non-streaming pull or send the `ack_id` in a
1022 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
1023 # The minimum custom deadline you can specify is 10 seconds.
1024 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
1025 # If this parameter is 0, a default value of 10 seconds is used.
1026 #
1027 # For push delivery, this value is also used to set the request timeout for
1028 # the call to the push endpoint.
1029 #
1030 # If the subscriber never acknowledges the message, the Pub/Sub
1031 # system will eventually redeliver the message.
1032 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
1033 # from the moment a message is published.
1034 # If `retain_acked_messages` is true, then this also configures the retention
1035 # of acknowledged messages, and thus configures how far back in time a `Seek`
1036 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
1037 # minutes.
1038 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
1039 # messages are not expunged from the subscription&#x27;s backlog, even if they are
1040 # acknowledged, until they fall out of the `message_retention_duration`
1041 # window. This must be true if you would like to
1042 # &lt;a
1043 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
1044 # Seek to a timestamp&lt;/a&gt;.
1045 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
1046 # managing labels&lt;/a&gt;.
1047 &quot;a_key&quot;: &quot;A String&quot;,
1048 },
1049 &quot;deadLetterPolicy&quot;: { # 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
1050 # this subscription. If dead_letter_policy is not set, dead lettering
1051 # is disabled.
1052 #
1053 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
1054 # parent project (i.e.,
1055 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1056 # permission to Acknowledge() messages on this subscription.
1057 # dead lettered multiple times.
1058 #
1059 # If validation on any of the fields fails at subscription creation/updation,
1060 # the create/update subscription request will fail.
1061 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
1062 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
1063 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
1064 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1065 # permission to Publish() to this topic.
1066 #
1067 # The operation will fail if the topic does not exist.
1068 # Users should ensure that there is a subscription attached to this topic
1069 # since messages published to a topic with no subscriptions are lost.
1070 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
1071 # between 5 and 100.
1072 #
1073 # The number of delivery attempts is defined as 1 + (the sum of number of
1074 # NACKs and number of times the acknowledgement deadline has been exceeded
1075 # for the message).
1076 #
1077 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
1078 # client libraries may automatically extend ack_deadlines.
1079 #
1080 # This field will be honored on a best effort basis.
1081 #
1082 # If this parameter is 0, a default value of 5 is used.
1083 },
1084 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
1085 # A subscription is considered active as long as any connected subscriber is
1086 # successfully consuming messages from the subscription or is issuing
1087 # operations on the subscription. If `expiration_policy` is not set, a
1088 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
1089 # value for `expiration_policy.ttl` is 1 day.
1090 # automatic resource deletion).
1091 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
1092 # resource expires if it is not active for a period of `ttl`. The definition
1093 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
1094 # and maximum allowed values for `ttl` depend on the type of the associated
1095 # resource, as well. If `ttl` is not set, the associated resource never
1096 # expires.
1097 },
1098 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
1099 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
1100 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
1101 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
1102 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
1103 # in length, and it must not start with `&quot;goog&quot;`.
1104 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
1105 # Format is `projects/{project}/topics/{topic}`.
1106 # The value of this field will be `_deleted-topic_` if the topic has been
1107 # deleted.
1108 },
1109 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1110 &quot;nextPageToken&quot;: &quot;A String&quot;, # If not empty, indicates that there may be more subscriptions that match
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1111 # the request; this value should be passed in a new
1112 # `ListSubscriptionsRequest` to get more subscriptions.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1113 }</pre>
1114</div>
1115
1116<div class="method">
1117 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
1118 <pre>Retrieves the next page of results.
1119
1120Args:
1121 previous_request: The request for the previous page. (required)
1122 previous_response: The response from the request for the previous page. (required)
1123
1124Returns:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1125 A request object that you can call &#x27;execute()&#x27; on to request the next
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1126 page. Returns None if there are no more items in the collection.
1127 </pre>
1128</div>
1129
1130<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1131 <code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1132 <pre>Modifies the ack deadline for a specific message. This method is useful
1133to indicate that more time is needed to process a message by the
1134subscriber, or to make the message available for redelivery if the
1135processing was interrupted. Note that this does not modify the
1136subscription-level `ackDeadlineSeconds` used for subsequent messages.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1137
1138Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1139 subscription: string, Required. The name of the subscription.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1140Format is `projects/{project}/subscriptions/{sub}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1141 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1142 The object takes the form of:
1143
1144{ # Request for the ModifyAckDeadline method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1145 &quot;ackDeadlineSeconds&quot;: 42, # Required. The new ack deadline with respect to the time this request was sent to
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1146 # the Pub/Sub system. For example, if the value is 10, the new
1147 # ack deadline will expire 10 seconds after the `ModifyAckDeadline` call
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1148 # was made. Specifying zero might immediately make the message available for
1149 # delivery to another subscriber client. This typically results in an
1150 # increase in the rate of message redeliveries (that is, duplicates).
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1151 # The minimum deadline you can specify is 0 seconds.
1152 # The maximum deadline you can specify is 600 seconds (10 minutes).
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]1153 &quot;ackIds&quot;: [ # Required. List of acknowledgment IDs.
1154 &quot;A String&quot;,
1155 ],
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1156 }
1157
1158 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1159 Allowed values
1160 1 - v1 error format
1161 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1162
1163Returns:
1164 An object of the form:
1165
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1166 { # A generic empty message that you can re-use to avoid defining duplicated
1167 # empty messages in your APIs. A typical example is to use it as the request
1168 # or the response type of an API method. For instance:
1169 #
1170 # service Foo {
1171 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
1172 # }
1173 #
1174 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1175 }</pre>
1176</div>
1177
1178<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1179 <code class="details" id="modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1180 <pre>Modifies the `PushConfig` for a specified subscription.
1181
1182This may be used to change a push subscription to a pull one (signified by
1183an empty `PushConfig`) or vice versa, or change the endpoint URL and other
1184attributes of a push subscription. Messages will accumulate for delivery
1185continuously through the call regardless of changes to the `PushConfig`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1186
1187Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1188 subscription: string, Required. The name of the subscription.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1189Format is `projects/{project}/subscriptions/{sub}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1190 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1191 The object takes the form of:
1192
1193{ # Request for the ModifyPushConfig method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1194 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # Required. The push configuration for future deliveries.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1195 #
1196 # An empty `pushConfig` indicates that the Pub/Sub system should
1197 # stop pushing messages from the given subscription and allow
1198 # messages to be pulled and acknowledged - effectively pausing
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1199 # the subscription if `Pull` or `StreamingPull` is not called.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1200 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1201 # aspects of the message delivery.
1202 #
1203 # The only currently supported attribute is `x-goog-version`, which you can
1204 # use to change the format of the pushed message. This attribute
1205 # indicates the version of the data expected by the endpoint. This
1206 # controls the shape of the pushed message (i.e., its fields and metadata).
1207 #
1208 # If not present during the `CreateSubscription` call, it will default to
1209 # the version of the Pub/Sub API used to make such call. If not present in a
1210 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
1211 # calls will always return a valid version, even if the subscription was
1212 # created without this attribute.
1213 #
1214 # The only supported values for the `x-goog-version` attribute are:
1215 #
1216 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
1217 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
1218 #
1219 # For example:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1220 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
1221 &quot;a_key&quot;: &quot;A String&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1222 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1223 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
1224 # For example, a Webhook endpoint might use `https://example.com/push`.
1225 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
1226 # `Authorization` header in the HTTP request for every pushed message.
1227 # [OpenID Connect
1228 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
1229 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
1230 # identifies the recipients that the JWT is intended for. The audience
1231 # value is a single case-sensitive string. Having multiple values (array)
1232 # for the audience field is not supported. More info about the OIDC JWT
1233 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
1234 # Note: if not specified, the Push endpoint URL will be used.
1235 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
1236 # email](https://cloud.google.com/iam/docs/service-accounts)
1237 # to be used for generating the OIDC token. The caller (for
1238 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
1239 # have the iam.serviceAccounts.actAs permission for the service account.
1240 },
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1241 },
1242 }
1243
1244 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1245 Allowed values
1246 1 - v1 error format
1247 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1248
1249Returns:
1250 An object of the form:
1251
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1252 { # A generic empty message that you can re-use to avoid defining duplicated
1253 # empty messages in your APIs. A typical example is to use it as the request
1254 # or the response type of an API method. For instance:
1255 #
1256 # service Foo {
1257 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
1258 # }
1259 #
1260 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1261 }</pre>
1262</div>
1263
1264<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1265 <code class="details" id="patch">patch(name, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1266 <pre>Updates an existing subscription. Note that certain properties of a
1267subscription, such as its topic, are not modifiable.
1268
1269Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1270 name: string, Required. The name of the subscription. It must have the format
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1271`&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1272start with a letter, and contain only letters (`[A-Za-z]`), numbers
1273(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
1274plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1275in length, and it must not start with `&quot;goog&quot;`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1276 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1277 The object takes the form of:
1278
1279{ # Request for the UpdateSubscription method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1280 &quot;updateMask&quot;: &quot;A String&quot;, # Required. Indicates which fields in the provided subscription to update.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1281 # Must be specified and non-empty.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1282 &quot;subscription&quot;: { # A subscription resource. # Required. The updated subscription object.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1283 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1284 # used to configure it. An empty `pushConfig` signifies that the subscriber
1285 # will pull and ack messages using API methods.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1286 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1287 # aspects of the message delivery.
1288 #
1289 # The only currently supported attribute is `x-goog-version`, which you can
1290 # use to change the format of the pushed message. This attribute
1291 # indicates the version of the data expected by the endpoint. This
1292 # controls the shape of the pushed message (i.e., its fields and metadata).
1293 #
1294 # If not present during the `CreateSubscription` call, it will default to
1295 # the version of the Pub/Sub API used to make such call. If not present in a
1296 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
1297 # calls will always return a valid version, even if the subscription was
1298 # created without this attribute.
1299 #
1300 # The only supported values for the `x-goog-version` attribute are:
1301 #
1302 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
1303 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
1304 #
1305 # For example:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1306 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
1307 &quot;a_key&quot;: &quot;A String&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1308 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1309 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
1310 # For example, a Webhook endpoint might use `https://example.com/push`.
1311 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
1312 # `Authorization` header in the HTTP request for every pushed message.
1313 # [OpenID Connect
1314 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
1315 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
1316 # identifies the recipients that the JWT is intended for. The audience
1317 # value is a single case-sensitive string. Having multiple values (array)
1318 # for the audience field is not supported. More info about the OIDC JWT
1319 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
1320 # Note: if not specified, the Push endpoint URL will be used.
1321 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
1322 # email](https://cloud.google.com/iam/docs/service-accounts)
1323 # to be used for generating the OIDC token. The caller (for
1324 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
1325 # have the iam.serviceAccounts.actAs permission for the service account.
1326 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1327 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1328 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
1329 # then only `PubsubMessage`s whose `attributes` field matches the filter are
1330 # delivered on this subscription. If empty, then no messages are filtered
1331 # out.
1332 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
1333 # API might be changed in backward-incompatible ways and is not recommended
1334 # for production use. It is not subject to any SLA or deprecation policy.
1335 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
1336 # the subscriber to acknowledge receipt before resending the message. In the
1337 # interval after the message is delivered and before it is acknowledged, it
1338 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
1339 # message will not be redelivered (on a best-effort basis).
1340 #
1341 # For pull subscriptions, this value is used as the initial value for the ack
1342 # deadline. To override this value for a given message, call
1343 # `ModifyAckDeadline` with the corresponding `ack_id` if using
1344 # non-streaming pull or send the `ack_id` in a
1345 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
1346 # The minimum custom deadline you can specify is 10 seconds.
1347 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
1348 # If this parameter is 0, a default value of 10 seconds is used.
1349 #
1350 # For push delivery, this value is also used to set the request timeout for
1351 # the call to the push endpoint.
1352 #
1353 # If the subscriber never acknowledges the message, the Pub/Sub
1354 # system will eventually redeliver the message.
1355 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1356 # from the moment a message is published.
1357 # If `retain_acked_messages` is true, then this also configures the retention
1358 # of acknowledged messages, and thus configures how far back in time a `Seek`
1359 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
1360 # minutes.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]1361 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
1362 # messages are not expunged from the subscription&#x27;s backlog, even if they are
1363 # acknowledged, until they fall out of the `message_retention_duration`
1364 # window. This must be true if you would like to
1365 # &lt;a
1366 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
1367 # Seek to a timestamp&lt;/a&gt;.
1368 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
1369 # managing labels&lt;/a&gt;.
1370 &quot;a_key&quot;: &quot;A String&quot;,
1371 },
1372 &quot;deadLetterPolicy&quot;: { # 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
1373 # this subscription. If dead_letter_policy is not set, dead lettering
1374 # is disabled.
1375 #
1376 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
1377 # parent project (i.e.,
1378 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1379 # permission to Acknowledge() messages on this subscription.
1380 # dead lettered multiple times.
1381 #
1382 # If validation on any of the fields fails at subscription creation/updation,
1383 # the create/update subscription request will fail.
1384 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
1385 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
1386 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
1387 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1388 # permission to Publish() to this topic.
1389 #
1390 # The operation will fail if the topic does not exist.
1391 # Users should ensure that there is a subscription attached to this topic
1392 # since messages published to a topic with no subscriptions are lost.
1393 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
1394 # between 5 and 100.
1395 #
1396 # The number of delivery attempts is defined as 1 + (the sum of number of
1397 # NACKs and number of times the acknowledgement deadline has been exceeded
1398 # for the message).
1399 #
1400 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
1401 # client libraries may automatically extend ack_deadlines.
1402 #
1403 # This field will be honored on a best effort basis.
1404 #
1405 # If this parameter is 0, a default value of 5 is used.
1406 },
1407 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
1408 # A subscription is considered active as long as any connected subscriber is
1409 # successfully consuming messages from the subscription or is issuing
1410 # operations on the subscription. If `expiration_policy` is not set, a
1411 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
1412 # value for `expiration_policy.ttl` is 1 day.
1413 # automatic resource deletion).
1414 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
1415 # resource expires if it is not active for a period of `ttl`. The definition
1416 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
1417 # and maximum allowed values for `ttl` depend on the type of the associated
1418 # resource, as well. If `ttl` is not set, the associated resource never
1419 # expires.
1420 },
1421 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
1422 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
1423 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
1424 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
1425 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
1426 # in length, and it must not start with `&quot;goog&quot;`.
1427 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
1428 # Format is `projects/{project}/topics/{topic}`.
1429 # The value of this field will be `_deleted-topic_` if the topic has been
1430 # deleted.
1431 },
1432 }
1433
1434 x__xgafv: string, V1 error format.
1435 Allowed values
1436 1 - v1 error format
1437 2 - v2 error format
1438
1439Returns:
1440 An object of the form:
1441
1442 { # A subscription resource.
1443 &quot;pushConfig&quot;: { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
1444 # used to configure it. An empty `pushConfig` signifies that the subscriber
1445 # will pull and ack messages using API methods.
1446 &quot;attributes&quot;: { # Endpoint configuration attributes that can be used to control different
1447 # aspects of the message delivery.
1448 #
1449 # The only currently supported attribute is `x-goog-version`, which you can
1450 # use to change the format of the pushed message. This attribute
1451 # indicates the version of the data expected by the endpoint. This
1452 # controls the shape of the pushed message (i.e., its fields and metadata).
1453 #
1454 # If not present during the `CreateSubscription` call, it will default to
1455 # the version of the Pub/Sub API used to make such call. If not present in a
1456 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
1457 # calls will always return a valid version, even if the subscription was
1458 # created without this attribute.
1459 #
1460 # The only supported values for the `x-goog-version` attribute are:
1461 #
1462 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
1463 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
1464 #
1465 # For example:
1466 # &lt;pre&gt;&lt;code&gt;attributes { &quot;x-goog-version&quot;: &quot;v1&quot; } &lt;/code&gt;&lt;/pre&gt;
1467 &quot;a_key&quot;: &quot;A String&quot;,
1468 },
1469 &quot;pushEndpoint&quot;: &quot;A String&quot;, # A URL locating the endpoint to which messages should be pushed.
1470 # For example, a Webhook endpoint might use `https://example.com/push`.
1471 &quot;oidcToken&quot;: { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
1472 # `Authorization` header in the HTTP request for every pushed message.
1473 # [OpenID Connect
1474 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
1475 &quot;audience&quot;: &quot;A String&quot;, # Audience to be used when generating OIDC token. The audience claim
1476 # identifies the recipients that the JWT is intended for. The audience
1477 # value is a single case-sensitive string. Having multiple values (array)
1478 # for the audience field is not supported. More info about the OIDC JWT
1479 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
1480 # Note: if not specified, the Push endpoint URL will be used.
1481 &quot;serviceAccountEmail&quot;: &quot;A String&quot;, # [Service account
1482 # email](https://cloud.google.com/iam/docs/service-accounts)
1483 # to be used for generating the OIDC token. The caller (for
1484 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
1485 # have the iam.serviceAccounts.actAs permission for the service account.
1486 },
1487 },
1488 &quot;filter&quot;: &quot;A String&quot;, # An expression written in the Cloud Pub/Sub filter language. If non-empty,
1489 # then only `PubsubMessage`s whose `attributes` field matches the filter are
1490 # delivered on this subscription. If empty, then no messages are filtered
1491 # out.
1492 # &lt;b&gt;EXPERIMENTAL:&lt;/b&gt; This feature is part of a closed alpha release. This
1493 # API might be changed in backward-incompatible ways and is not recommended
1494 # for production use. It is not subject to any SLA or deprecation policy.
1495 &quot;ackDeadlineSeconds&quot;: 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for
1496 # the subscriber to acknowledge receipt before resending the message. In the
1497 # interval after the message is delivered and before it is acknowledged, it
1498 # is considered to be &lt;i&gt;outstanding&lt;/i&gt;. During that time period, the
1499 # message will not be redelivered (on a best-effort basis).
1500 #
1501 # For pull subscriptions, this value is used as the initial value for the ack
1502 # deadline. To override this value for a given message, call
1503 # `ModifyAckDeadline` with the corresponding `ack_id` if using
1504 # non-streaming pull or send the `ack_id` in a
1505 # `StreamingModifyAckDeadlineRequest` if using streaming pull.
1506 # The minimum custom deadline you can specify is 10 seconds.
1507 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
1508 # If this parameter is 0, a default value of 10 seconds is used.
1509 #
1510 # For push delivery, this value is also used to set the request timeout for
1511 # the call to the push endpoint.
1512 #
1513 # If the subscriber never acknowledges the message, the Pub/Sub
1514 # system will eventually redeliver the message.
1515 &quot;messageRetentionDuration&quot;: &quot;A String&quot;, # How long to retain unacknowledged messages in the subscription&#x27;s backlog,
1516 # from the moment a message is published.
1517 # If `retain_acked_messages` is true, then this also configures the retention
1518 # of acknowledged messages, and thus configures how far back in time a `Seek`
1519 # can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
1520 # minutes.
1521 &quot;retainAckedMessages&quot;: True or False, # Indicates whether to retain acknowledged messages. If true, then
1522 # messages are not expunged from the subscription&#x27;s backlog, even if they are
1523 # acknowledged, until they fall out of the `message_retention_duration`
1524 # window. This must be true if you would like to
1525 # &lt;a
1526 # href=&quot;https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time&quot;&gt;
1527 # Seek to a timestamp&lt;/a&gt;.
1528 &quot;labels&quot;: { # See &lt;a href=&quot;https://cloud.google.com/pubsub/docs/labels&quot;&gt; Creating and
1529 # managing labels&lt;/a&gt;.
1530 &quot;a_key&quot;: &quot;A String&quot;,
1531 },
1532 &quot;deadLetterPolicy&quot;: { # 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
1533 # this subscription. If dead_letter_policy is not set, dead lettering
1534 # is disabled.
1535 #
1536 # The Cloud Pub/Sub service account associated with this subscriptions&#x27;s
1537 # parent project (i.e.,
1538 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1539 # permission to Acknowledge() messages on this subscription.
1540 # dead lettered multiple times.
1541 #
1542 # If validation on any of the fields fails at subscription creation/updation,
1543 # the create/update subscription request will fail.
1544 &quot;deadLetterTopic&quot;: &quot;A String&quot;, # The name of the topic to which dead letter messages should be published.
1545 # Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
1546 # account associated with the enclosing subscription&#x27;s parent project (i.e.,
1547 # service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
1548 # permission to Publish() to this topic.
1549 #
1550 # The operation will fail if the topic does not exist.
1551 # Users should ensure that there is a subscription attached to this topic
1552 # since messages published to a topic with no subscriptions are lost.
1553 &quot;maxDeliveryAttempts&quot;: 42, # The maximum number of delivery attempts for any message. The value must be
1554 # between 5 and 100.
1555 #
1556 # The number of delivery attempts is defined as 1 + (the sum of number of
1557 # NACKs and number of times the acknowledgement deadline has been exceeded
1558 # for the message).
1559 #
1560 # A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
1561 # client libraries may automatically extend ack_deadlines.
1562 #
1563 # This field will be honored on a best effort basis.
1564 #
1565 # If this parameter is 0, a default value of 5 is used.
1566 },
1567 &quot;expirationPolicy&quot;: { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription&#x27;s expiration.
1568 # A subscription is considered active as long as any connected subscriber is
1569 # successfully consuming messages from the subscription or is issuing
1570 # operations on the subscription. If `expiration_policy` is not set, a
1571 # *default policy* with `ttl` of 31 days will be used. The minimum allowed
1572 # value for `expiration_policy.ttl` is 1 day.
1573 # automatic resource deletion).
1574 &quot;ttl&quot;: &quot;A String&quot;, # Specifies the &quot;time-to-live&quot; duration for an associated resource. The
1575 # resource expires if it is not active for a period of `ttl`. The definition
1576 # of &quot;activity&quot; depends on the type of the associated resource. The minimum
1577 # and maximum allowed values for `ttl` depend on the type of the associated
1578 # resource, as well. If `ttl` is not set, the associated resource never
1579 # expires.
1580 },
1581 &quot;name&quot;: &quot;A String&quot;, # Required. The name of the subscription. It must have the format
1582 # `&quot;projects/{project}/subscriptions/{subscription}&quot;`. `{subscription}` must
1583 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
1584 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
1585 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
1586 # in length, and it must not start with `&quot;goog&quot;`.
1587 &quot;topic&quot;: &quot;A String&quot;, # Required. The name of the topic from which this subscription is receiving messages.
1588 # Format is `projects/{project}/topics/{topic}`.
1589 # The value of this field will be `_deleted-topic_` if the topic has been
1590 # deleted.
1591 }</pre>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1592</div>
1593
1594<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1595 <code class="details" id="pull">pull(subscription, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1596 <pre>Pulls messages from the server. The server may return `UNAVAILABLE` if
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1597there are too many concurrent pull requests pending for the given
1598subscription.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1599
1600Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1601 subscription: string, Required. The subscription from which messages should be pulled.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1602Format is `projects/{project}/subscriptions/{sub}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1603 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1604 The object takes the form of:
1605
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]1606{ # Request for the `Pull` method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1607 &quot;returnImmediately&quot;: True or False, # Optional. If this field set to true, the system will respond immediately even if
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1608 # it there are no messages available to return in the `Pull` response.
1609 # Otherwise, the system may wait (for a bounded amount of time) until at
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1610 # least one message is available, rather than returning no messages. Warning:
1611 # setting this field to `true` is discouraged because it adversely impacts
1612 # the performance of `Pull` operations. We recommend that users do not set
1613 # this field.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1614 &quot;maxMessages&quot;: 42, # Required. The maximum number of messages to return for this request. Must be a
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1615 # positive integer. The Pub/Sub system may return fewer than the number
1616 # specified.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1617 }
1618
1619 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1620 Allowed values
1621 1 - v1 error format
1622 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1623
1624Returns:
1625 An object of the form:
1626
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]1627 { # Response for the `Pull` method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1628 &quot;receivedMessages&quot;: [ # Received Pub/Sub messages. The list will be empty if there are no more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1629 # messages available in the backlog. For JSON, the response can be entirely
1630 # empty. The Pub/Sub system may return fewer than the `maxMessages` requested
1631 # even if there are more messages available in the backlog.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1632 { # A message and its corresponding acknowledgment ID.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1633 &quot;deliveryAttempt&quot;: 42, # The approximate number of times that Cloud Pub/Sub has attempted to deliver
1634 # the associated message to a subscriber.
1635 #
1636 # More precisely, this is 1 + (number of NACKs) +
1637 # (number of ack_deadline exceeds) for this message.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1638 #
1639 # A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
1640 # exceeds event is whenever a message is not acknowledged within
1641 # ack_deadline. Note that ack_deadline is initially
1642 # Subscription.ackDeadlineSeconds, but may get extended automatically by
1643 # the client library.
1644 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1645 # Upon the first delivery of a given message, `delivery_attempt` will have a
1646 # value of 1. The value is calculated at best effort and is approximate.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1647 #
1648 # If a DeadLetterPolicy is not set on the subscription, this will be 0.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1649 &quot;message&quot;: { # A message that is published by publishers and consumed by subscribers. The # The message.
1650 # message must contain either a non-empty data field or at least one attribute.
1651 # Note that client libraries represent this object differently
1652 # depending on the language. See the corresponding
1653 # &lt;a href=&quot;https://cloud.google.com/pubsub/docs/reference/libraries&quot;&gt;client
1654 # library documentation&lt;/a&gt; for more information. See
1655 # &lt;a href=&quot;https://cloud.google.com/pubsub/quotas&quot;&gt;Quotas and limits&lt;/a&gt;
1656 # for more information about message limits.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]1657 &quot;publishTime&quot;: &quot;A String&quot;, # The time at which the message was published, populated by the server when
1658 # it receives the `Publish` call. It must not be populated by the
1659 # publisher in a `Publish` call.
1660 &quot;data&quot;: &quot;A String&quot;, # The message data field. If this field is empty, the message must contain
1661 # at least one attribute.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1662 &quot;messageId&quot;: &quot;A String&quot;, # ID of this message, assigned by the server when the message is published.
1663 # Guaranteed to be unique within the topic. This value may be read by a
1664 # subscriber that receives a `PubsubMessage` via a `Pull` call or a push
1665 # delivery. It must not be populated by the publisher in a `Publish` call.
1666 &quot;attributes&quot;: { # Attributes for this message. If this field is empty, the message must
1667 # contain non-empty data.
1668 &quot;a_key&quot;: &quot;A String&quot;,
1669 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1670 },
1671 &quot;ackId&quot;: &quot;A String&quot;, # This ID can be used to acknowledge the received message.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1672 },
1673 ],
1674 }</pre>
1675</div>
1676
1677<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1678 <code class="details" id="seek">seek(subscription, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1679 <pre>Seeks an existing subscription to a point in time or to a given snapshot,
1680whichever is provided in the request. Snapshots are used in
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1681&lt;a href=&quot;https://cloud.google.com/pubsub/docs/replay-overview&quot;&gt;Seek&lt;/a&gt;
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1682operations, which allow
1683you to manage message acknowledgments in bulk. That is, you can set the
1684acknowledgment state of messages in an existing subscription to the state
1685captured by a snapshot. Note that both the subscription and the snapshot
1686must be on the same topic.
1687
1688Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1689 subscription: string, Required. The subscription to affect. (required)
1690 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1691 The object takes the form of:
1692
1693{ # Request for the `Seek` method.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]1694 &quot;snapshot&quot;: &quot;A String&quot;, # The snapshot to seek to. The snapshot&#x27;s topic must be the same as that of
1695 # the provided subscription.
1696 # Format is `projects/{project}/snapshots/{snap}`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1697 &quot;time&quot;: &quot;A String&quot;, # The time to seek to.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1698 # Messages retained in the subscription that were published before this
1699 # time are marked as acknowledged, and messages retained in the
1700 # subscription that were published after this time are marked as
1701 # unacknowledged. Note that this operation affects only those messages
1702 # retained in the subscription (configured by the combination of
1703 # `message_retention_duration` and `retain_acked_messages`). For example,
1704 # if `time` corresponds to a point before the message retention
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1705 # window (or to a point before the system&#x27;s notion of the subscription
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1706 # creation time), only retained messages will be marked as unacknowledged,
1707 # and already-expunged messages will not be restored.
1708 }
1709
1710 x__xgafv: string, V1 error format.
1711 Allowed values
1712 1 - v1 error format
1713 2 - v2 error format
1714
1715Returns:
1716 An object of the form:
1717
1718 { # Response for the `Seek` method (this response is empty).
1719 }</pre>
1720</div>
1721
1722<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1723 <code class="details" id="setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1724 <pre>Sets the access control policy on the specified resource. Replaces any
1725existing policy.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1726
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1727Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED` errors.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1728
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1729Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1730 resource: string, REQUIRED: The resource for which the policy is being specified.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]1731See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1732 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1733 The object takes the form of:
1734
1735{ # Request message for `SetIamPolicy` method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1736 &quot;policy&quot;: { # An Identity and Access Management (IAM) policy, which specifies access # REQUIRED: The complete policy to be applied to the `resource`. The size of
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1737 # the policy is limited to a few 10s of KB. An empty policy is a
1738 # valid policy but certain Cloud Platform services (such as Projects)
1739 # might reject them.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1740 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1741 #
1742 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1743 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
1744 # `members` to a single `role`. Members can be user accounts, service accounts,
1745 # Google groups, and domains (such as G Suite). A `role` is a named list of
1746 # permissions; each `role` can be an IAM predefined role or a user-created
1747 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1748 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1749 # For some types of Google Cloud resources, a `binding` can also specify a
1750 # `condition`, which is a logical expression that allows access to a resource
1751 # only if the expression evaluates to `true`. A condition can add constraints
1752 # based on attributes of the request, the resource, or both. To learn which
1753 # resources support conditions in their IAM policies, see the
1754 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1755 #
1756 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1757 #
1758 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1759 # &quot;bindings&quot;: [
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1760 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1761 # &quot;role&quot;: &quot;roles/resourcemanager.organizationAdmin&quot;,
1762 # &quot;members&quot;: [
1763 # &quot;user:mike@example.com&quot;,
1764 # &quot;group:admins@example.com&quot;,
1765 # &quot;domain:google.com&quot;,
1766 # &quot;serviceAccount:my-project-id@appspot.gserviceaccount.com&quot;
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1767 # ]
1768 # },
1769 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1770 # &quot;role&quot;: &quot;roles/resourcemanager.organizationViewer&quot;,
1771 # &quot;members&quot;: [
1772 # &quot;user:eve@example.com&quot;
1773 # ],
1774 # &quot;condition&quot;: {
1775 # &quot;title&quot;: &quot;expirable access&quot;,
1776 # &quot;description&quot;: &quot;Does not grant access after Sep 2020&quot;,
1777 # &quot;expression&quot;: &quot;request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1778 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1779 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1780 # ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1781 # &quot;etag&quot;: &quot;BwWWja0YfJA=&quot;,
1782 # &quot;version&quot;: 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1783 # }
1784 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1785 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1786 #
1787 # bindings:
1788 # - members:
1789 # - user:mike@example.com
1790 # - group:admins@example.com
1791 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1792 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
1793 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1794 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1795 # - user:eve@example.com
1796 # role: roles/resourcemanager.organizationViewer
1797 # condition:
1798 # title: expirable access
1799 # description: Does not grant access after Sep 2020
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1800 # expression: request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1801 # - etag: BwWWja0YfJA=
1802 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1803 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1804 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1805 # [IAM documentation](https://cloud.google.com/iam/docs/).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1806 &quot;bindings&quot;: [ # Associates a list of `members` to a `role`. Optionally, may specify a
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1807 # `condition` that determines how and when the `bindings` are applied. Each
1808 # of the `bindings` must contain at least one member.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]1809 { # Associates `members` with a `role`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1810 &quot;condition&quot;: { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
1811 #
1812 # If the condition evaluates to `true`, then this binding applies to the
1813 # current request.
1814 #
1815 # If the condition evaluates to `false`, then this binding does not apply to
1816 # the current request. However, a different role binding might grant the same
1817 # role to one or more of the members in this binding.
1818 #
1819 # To learn which resources support conditions in their IAM policies, see the
1820 # [IAM
1821 # documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
1822 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
1823 # are documented at https://github.com/google/cel-spec.
1824 #
1825 # Example (Comparison):
1826 #
1827 # title: &quot;Summary size limit&quot;
1828 # description: &quot;Determines if a summary is less than 100 chars&quot;
1829 # expression: &quot;document.summary.size() &lt; 100&quot;
1830 #
1831 # Example (Equality):
1832 #
1833 # title: &quot;Requestor is owner&quot;
1834 # description: &quot;Determines if requestor is the document owner&quot;
1835 # expression: &quot;document.owner == request.auth.claims.email&quot;
1836 #
1837 # Example (Logic):
1838 #
1839 # title: &quot;Public documents&quot;
1840 # description: &quot;Determine whether the document should be publicly visible&quot;
1841 # expression: &quot;document.type != &#x27;private&#x27; &amp;&amp; document.type != &#x27;internal&#x27;&quot;
1842 #
1843 # Example (Data Manipulation):
1844 #
1845 # title: &quot;Notification string&quot;
1846 # description: &quot;Create a notification string with a timestamp.&quot;
1847 # expression: &quot;&#x27;New message received at &#x27; + string(document.create_time)&quot;
1848 #
1849 # The exact variables and functions that may be referenced within an expression
1850 # are determined by the service that evaluates it. See the service
1851 # documentation for additional information.
1852 &quot;location&quot;: &quot;A String&quot;, # Optional. String indicating the location of the expression for error
1853 # reporting, e.g. a file name and a position in the file.
1854 &quot;title&quot;: &quot;A String&quot;, # Optional. Title for the expression, i.e. a short string describing
1855 # its purpose. This can be used e.g. in UIs which allow to enter the
1856 # expression.
1857 &quot;description&quot;: &quot;A String&quot;, # Optional. Description of the expression. This is a longer text which
1858 # describes the expression, e.g. when hovered over it in a UI.
1859 &quot;expression&quot;: &quot;A String&quot;, # Textual representation of an expression in Common Expression Language
1860 # syntax.
1861 },
1862 &quot;members&quot;: [ # Specifies the identities requesting access for a Cloud Platform resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1863 # `members` can have the following values:
1864 #
1865 # * `allUsers`: A special identifier that represents anyone who is
1866 # on the internet; with or without a Google account.
1867 #
1868 # * `allAuthenticatedUsers`: A special identifier that represents anyone
1869 # who is authenticated with a Google account or a service account.
1870 #
1871 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1872 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1873 #
1874 #
1875 # * `serviceAccount:{emailid}`: An email address that represents a service
1876 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
1877 #
1878 # * `group:{emailid}`: An email address that represents a Google group.
1879 # For example, `admins@example.com`.
1880 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1881 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
1882 # identifier) representing a user that has been recently deleted. For
1883 # example, `alice@example.com?uid=123456789012345678901`. If the user is
1884 # recovered, this value reverts to `user:{emailid}` and the recovered user
1885 # retains the role in the binding.
1886 #
1887 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
1888 # unique identifier) representing a service account that has been recently
1889 # deleted. For example,
1890 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
1891 # If the service account is undeleted, this value reverts to
1892 # `serviceAccount:{emailid}` and the undeleted service account retains the
1893 # role in the binding.
1894 #
1895 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
1896 # identifier) representing a Google group that has been recently
1897 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
1898 # the group is recovered, this value reverts to `group:{emailid}` and the
1899 # recovered group retains the role in the binding.
1900 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1901 #
1902 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1903 # users of that domain. For example, `google.com` or `example.com`.
1904 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1905 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1906 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1907 &quot;role&quot;: &quot;A String&quot;, # Role that is assigned to `members`.
1908 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1909 },
1910 ],
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]1911 &quot;etag&quot;: &quot;A String&quot;, # `etag` is used for optimistic concurrency control as a way to help
1912 # prevent simultaneous updates of a policy from overwriting each other.
1913 # It is strongly suggested that systems make use of the `etag` in the
1914 # read-modify-write cycle to perform policy updates in order to avoid race
1915 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
1916 # systems are expected to put that etag in the request to `setIamPolicy` to
1917 # ensure that their change will be applied to the same version of the policy.
1918 #
1919 # **Important:** If you use IAM Conditions, you must include the `etag` field
1920 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1921 # you to overwrite a version `3` policy with a version `1` policy, and all of
1922 # the conditions in the version `3` policy are lost.
1923 &quot;version&quot;: 42, # Specifies the format of the policy.
1924 #
1925 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
1926 # are rejected.
1927 #
1928 # Any operation that affects conditional role bindings must specify version
1929 # `3`. This requirement applies to the following operations:
1930 #
1931 # * Getting a policy that includes a conditional role binding
1932 # * Adding a conditional role binding to a policy
1933 # * Changing a conditional role binding in a policy
1934 # * Removing any role binding, with or without a condition, from a policy
1935 # that includes conditions
1936 #
1937 # **Important:** If you use IAM Conditions, you must include the `etag` field
1938 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1939 # you to overwrite a version `3` policy with a version `1` policy, and all of
1940 # the conditions in the version `3` policy are lost.
1941 #
1942 # If a policy does not include any conditions, operations on that policy may
1943 # specify any valid version or leave the field unset.
1944 #
1945 # To learn which resources support conditions in their IAM policies, see the
1946 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1947 },
1948 }
1949
1950 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1951 Allowed values
1952 1 - v1 error format
1953 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1954
1955Returns:
1956 An object of the form:
1957
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1958 { # An Identity and Access Management (IAM) policy, which specifies access
1959 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1960 #
1961 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1962 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
1963 # `members` to a single `role`. Members can be user accounts, service accounts,
1964 # Google groups, and domains (such as G Suite). A `role` is a named list of
1965 # permissions; each `role` can be an IAM predefined role or a user-created
1966 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1967 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1968 # For some types of Google Cloud resources, a `binding` can also specify a
1969 # `condition`, which is a logical expression that allows access to a resource
1970 # only if the expression evaluates to `true`. A condition can add constraints
1971 # based on attributes of the request, the resource, or both. To learn which
1972 # resources support conditions in their IAM policies, see the
1973 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1974 #
1975 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1976 #
1977 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1978 # &quot;bindings&quot;: [
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1979 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1980 # &quot;role&quot;: &quot;roles/resourcemanager.organizationAdmin&quot;,
1981 # &quot;members&quot;: [
1982 # &quot;user:mike@example.com&quot;,
1983 # &quot;group:admins@example.com&quot;,
1984 # &quot;domain:google.com&quot;,
1985 # &quot;serviceAccount:my-project-id@appspot.gserviceaccount.com&quot;
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1986 # ]
1987 # },
1988 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]1989 # &quot;role&quot;: &quot;roles/resourcemanager.organizationViewer&quot;,
1990 # &quot;members&quot;: [
1991 # &quot;user:eve@example.com&quot;
1992 # ],
1993 # &quot;condition&quot;: {
1994 # &quot;title&quot;: &quot;expirable access&quot;,
1995 # &quot;description&quot;: &quot;Does not grant access after Sep 2020&quot;,
1996 # &quot;expression&quot;: &quot;request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1997 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1998 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1999 # ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2000 # &quot;etag&quot;: &quot;BwWWja0YfJA=&quot;,
2001 # &quot;version&quot;: 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2002 # }
2003 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2004 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2005 #
2006 # bindings:
2007 # - members:
2008 # - user:mike@example.com
2009 # - group:admins@example.com
2010 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2011 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
2012 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2013 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2014 # - user:eve@example.com
2015 # role: roles/resourcemanager.organizationViewer
2016 # condition:
2017 # title: expirable access
2018 # description: Does not grant access after Sep 2020
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2019 # expression: request.time &lt; timestamp(&#x27;2020-10-01T00:00:00.000Z&#x27;)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2020 # - etag: BwWWja0YfJA=
2021 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2022 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2023 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2024 # [IAM documentation](https://cloud.google.com/iam/docs/).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2025 &quot;bindings&quot;: [ # Associates a list of `members` to a `role`. Optionally, may specify a
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2026 # `condition` that determines how and when the `bindings` are applied. Each
2027 # of the `bindings` must contain at least one member.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]2028 { # Associates `members` with a `role`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2029 &quot;condition&quot;: { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
2030 #
2031 # If the condition evaluates to `true`, then this binding applies to the
2032 # current request.
2033 #
2034 # If the condition evaluates to `false`, then this binding does not apply to
2035 # the current request. However, a different role binding might grant the same
2036 # role to one or more of the members in this binding.
2037 #
2038 # To learn which resources support conditions in their IAM policies, see the
2039 # [IAM
2040 # documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
2041 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
2042 # are documented at https://github.com/google/cel-spec.
2043 #
2044 # Example (Comparison):
2045 #
2046 # title: &quot;Summary size limit&quot;
2047 # description: &quot;Determines if a summary is less than 100 chars&quot;
2048 # expression: &quot;document.summary.size() &lt; 100&quot;
2049 #
2050 # Example (Equality):
2051 #
2052 # title: &quot;Requestor is owner&quot;
2053 # description: &quot;Determines if requestor is the document owner&quot;
2054 # expression: &quot;document.owner == request.auth.claims.email&quot;
2055 #
2056 # Example (Logic):
2057 #
2058 # title: &quot;Public documents&quot;
2059 # description: &quot;Determine whether the document should be publicly visible&quot;
2060 # expression: &quot;document.type != &#x27;private&#x27; &amp;&amp; document.type != &#x27;internal&#x27;&quot;
2061 #
2062 # Example (Data Manipulation):
2063 #
2064 # title: &quot;Notification string&quot;
2065 # description: &quot;Create a notification string with a timestamp.&quot;
2066 # expression: &quot;&#x27;New message received at &#x27; + string(document.create_time)&quot;
2067 #
2068 # The exact variables and functions that may be referenced within an expression
2069 # are determined by the service that evaluates it. See the service
2070 # documentation for additional information.
2071 &quot;location&quot;: &quot;A String&quot;, # Optional. String indicating the location of the expression for error
2072 # reporting, e.g. a file name and a position in the file.
2073 &quot;title&quot;: &quot;A String&quot;, # Optional. Title for the expression, i.e. a short string describing
2074 # its purpose. This can be used e.g. in UIs which allow to enter the
2075 # expression.
2076 &quot;description&quot;: &quot;A String&quot;, # Optional. Description of the expression. This is a longer text which
2077 # describes the expression, e.g. when hovered over it in a UI.
2078 &quot;expression&quot;: &quot;A String&quot;, # Textual representation of an expression in Common Expression Language
2079 # syntax.
2080 },
2081 &quot;members&quot;: [ # Specifies the identities requesting access for a Cloud Platform resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2082 # `members` can have the following values:
2083 #
2084 # * `allUsers`: A special identifier that represents anyone who is
2085 # on the internet; with or without a Google account.
2086 #
2087 # * `allAuthenticatedUsers`: A special identifier that represents anyone
2088 # who is authenticated with a Google account or a service account.
2089 #
2090 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2091 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2092 #
2093 #
2094 # * `serviceAccount:{emailid}`: An email address that represents a service
2095 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
2096 #
2097 # * `group:{emailid}`: An email address that represents a Google group.
2098 # For example, `admins@example.com`.
2099 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2100 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
2101 # identifier) representing a user that has been recently deleted. For
2102 # example, `alice@example.com?uid=123456789012345678901`. If the user is
2103 # recovered, this value reverts to `user:{emailid}` and the recovered user
2104 # retains the role in the binding.
2105 #
2106 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
2107 # unique identifier) representing a service account that has been recently
2108 # deleted. For example,
2109 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
2110 # If the service account is undeleted, this value reverts to
2111 # `serviceAccount:{emailid}` and the undeleted service account retains the
2112 # role in the binding.
2113 #
2114 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
2115 # identifier) representing a Google group that has been recently
2116 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
2117 # the group is recovered, this value reverts to `group:{emailid}` and the
2118 # recovered group retains the role in the binding.
2119 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2120 #
2121 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2122 # users of that domain. For example, `google.com` or `example.com`.
2123 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2124 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2125 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2126 &quot;role&quot;: &quot;A String&quot;, # Role that is assigned to `members`.
2127 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2128 },
2129 ],
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame]2130 &quot;etag&quot;: &quot;A String&quot;, # `etag` is used for optimistic concurrency control as a way to help
2131 # prevent simultaneous updates of a policy from overwriting each other.
2132 # It is strongly suggested that systems make use of the `etag` in the
2133 # read-modify-write cycle to perform policy updates in order to avoid race
2134 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
2135 # systems are expected to put that etag in the request to `setIamPolicy` to
2136 # ensure that their change will be applied to the same version of the policy.
2137 #
2138 # **Important:** If you use IAM Conditions, you must include the `etag` field
2139 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
2140 # you to overwrite a version `3` policy with a version `1` policy, and all of
2141 # the conditions in the version `3` policy are lost.
2142 &quot;version&quot;: 42, # Specifies the format of the policy.
2143 #
2144 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
2145 # are rejected.
2146 #
2147 # Any operation that affects conditional role bindings must specify version
2148 # `3`. This requirement applies to the following operations:
2149 #
2150 # * Getting a policy that includes a conditional role binding
2151 # * Adding a conditional role binding to a policy
2152 # * Changing a conditional role binding in a policy
2153 # * Removing any role binding, with or without a condition, from a policy
2154 # that includes conditions
2155 #
2156 # **Important:** If you use IAM Conditions, you must include the `etag` field
2157 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
2158 # you to overwrite a version `3` policy with a version `1` policy, and all of
2159 # the conditions in the version `3` policy are lost.
2160 #
2161 # If a policy does not include any conditions, operations on that policy may
2162 # specify any valid version or leave the field unset.
2163 #
2164 # To learn which resources support conditions in their IAM policies, see the
2165 # [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2166 }</pre>
2167</div>
2168
2169<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2170 <code class="details" id="testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2171 <pre>Returns permissions that a caller has on the specified resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2172If the resource does not exist, this will return an empty set of
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2173permissions, not a `NOT_FOUND` error.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2174
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]2175Note: This operation is designed to be used for building permission-aware
2176UIs and command-line tools, not for authorization checking. This operation
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2177may &quot;fail open&quot; without warning.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]2178
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2179Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2180 resource: string, REQUIRED: The resource for which the policy detail is being requested.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]2181See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2182 body: object, The request body.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2183 The object takes the form of:
2184
2185{ # Request message for `TestIamPermissions` method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2186 &quot;permissions&quot;: [ # The set of permissions to check for the `resource`. Permissions with
2187 # wildcards (such as &#x27;*&#x27; or &#x27;storage.*&#x27;) are not allowed. For more
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2188 # information see
2189 # [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2190 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2191 ],
2192 }
2193
2194 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2195 Allowed values
2196 1 - v1 error format
2197 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2198
2199Returns:
2200 An object of the form:
2201
2202 { # Response message for `TestIamPermissions` method.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2203 &quot;permissions&quot;: [ # A subset of `TestPermissionsRequest.permissions` that the caller is
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]2204 # allowed.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]2205 &quot;A String&quot;,
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]2206 ],
2207 }</pre>
2208</div>
2209
2210</body></html>