Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / dd49464a6262c0d1f71efcf11f131e2f591fe5f6 / . / docs / dyn / pubsub_v1beta2.projects.subscriptions.html
blob: 1de1b7c4c52c22efe1db9a7babea5a1af37fa21f [file] [log] [blame]
Craig Citroe633be12015-03-02 13:40:36 -0800[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_v1beta2.html">Cloud Pub/Sub API</a> . <a href="pubsub_v1beta2.projects.html">projects</a> . <a href="pubsub_v1beta2.projects.subscriptions.html">subscriptions</a></h1>
Craig Citroe633be12015-03-02 13:40:36 -0800[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>
Craig Citroe633be12015-03-02 13:40:36 -0800[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>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]82<p class="firstline">Creates a subscription to a given topic.</p>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]83<p class="toc_element">
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[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 pending messages in the subscription</p>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]86<p class="toc_element">
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]87 <code><a href="#get">get(subscription, x__xgafv=None)</a></code></p>
Craig Citroe633be12015-03-02 13:40:36 -0800[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>
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]92<p class="toc_element">
93 <code><a href="#list">list(project, pageSize=None, pageToken=None, x__xgafv=None)</a></code></p>
Craig Citroe633be12015-03-02 13:40:36 -0800[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>
Craig Citroe633be12015-03-02 13:40:36 -0800[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>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]104<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]105 <code><a href="#pull">pull(subscription, body=None, x__xgafv=None)</a></code></p>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]106<p class="firstline">Pulls messages from the server. Returns an empty list if there are no</p>
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]107<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]108 <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]109<p class="firstline">Sets the access control policy on the specified resource. Replaces any</p>
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]110<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]111 <code><a href="#testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</a></code></p>
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]112<p class="firstline">Returns permissions that a caller has on the specified resource.</p>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]113<h3>Method Details</h3>
114<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]115 <code class="details" id="acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]116 <pre>Acknowledges the messages associated with the `ack_ids` in the
117`AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages
118from the subscription.
119
120Acknowledging a message whose ack deadline has expired may succeed,
121but such a message may be redelivered later. Acknowledging a message more
122than once will not result in an error.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]123
124Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]125 subscription: string, The subscription whose message is being acknowledged. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]126 body: object, The request body.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]127 The object takes the form of:
128
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]129{ # Request for the Acknowledge method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]130 "ackIds": [ # The acknowledgment ID for the messages being acknowledged that was returned
131 # by the Pub/Sub system in the `Pull` response. Must not be empty.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]132 "A String",
133 ],
134 }
135
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]136 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]137 Allowed values
138 1 - v1 error format
139 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]140
141Returns:
142 An object of the form:
143
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]144 { # A generic empty message that you can re-use to avoid defining duplicated
145 # empty messages in your APIs. A typical example is to use it as the request
146 # or the response type of an API method. For instance:
147 #
148 # service Foo {
149 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
150 # }
151 #
152 # The JSON representation for `Empty` is empty JSON object `{}`.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]153 }</pre>
154</div>
155
156<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]157 <code class="details" id="create">create(name, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]158 <pre>Creates a subscription to a given topic.
159If the subscription already exists, returns `ALREADY_EXISTS`.
160If the corresponding topic doesn't exist, returns `NOT_FOUND`.
161
162If the name is not provided in the request, the server will assign a random
163name for this subscription on the same project as the topic. Note that
164for REST API requests, you must specify a name.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]165
166Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]167 name: string, The name of the subscription. It must have the format
168`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
169start with a letter, and contain only letters (`[A-Za-z]`), numbers
170(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
171plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
172in length, and it must not start with `"goog"`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]173 body: object, The request body.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]174 The object takes the form of:
175
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]176{ # A subscription resource.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]177 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
178 # before the subscriber should acknowledge the message. After message
179 # delivery but before the ack deadline expires and before the message is
180 # acknowledged, it is an outstanding message and will not be delivered
181 # again during that time (on a best-effort basis).
182 #
183 # For pull subscriptions, this value is used as the initial value for the ack
184 # deadline. To override this value for a given message, call
185 # `ModifyAckDeadline` with the corresponding `ack_id` if using pull.
186 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
187 #
188 # For push delivery, this value is also used to set the request timeout for
189 # the call to the push endpoint.
190 #
191 # If the subscriber never acknowledges the message, the Pub/Sub
192 # system will eventually redeliver the message.
193 #
194 # If this parameter is 0, a default value of 10 seconds is used.
195 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
196 # The value of this field will be `_deleted-topic_` if the topic has been
197 # deleted.
198 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
199 # used to configure it. An empty `pushConfig` signifies that the subscriber
200 # will pull and ack messages using API methods.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]201 "oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
202 # `Authorization` header in the HTTP request for every pushed message.
203 # [OpenID Connect
204 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
205 "audience": "A String", # Audience to be used when generating OIDC token. The audience claim
206 # identifies the recipients that the JWT is intended for. The audience
207 # value is a single case-sensitive string. Having multiple values (array)
208 # for the audience field is not supported. More info about the OIDC JWT
209 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
210 # Note: if not specified, the Push endpoint URL will be used.
211 "serviceAccountEmail": "A String", # [Service account
212 # email](https://cloud.google.com/iam/docs/service-accounts)
213 # to be used for generating the OIDC token. The caller (for
214 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
215 # have the iam.serviceAccounts.actAs permission for the service account.
216 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]217 "attributes": { # Endpoint configuration attributes.
218 #
219 # Every endpoint has a set of API supported attributes that can be used to
220 # control different aspects of the message delivery.
221 #
222 # The currently supported attribute is `x-goog-version`, which you can
223 # use to change the format of the push message. This attribute
224 # indicates the version of the data expected by the endpoint. This
225 # controls the shape of the envelope (i.e. its fields and metadata).
226 # The endpoint version is based on the version of the Pub/Sub
227 # API.
228 #
229 # If not present during the `CreateSubscription` call, it will default to
230 # the version of the API used to make such call. If not present during a
231 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
232 # calls will always return a valid version, even if the subscription was
233 # created without this attribute.
234 #
235 # The possible values for this attribute are:
236 #
237 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
238 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
239 "a_key": "A String",
240 },
241 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
242 # For example, a Webhook endpoint might use "https://example.com/push".
243 },
244 "name": "A String", # The name of the subscription. It must have the format
245 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
246 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
247 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
248 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
249 # in length, and it must not start with `"goog"`.
250}
251
252 x__xgafv: string, V1 error format.
253 Allowed values
254 1 - v1 error format
255 2 - v2 error format
256
257Returns:
258 An object of the form:
259
260 { # A subscription resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]261 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
262 # before the subscriber should acknowledge the message. After message
263 # delivery but before the ack deadline expires and before the message is
264 # acknowledged, it is an outstanding message and will not be delivered
265 # again during that time (on a best-effort basis).
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]266 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]267 # For pull subscriptions, this value is used as the initial value for the ack
268 # deadline. To override this value for a given message, call
269 # `ModifyAckDeadline` with the corresponding `ack_id` if using pull.
270 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]271 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]272 # For push delivery, this value is also used to set the request timeout for
273 # the call to the push endpoint.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]274 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]275 # If the subscriber never acknowledges the message, the Pub/Sub
276 # system will eventually redeliver the message.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]277 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]278 # If this parameter is 0, a default value of 10 seconds is used.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]279 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
280 # The value of this field will be `_deleted-topic_` if the topic has been
281 # deleted.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]282 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
283 # used to configure it. An empty `pushConfig` signifies that the subscriber
284 # will pull and ack messages using API methods.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]285 "oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
286 # `Authorization` header in the HTTP request for every pushed message.
287 # [OpenID Connect
288 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
289 "audience": "A String", # Audience to be used when generating OIDC token. The audience claim
290 # identifies the recipients that the JWT is intended for. The audience
291 # value is a single case-sensitive string. Having multiple values (array)
292 # for the audience field is not supported. More info about the OIDC JWT
293 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
294 # Note: if not specified, the Push endpoint URL will be used.
295 "serviceAccountEmail": "A String", # [Service account
296 # email](https://cloud.google.com/iam/docs/service-accounts)
297 # to be used for generating the OIDC token. The caller (for
298 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
299 # have the iam.serviceAccounts.actAs permission for the service account.
300 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]301 "attributes": { # Endpoint configuration attributes.
302 #
303 # Every endpoint has a set of API supported attributes that can be used to
304 # control different aspects of the message delivery.
305 #
306 # The currently supported attribute is `x-goog-version`, which you can
307 # use to change the format of the push message. This attribute
308 # indicates the version of the data expected by the endpoint. This
309 # controls the shape of the envelope (i.e. its fields and metadata).
310 # The endpoint version is based on the version of the Pub/Sub
311 # API.
312 #
313 # If not present during the `CreateSubscription` call, it will default to
314 # the version of the API used to make such call. If not present during a
315 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
316 # calls will always return a valid version, even if the subscription was
317 # created without this attribute.
318 #
319 # The possible values for this attribute are:
320 #
321 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
322 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]323 "a_key": "A String",
324 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]325 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
326 # For example, a Webhook endpoint might use "https://example.com/push".
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]327 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]328 "name": "A String", # The name of the subscription. It must have the format
329 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
330 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
331 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
332 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
333 # in length, and it must not start with `"goog"`.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]334 }</pre>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]335</div>
336
337<div class="method">
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]338 <code class="details" id="delete">delete(subscription, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]339 <pre>Deletes an existing subscription. All pending messages in the subscription
340are immediately dropped. Calls to `Pull` after deletion will return
341`NOT_FOUND`. After a subscription is deleted, a new one may be created with
342the same name, but the new one has no association with the old
343subscription, or its topic unless the same topic is specified.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]344
345Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]346 subscription: string, The subscription to delete. (required)
347 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]348 Allowed values
349 1 - v1 error format
350 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]351
352Returns:
353 An object of the form:
354
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]355 { # A generic empty message that you can re-use to avoid defining duplicated
356 # empty messages in your APIs. A typical example is to use it as the request
357 # or the response type of an API method. For instance:
358 #
359 # service Foo {
360 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
361 # }
362 #
363 # The JSON representation for `Empty` is empty JSON object `{}`.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]364 }</pre>
365</div>
366
367<div class="method">
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]368 <code class="details" id="get">get(subscription, x__xgafv=None)</code>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]369 <pre>Gets the configuration details of a subscription.
370
371Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]372 subscription: string, The name of the subscription to get. (required)
373 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]374 Allowed values
375 1 - v1 error format
376 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]377
378Returns:
379 An object of the form:
380
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]381 { # A subscription resource.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]382 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
383 # before the subscriber should acknowledge the message. After message
384 # delivery but before the ack deadline expires and before the message is
385 # acknowledged, it is an outstanding message and will not be delivered
386 # again during that time (on a best-effort basis).
387 #
388 # For pull subscriptions, this value is used as the initial value for the ack
389 # deadline. To override this value for a given message, call
390 # `ModifyAckDeadline` with the corresponding `ack_id` if using pull.
391 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
392 #
393 # For push delivery, this value is also used to set the request timeout for
394 # the call to the push endpoint.
395 #
396 # If the subscriber never acknowledges the message, the Pub/Sub
397 # system will eventually redeliver the message.
398 #
399 # If this parameter is 0, a default value of 10 seconds is used.
400 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
401 # The value of this field will be `_deleted-topic_` if the topic has been
402 # deleted.
403 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
404 # used to configure it. An empty `pushConfig` signifies that the subscriber
405 # will pull and ack messages using API methods.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]406 "oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
407 # `Authorization` header in the HTTP request for every pushed message.
408 # [OpenID Connect
409 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
410 "audience": "A String", # Audience to be used when generating OIDC token. The audience claim
411 # identifies the recipients that the JWT is intended for. The audience
412 # value is a single case-sensitive string. Having multiple values (array)
413 # for the audience field is not supported. More info about the OIDC JWT
414 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
415 # Note: if not specified, the Push endpoint URL will be used.
416 "serviceAccountEmail": "A String", # [Service account
417 # email](https://cloud.google.com/iam/docs/service-accounts)
418 # to be used for generating the OIDC token. The caller (for
419 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
420 # have the iam.serviceAccounts.actAs permission for the service account.
421 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]422 "attributes": { # Endpoint configuration attributes.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]423 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]424 # Every endpoint has a set of API supported attributes that can be used to
425 # control different aspects of the message delivery.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]426 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]427 # The currently supported attribute is `x-goog-version`, which you can
428 # use to change the format of the push message. This attribute
429 # indicates the version of the data expected by the endpoint. This
430 # controls the shape of the envelope (i.e. its fields and metadata).
431 # The endpoint version is based on the version of the Pub/Sub
432 # API.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]433 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]434 # If not present during the `CreateSubscription` call, it will default to
435 # the version of the API used to make such call. If not present during a
436 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
437 # calls will always return a valid version, even if the subscription was
438 # created without this attribute.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]439 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]440 # The possible values for this attribute are:
441 #
442 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
443 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
444 "a_key": "A String",
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]445 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]446 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
447 # For example, a Webhook endpoint might use "https://example.com/push".
448 },
449 "name": "A String", # The name of the subscription. It must have the format
450 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
451 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
452 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
453 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
454 # in length, and it must not start with `"goog"`.
455 }</pre>
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]456</div>
457
458<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]459 <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]460 <pre>Gets the access control policy for a resource.
461Returns an empty policy if the resource exists and does not have a policy
462set.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]463
464Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]465 resource: string, REQUIRED: The resource for which the policy is being requested.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]466See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]467 options_requestedPolicyVersion: integer, Optional. The policy format version to be returned.
468
469Valid values are 0, 1, and 3. Requests specifying an invalid value will be
470rejected.
471
472Requests for policies with any conditional bindings must specify version 3.
473Policies without any conditional bindings may specify any valid value or
474leave the field unset.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]475 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]476 Allowed values
477 1 - v1 error format
478 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]479
480Returns:
481 An object of the form:
482
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]483 { # An Identity and Access Management (IAM) policy, which specifies access
484 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]485 #
486 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]487 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
488 # `members` to a single `role`. Members can be user accounts, service accounts,
489 # Google groups, and domains (such as G Suite). A `role` is a named list of
490 # permissions; each `role` can be an IAM predefined role or a user-created
491 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]492 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]493 # Optionally, a `binding` can specify a `condition`, which is a logical
494 # expression that allows access to a resource only if the expression evaluates
495 # to `true`. A condition can add constraints based on attributes of the
496 # request, the resource, or both.
497 #
498 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]499 #
500 # {
501 # "bindings": [
502 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]503 # "role": "roles/resourcemanager.organizationAdmin",
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]504 # "members": [
505 # "user:mike@example.com",
506 # "group:admins@example.com",
507 # "domain:google.com",
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]508 # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]509 # ]
510 # },
511 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]512 # "role": "roles/resourcemanager.organizationViewer",
513 # "members": ["user:eve@example.com"],
514 # "condition": {
515 # "title": "expirable access",
516 # "description": "Does not grant access after Sep 2020",
517 # "expression": "request.time &lt; timestamp('2020-10-01T00:00:00.000Z')",
518 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]519 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]520 # ],
521 # "etag": "BwWWja0YfJA=",
522 # "version": 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]523 # }
524 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]525 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]526 #
527 # bindings:
528 # - members:
529 # - user:mike@example.com
530 # - group:admins@example.com
531 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]532 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
533 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]534 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]535 # - user:eve@example.com
536 # role: roles/resourcemanager.organizationViewer
537 # condition:
538 # title: expirable access
539 # description: Does not grant access after Sep 2020
540 # expression: request.time &lt; timestamp('2020-10-01T00:00:00.000Z')
541 # - etag: BwWWja0YfJA=
542 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]543 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]544 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]545 # [IAM documentation](https://cloud.google.com/iam/docs/).
546 "bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a
547 # `condition` that determines how and when the `bindings` are applied. Each
548 # of the `bindings` must contain at least one member.
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]549 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]550 "role": "A String", # Role that is assigned to `members`.
551 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]552 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
553 # `members` can have the following values:
554 #
555 # * `allUsers`: A special identifier that represents anyone who is
556 # on the internet; with or without a Google account.
557 #
558 # * `allAuthenticatedUsers`: A special identifier that represents anyone
559 # who is authenticated with a Google account or a service account.
560 #
561 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]562 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]563 #
564 #
565 # * `serviceAccount:{emailid}`: An email address that represents a service
566 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
567 #
568 # * `group:{emailid}`: An email address that represents a Google group.
569 # For example, `admins@example.com`.
570 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]571 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
572 # identifier) representing a user that has been recently deleted. For
573 # example, `alice@example.com?uid=123456789012345678901`. If the user is
574 # recovered, this value reverts to `user:{emailid}` and the recovered user
575 # retains the role in the binding.
576 #
577 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
578 # unique identifier) representing a service account that has been recently
579 # deleted. For example,
580 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
581 # If the service account is undeleted, this value reverts to
582 # `serviceAccount:{emailid}` and the undeleted service account retains the
583 # role in the binding.
584 #
585 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
586 # identifier) representing a Google group that has been recently
587 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
588 # the group is recovered, this value reverts to `group:{emailid}` and the
589 # recovered group retains the role in the binding.
590 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]591 #
592 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]593 # users of that domain. For example, `google.com` or `example.com`.
594 #
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]595 "A String",
596 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]597 "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
598 # NOTE: An unsatisfied condition will not allow user access via current
599 # binding. Different bindings, including their conditions, are examined
600 # independently.
601 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
602 # are documented at https://github.com/google/cel-spec.
603 #
604 # Example (Comparison):
605 #
606 # title: "Summary size limit"
607 # description: "Determines if a summary is less than 100 chars"
608 # expression: "document.summary.size() &lt; 100"
609 #
610 # Example (Equality):
611 #
612 # title: "Requestor is owner"
613 # description: "Determines if requestor is the document owner"
614 # expression: "document.owner == request.auth.claims.email"
615 #
616 # Example (Logic):
617 #
618 # title: "Public documents"
619 # description: "Determine whether the document should be publicly visible"
620 # expression: "document.type != 'private' &amp;&amp; document.type != 'internal'"
621 #
622 # Example (Data Manipulation):
623 #
624 # title: "Notification string"
625 # description: "Create a notification string with a timestamp."
626 # expression: "'New message received at ' + string(document.create_time)"
627 #
628 # The exact variables and functions that may be referenced within an expression
629 # are determined by the service that evaluates it. See the service
630 # documentation for additional information.
631 "description": "A String", # Optional. Description of the expression. This is a longer text which
632 # describes the expression, e.g. when hovered over it in a UI.
633 "expression": "A String", # Textual representation of an expression in Common Expression Language
634 # syntax.
635 "location": "A String", # Optional. String indicating the location of the expression for error
636 # reporting, e.g. a file name and a position in the file.
637 "title": "A String", # Optional. Title for the expression, i.e. a short string describing
638 # its purpose. This can be used e.g. in UIs which allow to enter the
639 # expression.
640 },
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]641 },
642 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]643 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
644 # prevent simultaneous updates of a policy from overwriting each other.
645 # It is strongly suggested that systems make use of the `etag` in the
646 # read-modify-write cycle to perform policy updates in order to avoid race
647 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
648 # systems are expected to put that etag in the request to `setIamPolicy` to
649 # ensure that their change will be applied to the same version of the policy.
650 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]651 # **Important:** If you use IAM Conditions, you must include the `etag` field
652 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
653 # you to overwrite a version `3` policy with a version `1` policy, and all of
654 # the conditions in the version `3` policy are lost.
655 "version": 42, # Specifies the format of the policy.
656 #
657 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
658 # are rejected.
659 #
660 # Any operation that affects conditional role bindings must specify version
661 # `3`. This requirement applies to the following operations:
662 #
663 # * Getting a policy that includes a conditional role binding
664 # * Adding a conditional role binding to a policy
665 # * Changing a conditional role binding in a policy
666 # * Removing any role binding, with or without a condition, from a policy
667 # that includes conditions
668 #
669 # **Important:** If you use IAM Conditions, you must include the `etag` field
670 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
671 # you to overwrite a version `3` policy with a version `1` policy, and all of
672 # the conditions in the version `3` policy are lost.
673 #
674 # If a policy does not include any conditions, operations on that policy may
675 # specify any valid version or leave the field unset.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]676 }</pre>
677</div>
678
679<div class="method">
680 <code class="details" id="list">list(project, pageSize=None, pageToken=None, x__xgafv=None)</code>
681 <pre>Lists matching subscriptions.
682
683Args:
684 project: string, The name of the cloud project that subscriptions belong to. (required)
685 pageSize: integer, Maximum number of subscriptions to return.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]686 pageToken: string, The value returned by the last `ListSubscriptionsResponse`; indicates that
687this is a continuation of a prior `ListSubscriptions` call, and that the
688system should return the next page of data.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]689 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]690 Allowed values
691 1 - v1 error format
692 2 - v2 error format
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]693
694Returns:
695 An object of the form:
696
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]697 { # Response for the `ListSubscriptions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]698 "nextPageToken": "A String", # If not empty, indicates that there may be more subscriptions that match
699 # the request; this value should be passed in a new
700 # `ListSubscriptionsRequest` to get more subscriptions.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]701 "subscriptions": [ # The subscriptions that match the request.
702 { # A subscription resource.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]703 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
704 # before the subscriber should acknowledge the message. After message
705 # delivery but before the ack deadline expires and before the message is
706 # acknowledged, it is an outstanding message and will not be delivered
707 # again during that time (on a best-effort basis).
708 #
709 # For pull subscriptions, this value is used as the initial value for the ack
710 # deadline. To override this value for a given message, call
711 # `ModifyAckDeadline` with the corresponding `ack_id` if using pull.
712 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
713 #
714 # For push delivery, this value is also used to set the request timeout for
715 # the call to the push endpoint.
716 #
717 # If the subscriber never acknowledges the message, the Pub/Sub
718 # system will eventually redeliver the message.
719 #
720 # If this parameter is 0, a default value of 10 seconds is used.
721 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
722 # The value of this field will be `_deleted-topic_` if the topic has been
723 # deleted.
724 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
725 # used to configure it. An empty `pushConfig` signifies that the subscriber
726 # will pull and ack messages using API methods.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]727 "oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
728 # `Authorization` header in the HTTP request for every pushed message.
729 # [OpenID Connect
730 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
731 "audience": "A String", # Audience to be used when generating OIDC token. The audience claim
732 # identifies the recipients that the JWT is intended for. The audience
733 # value is a single case-sensitive string. Having multiple values (array)
734 # for the audience field is not supported. More info about the OIDC JWT
735 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
736 # Note: if not specified, the Push endpoint URL will be used.
737 "serviceAccountEmail": "A String", # [Service account
738 # email](https://cloud.google.com/iam/docs/service-accounts)
739 # to be used for generating the OIDC token. The caller (for
740 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
741 # have the iam.serviceAccounts.actAs permission for the service account.
742 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]743 "attributes": { # Endpoint configuration attributes.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]744 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]745 # Every endpoint has a set of API supported attributes that can be used to
746 # control different aspects of the message delivery.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]747 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]748 # The currently supported attribute is `x-goog-version`, which you can
749 # use to change the format of the push message. This attribute
750 # indicates the version of the data expected by the endpoint. This
751 # controls the shape of the envelope (i.e. its fields and metadata).
752 # The endpoint version is based on the version of the Pub/Sub
753 # API.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]754 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]755 # If not present during the `CreateSubscription` call, it will default to
756 # the version of the API used to make such call. If not present during a
757 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
758 # calls will always return a valid version, even if the subscription was
759 # created without this attribute.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]760 #
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]761 # The possible values for this attribute are:
762 #
763 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
764 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
765 "a_key": "A String",
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]766 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]767 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
768 # For example, a Webhook endpoint might use "https://example.com/push".
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]769 },
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]770 "name": "A String", # The name of the subscription. It must have the format
771 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
772 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
773 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
774 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
775 # in length, and it must not start with `"goog"`.
776 },
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]777 ],
778 }</pre>
779</div>
780
781<div class="method">
782 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
783 <pre>Retrieves the next page of results.
784
785Args:
786 previous_request: The request for the previous page. (required)
787 previous_response: The response from the request for the previous page. (required)
788
789Returns:
790 A request object that you can call 'execute()' on to request the next
791 page. Returns None if there are no more items in the collection.
792 </pre>
793</div>
794
795<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]796 <code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]797 <pre>Modifies the ack deadline for a specific message. This method is useful
798to indicate that more time is needed to process a message by the
799subscriber, or to make the message available for redelivery if the
800processing was interrupted. Note that this does not modify the
801subscription-level `ackDeadlineSeconds` used for subsequent messages.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]802
803Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]804 subscription: string, The name of the subscription. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]805 body: object, The request body.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]806 The object takes the form of:
807
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]808{ # Request for the ModifyAckDeadline method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]809 "ackDeadlineSeconds": 42, # The new ack deadline with respect to the time this request was sent to
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]810 # the Pub/Sub system. Must be &gt;= 0. For example, if the value is 10, the new
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]811 # ack deadline will expire 10 seconds after the `ModifyAckDeadline` call
812 # was made. Specifying zero may immediately make the message available for
813 # another pull request.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]814 "ackId": "A String", # The acknowledgment ID. Either this or ack_ids must be populated, but not
815 # both.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]816 "ackIds": [ # List of acknowledgment IDs.
817 "A String",
818 ],
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]819 }
820
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]821 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]822 Allowed values
823 1 - v1 error format
824 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]825
826Returns:
827 An object of the form:
828
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]829 { # A generic empty message that you can re-use to avoid defining duplicated
830 # empty messages in your APIs. A typical example is to use it as the request
831 # or the response type of an API method. For instance:
832 #
833 # service Foo {
834 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
835 # }
836 #
837 # The JSON representation for `Empty` is empty JSON object `{}`.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]838 }</pre>
839</div>
840
841<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]842 <code class="details" id="modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]843 <pre>Modifies the `PushConfig` for a specified subscription.
844
845This may be used to change a push subscription to a pull one (signified by
846an empty `PushConfig`) or vice versa, or change the endpoint URL and other
847attributes of a push subscription. Messages will accumulate for delivery
848continuously through the call regardless of changes to the `PushConfig`.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]849
850Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]851 subscription: string, The name of the subscription. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]852 body: object, The request body.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]853 The object takes the form of:
854
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]855{ # Request for the ModifyPushConfig method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]856 "pushConfig": { # Configuration for a push delivery endpoint. # The push configuration for future deliveries.
857 #
858 # An empty `pushConfig` indicates that the Pub/Sub system should
859 # stop pushing messages from the given subscription and allow
860 # messages to be pulled and acknowledged - effectively pausing
861 # the subscription if `Pull` is not called.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]862 "oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an
863 # `Authorization` header in the HTTP request for every pushed message.
864 # [OpenID Connect
865 # token](https://developers.google.com/identity/protocols/OpenIDConnect).
866 "audience": "A String", # Audience to be used when generating OIDC token. The audience claim
867 # identifies the recipients that the JWT is intended for. The audience
868 # value is a single case-sensitive string. Having multiple values (array)
869 # for the audience field is not supported. More info about the OIDC JWT
870 # token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
871 # Note: if not specified, the Push endpoint URL will be used.
872 "serviceAccountEmail": "A String", # [Service account
873 # email](https://cloud.google.com/iam/docs/service-accounts)
874 # to be used for generating the OIDC token. The caller (for
875 # CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
876 # have the iam.serviceAccounts.actAs permission for the service account.
877 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]878 "attributes": { # Endpoint configuration attributes.
879 #
880 # Every endpoint has a set of API supported attributes that can be used to
881 # control different aspects of the message delivery.
882 #
883 # The currently supported attribute is `x-goog-version`, which you can
884 # use to change the format of the push message. This attribute
885 # indicates the version of the data expected by the endpoint. This
886 # controls the shape of the envelope (i.e. its fields and metadata).
887 # The endpoint version is based on the version of the Pub/Sub
888 # API.
889 #
890 # If not present during the `CreateSubscription` call, it will default to
891 # the version of the API used to make such call. If not present during a
892 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
893 # calls will always return a valid version, even if the subscription was
894 # created without this attribute.
895 #
896 # The possible values for this attribute are:
897 #
898 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
899 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]900 "a_key": "A String",
901 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]902 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
903 # For example, a Webhook endpoint might use "https://example.com/push".
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]904 },
905 }
906
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]907 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]908 Allowed values
909 1 - v1 error format
910 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]911
912Returns:
913 An object of the form:
914
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]915 { # A generic empty message that you can re-use to avoid defining duplicated
916 # empty messages in your APIs. A typical example is to use it as the request
917 # or the response type of an API method. For instance:
918 #
919 # service Foo {
920 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
921 # }
922 #
923 # The JSON representation for `Empty` is empty JSON object `{}`.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]924 }</pre>
925</div>
926
927<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]928 <code class="details" id="pull">pull(subscription, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]929 <pre>Pulls messages from the server. Returns an empty list if there are no
930messages available in the backlog. The server may return `UNAVAILABLE` if
931there are too many concurrent pull requests pending for the given
932subscription.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]933
934Args:
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]935 subscription: string, The subscription from which messages should be pulled. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]936 body: object, The request body.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]937 The object takes the form of:
938
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]939{ # Request for the `Pull` method.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]940 "returnImmediately": True or False, # Optional. If this is specified as true the system will respond immediately even if
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]941 # it is not able to return a message in the `Pull` response. Otherwise the
942 # system is allowed to wait until at least one message is available rather
943 # than returning no messages. The client may cancel the request if it does
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]944 # not wish to wait any longer for the response. Warning: setting this field
945 # to `true` is discouraged because it adversely impacts the performance of
946 # `Pull` operations. We recommend that users do not set this field.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]947 "maxMessages": 42, # The maximum number of messages returned for this request. The Pub/Sub
948 # system may return fewer than the number specified.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]949 }
950
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]951 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]952 Allowed values
953 1 - v1 error format
954 2 - v2 error format
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]955
956Returns:
957 An object of the form:
958
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]959 { # Response for the `Pull` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]960 "receivedMessages": [ # Received Pub/Sub messages. The Pub/Sub system will return zero messages if
961 # there are no more available in the backlog. The Pub/Sub system may return
962 # fewer than the `maxMessages` requested even if there are more messages
963 # available in the backlog.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]964 { # A message and its corresponding acknowledgment ID.
965 "ackId": "A String", # This ID can be used to acknowledge the received message.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]966 "message": { # A message data and its attributes. The message payload must not be empty; # The message.
967 # it must contain either a non-empty data field, or at least one attribute.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]968 "attributes": { # Optional attributes for this message.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]969 "a_key": "A String",
970 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]971 "data": "A String", # The message payload. For JSON requests, the value of this field must be
972 # [base64-encoded](https://tools.ietf.org/html/rfc4648).
973 "publishTime": "A String", # The time at which the message was published, populated by the server when
974 # it receives the `Publish` call. It must not be populated by the
975 # publisher in a `Publish` call.
976 "messageId": "A String", # ID of this message, assigned by the server when the message is published.
977 # Guaranteed to be unique within the topic. This value may be read by a
978 # subscriber that receives a `PubsubMessage` via a `Pull` call or a push
979 # delivery. It must not be populated by the publisher in a `Publish` call.
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]980 },
981 },
982 ],
983 }</pre>
984</div>
985
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]986<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]987 <code class="details" id="setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</code>
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]988 <pre>Sets the access control policy on the specified resource. Replaces any
989existing policy.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]990
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]991Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and PERMISSION_DENIED
992
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]993Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]994 resource: string, REQUIRED: The resource for which the policy is being specified.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]995See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]996 body: object, The request body.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]997 The object takes the form of:
998
999{ # Request message for `SetIamPolicy` method.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1000 "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]1001 # the policy is limited to a few 10s of KB. An empty policy is a
1002 # valid policy but certain Cloud Platform services (such as Projects)
1003 # might reject them.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1004 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1005 #
1006 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1007 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
1008 # `members` to a single `role`. Members can be user accounts, service accounts,
1009 # Google groups, and domains (such as G Suite). A `role` is a named list of
1010 # permissions; each `role` can be an IAM predefined role or a user-created
1011 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1012 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1013 # Optionally, a `binding` can specify a `condition`, which is a logical
1014 # expression that allows access to a resource only if the expression evaluates
1015 # to `true`. A condition can add constraints based on attributes of the
1016 # request, the resource, or both.
1017 #
1018 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1019 #
1020 # {
1021 # "bindings": [
1022 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1023 # "role": "roles/resourcemanager.organizationAdmin",
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1024 # "members": [
1025 # "user:mike@example.com",
1026 # "group:admins@example.com",
1027 # "domain:google.com",
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1028 # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1029 # ]
1030 # },
1031 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1032 # "role": "roles/resourcemanager.organizationViewer",
1033 # "members": ["user:eve@example.com"],
1034 # "condition": {
1035 # "title": "expirable access",
1036 # "description": "Does not grant access after Sep 2020",
1037 # "expression": "request.time &lt; timestamp('2020-10-01T00:00:00.000Z')",
1038 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1039 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1040 # ],
1041 # "etag": "BwWWja0YfJA=",
1042 # "version": 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1043 # }
1044 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1045 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1046 #
1047 # bindings:
1048 # - members:
1049 # - user:mike@example.com
1050 # - group:admins@example.com
1051 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1052 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
1053 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1054 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1055 # - user:eve@example.com
1056 # role: roles/resourcemanager.organizationViewer
1057 # condition:
1058 # title: expirable access
1059 # description: Does not grant access after Sep 2020
1060 # expression: request.time &lt; timestamp('2020-10-01T00:00:00.000Z')
1061 # - etag: BwWWja0YfJA=
1062 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1063 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1064 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1065 # [IAM documentation](https://cloud.google.com/iam/docs/).
1066 "bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a
1067 # `condition` that determines how and when the `bindings` are applied. Each
1068 # of the `bindings` must contain at least one member.
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]1069 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1070 "role": "A String", # Role that is assigned to `members`.
1071 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1072 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
1073 # `members` can have the following values:
1074 #
1075 # * `allUsers`: A special identifier that represents anyone who is
1076 # on the internet; with or without a Google account.
1077 #
1078 # * `allAuthenticatedUsers`: A special identifier that represents anyone
1079 # who is authenticated with a Google account or a service account.
1080 #
1081 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1082 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1083 #
1084 #
1085 # * `serviceAccount:{emailid}`: An email address that represents a service
1086 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
1087 #
1088 # * `group:{emailid}`: An email address that represents a Google group.
1089 # For example, `admins@example.com`.
1090 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1091 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
1092 # identifier) representing a user that has been recently deleted. For
1093 # example, `alice@example.com?uid=123456789012345678901`. If the user is
1094 # recovered, this value reverts to `user:{emailid}` and the recovered user
1095 # retains the role in the binding.
1096 #
1097 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
1098 # unique identifier) representing a service account that has been recently
1099 # deleted. For example,
1100 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
1101 # If the service account is undeleted, this value reverts to
1102 # `serviceAccount:{emailid}` and the undeleted service account retains the
1103 # role in the binding.
1104 #
1105 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
1106 # identifier) representing a Google group that has been recently
1107 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
1108 # the group is recovered, this value reverts to `group:{emailid}` and the
1109 # recovered group retains the role in the binding.
1110 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1111 #
1112 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1113 # users of that domain. For example, `google.com` or `example.com`.
1114 #
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1115 "A String",
1116 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1117 "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
1118 # NOTE: An unsatisfied condition will not allow user access via current
1119 # binding. Different bindings, including their conditions, are examined
1120 # independently.
1121 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
1122 # are documented at https://github.com/google/cel-spec.
1123 #
1124 # Example (Comparison):
1125 #
1126 # title: "Summary size limit"
1127 # description: "Determines if a summary is less than 100 chars"
1128 # expression: "document.summary.size() &lt; 100"
1129 #
1130 # Example (Equality):
1131 #
1132 # title: "Requestor is owner"
1133 # description: "Determines if requestor is the document owner"
1134 # expression: "document.owner == request.auth.claims.email"
1135 #
1136 # Example (Logic):
1137 #
1138 # title: "Public documents"
1139 # description: "Determine whether the document should be publicly visible"
1140 # expression: "document.type != 'private' &amp;&amp; document.type != 'internal'"
1141 #
1142 # Example (Data Manipulation):
1143 #
1144 # title: "Notification string"
1145 # description: "Create a notification string with a timestamp."
1146 # expression: "'New message received at ' + string(document.create_time)"
1147 #
1148 # The exact variables and functions that may be referenced within an expression
1149 # are determined by the service that evaluates it. See the service
1150 # documentation for additional information.
1151 "description": "A String", # Optional. Description of the expression. This is a longer text which
1152 # describes the expression, e.g. when hovered over it in a UI.
1153 "expression": "A String", # Textual representation of an expression in Common Expression Language
1154 # syntax.
1155 "location": "A String", # Optional. String indicating the location of the expression for error
1156 # reporting, e.g. a file name and a position in the file.
1157 "title": "A String", # Optional. Title for the expression, i.e. a short string describing
1158 # its purpose. This can be used e.g. in UIs which allow to enter the
1159 # expression.
1160 },
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1161 },
1162 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1163 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
1164 # prevent simultaneous updates of a policy from overwriting each other.
1165 # It is strongly suggested that systems make use of the `etag` in the
1166 # read-modify-write cycle to perform policy updates in order to avoid race
1167 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
1168 # systems are expected to put that etag in the request to `setIamPolicy` to
1169 # ensure that their change will be applied to the same version of the policy.
1170 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1171 # **Important:** If you use IAM Conditions, you must include the `etag` field
1172 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1173 # you to overwrite a version `3` policy with a version `1` policy, and all of
1174 # the conditions in the version `3` policy are lost.
1175 "version": 42, # Specifies the format of the policy.
1176 #
1177 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
1178 # are rejected.
1179 #
1180 # Any operation that affects conditional role bindings must specify version
1181 # `3`. This requirement applies to the following operations:
1182 #
1183 # * Getting a policy that includes a conditional role binding
1184 # * Adding a conditional role binding to a policy
1185 # * Changing a conditional role binding in a policy
1186 # * Removing any role binding, with or without a condition, from a policy
1187 # that includes conditions
1188 #
1189 # **Important:** If you use IAM Conditions, you must include the `etag` field
1190 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1191 # you to overwrite a version `3` policy with a version `1` policy, and all of
1192 # the conditions in the version `3` policy are lost.
1193 #
1194 # If a policy does not include any conditions, operations on that policy may
1195 # specify any valid version or leave the field unset.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1196 },
1197 }
1198
1199 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1200 Allowed values
1201 1 - v1 error format
1202 2 - v2 error format
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1203
1204Returns:
1205 An object of the form:
1206
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1207 { # An Identity and Access Management (IAM) policy, which specifies access
1208 # controls for Google Cloud resources.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1209 #
1210 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1211 # A `Policy` is a collection of `bindings`. A `binding` binds one or more
1212 # `members` to a single `role`. Members can be user accounts, service accounts,
1213 # Google groups, and domains (such as G Suite). A `role` is a named list of
1214 # permissions; each `role` can be an IAM predefined role or a user-created
1215 # custom role.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1216 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1217 # Optionally, a `binding` can specify a `condition`, which is a logical
1218 # expression that allows access to a resource only if the expression evaluates
1219 # to `true`. A condition can add constraints based on attributes of the
1220 # request, the resource, or both.
1221 #
1222 # **JSON example:**
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1223 #
1224 # {
1225 # "bindings": [
1226 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1227 # "role": "roles/resourcemanager.organizationAdmin",
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1228 # "members": [
1229 # "user:mike@example.com",
1230 # "group:admins@example.com",
1231 # "domain:google.com",
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1232 # "serviceAccount:my-project-id@appspot.gserviceaccount.com"
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1233 # ]
1234 # },
1235 # {
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1236 # "role": "roles/resourcemanager.organizationViewer",
1237 # "members": ["user:eve@example.com"],
1238 # "condition": {
1239 # "title": "expirable access",
1240 # "description": "Does not grant access after Sep 2020",
1241 # "expression": "request.time &lt; timestamp('2020-10-01T00:00:00.000Z')",
1242 # }
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1243 # }
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1244 # ],
1245 # "etag": "BwWWja0YfJA=",
1246 # "version": 3
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1247 # }
1248 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1249 # **YAML example:**
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1250 #
1251 # bindings:
1252 # - members:
1253 # - user:mike@example.com
1254 # - group:admins@example.com
1255 # - domain:google.com
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1256 # - serviceAccount:my-project-id@appspot.gserviceaccount.com
1257 # role: roles/resourcemanager.organizationAdmin
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1258 # - members:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1259 # - user:eve@example.com
1260 # role: roles/resourcemanager.organizationViewer
1261 # condition:
1262 # title: expirable access
1263 # description: Does not grant access after Sep 2020
1264 # expression: request.time &lt; timestamp('2020-10-01T00:00:00.000Z')
1265 # - etag: BwWWja0YfJA=
1266 # - version: 3
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1267 #
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1268 # For a description of IAM and its features, see the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1269 # [IAM documentation](https://cloud.google.com/iam/docs/).
1270 "bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a
1271 # `condition` that determines how and when the `bindings` are applied. Each
1272 # of the `bindings` must contain at least one member.
Sai Cheemalapatidf613972016-10-21 13:59:49 -0700[diff] [blame]1273 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1274 "role": "A String", # Role that is assigned to `members`.
1275 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1276 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
1277 # `members` can have the following values:
1278 #
1279 # * `allUsers`: A special identifier that represents anyone who is
1280 # on the internet; with or without a Google account.
1281 #
1282 # * `allAuthenticatedUsers`: A special identifier that represents anyone
1283 # who is authenticated with a Google account or a service account.
1284 #
1285 # * `user:{emailid}`: An email address that represents a specific Google
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1286 # account. For example, `alice@example.com` .
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1287 #
1288 #
1289 # * `serviceAccount:{emailid}`: An email address that represents a service
1290 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
1291 #
1292 # * `group:{emailid}`: An email address that represents a Google group.
1293 # For example, `admins@example.com`.
1294 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1295 # * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
1296 # identifier) representing a user that has been recently deleted. For
1297 # example, `alice@example.com?uid=123456789012345678901`. If the user is
1298 # recovered, this value reverts to `user:{emailid}` and the recovered user
1299 # retains the role in the binding.
1300 #
1301 # * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
1302 # unique identifier) representing a service account that has been recently
1303 # deleted. For example,
1304 # `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
1305 # If the service account is undeleted, this value reverts to
1306 # `serviceAccount:{emailid}` and the undeleted service account retains the
1307 # role in the binding.
1308 #
1309 # * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
1310 # identifier) representing a Google group that has been recently
1311 # deleted. For example, `admins@example.com?uid=123456789012345678901`. If
1312 # the group is recovered, this value reverts to `group:{emailid}` and the
1313 # recovered group retains the role in the binding.
1314 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1315 #
1316 # * `domain:{domain}`: The G Suite domain (primary) that represents all the
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1317 # users of that domain. For example, `google.com` or `example.com`.
1318 #
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1319 "A String",
1320 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1321 "condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.
1322 # NOTE: An unsatisfied condition will not allow user access via current
1323 # binding. Different bindings, including their conditions, are examined
1324 # independently.
1325 # syntax. CEL is a C-like expression language. The syntax and semantics of CEL
1326 # are documented at https://github.com/google/cel-spec.
1327 #
1328 # Example (Comparison):
1329 #
1330 # title: "Summary size limit"
1331 # description: "Determines if a summary is less than 100 chars"
1332 # expression: "document.summary.size() &lt; 100"
1333 #
1334 # Example (Equality):
1335 #
1336 # title: "Requestor is owner"
1337 # description: "Determines if requestor is the document owner"
1338 # expression: "document.owner == request.auth.claims.email"
1339 #
1340 # Example (Logic):
1341 #
1342 # title: "Public documents"
1343 # description: "Determine whether the document should be publicly visible"
1344 # expression: "document.type != 'private' &amp;&amp; document.type != 'internal'"
1345 #
1346 # Example (Data Manipulation):
1347 #
1348 # title: "Notification string"
1349 # description: "Create a notification string with a timestamp."
1350 # expression: "'New message received at ' + string(document.create_time)"
1351 #
1352 # The exact variables and functions that may be referenced within an expression
1353 # are determined by the service that evaluates it. See the service
1354 # documentation for additional information.
1355 "description": "A String", # Optional. Description of the expression. This is a longer text which
1356 # describes the expression, e.g. when hovered over it in a UI.
1357 "expression": "A String", # Textual representation of an expression in Common Expression Language
1358 # syntax.
1359 "location": "A String", # Optional. String indicating the location of the expression for error
1360 # reporting, e.g. a file name and a position in the file.
1361 "title": "A String", # Optional. Title for the expression, i.e. a short string describing
1362 # its purpose. This can be used e.g. in UIs which allow to enter the
1363 # expression.
1364 },
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1365 },
1366 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1367 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
1368 # prevent simultaneous updates of a policy from overwriting each other.
1369 # It is strongly suggested that systems make use of the `etag` in the
1370 # read-modify-write cycle to perform policy updates in order to avoid race
1371 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
1372 # systems are expected to put that etag in the request to `setIamPolicy` to
1373 # ensure that their change will be applied to the same version of the policy.
1374 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1375 # **Important:** If you use IAM Conditions, you must include the `etag` field
1376 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1377 # you to overwrite a version `3` policy with a version `1` policy, and all of
1378 # the conditions in the version `3` policy are lost.
1379 "version": 42, # Specifies the format of the policy.
1380 #
1381 # Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
1382 # are rejected.
1383 #
1384 # Any operation that affects conditional role bindings must specify version
1385 # `3`. This requirement applies to the following operations:
1386 #
1387 # * Getting a policy that includes a conditional role binding
1388 # * Adding a conditional role binding to a policy
1389 # * Changing a conditional role binding in a policy
1390 # * Removing any role binding, with or without a condition, from a policy
1391 # that includes conditions
1392 #
1393 # **Important:** If you use IAM Conditions, you must include the `etag` field
1394 # whenever you call `setIamPolicy`. If you omit this field, then IAM allows
1395 # you to overwrite a version `3` policy with a version `1` policy, and all of
1396 # the conditions in the version `3` policy are lost.
1397 #
1398 # If a policy does not include any conditions, operations on that policy may
1399 # specify any valid version or leave the field unset.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1400 }</pre>
1401</div>
1402
1403<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1404 <code class="details" id="testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</code>
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1405 <pre>Returns permissions that a caller has on the specified resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1406If the resource does not exist, this will return an empty set of
1407permissions, not a NOT_FOUND error.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1408
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1409Note: This operation is designed to be used for building permission-aware
1410UIs and command-line tools, not for authorization checking. This operation
1411may "fail open" without warning.
1412
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1413Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1414 resource: string, REQUIRED: The resource for which the policy detail is being requested.
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]1415See the operation documentation for the appropriate value for this field. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1416 body: object, The request body.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1417 The object takes the form of:
1418
1419{ # Request message for `TestIamPermissions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1420 "permissions": [ # The set of permissions to check for the `resource`. Permissions with
1421 # wildcards (such as '*' or 'storage.*') are not allowed. For more
1422 # information see
1423 # [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1424 "A String",
1425 ],
1426 }
1427
1428 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1429 Allowed values
1430 1 - v1 error format
1431 2 - v2 error format
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1432
1433Returns:
1434 An object of the form:
1435
1436 { # Response message for `TestIamPermissions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1437 "permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is
1438 # allowed.
Nathaniel Manista4f877e52015-06-15 16:44:50 +0000[diff] [blame]1439 "A String",
1440 ],
1441 }</pre>
1442</div>
1443
Craig Citroe633be12015-03-02 13:40:36 -0800[diff] [blame]1444</body></html>