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