Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / c30d2b5d4478b230246dcaaa9f1c533ca3304387 / . / docs / dyn / pubsub_v1.projects.subscriptions.html
blob: 583a0e4d75da07af6d2da6cd988612449f4478e9 [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
75<h1><a href="pubsub_v1.html">Google Cloud Pub/Sub API</a> . <a href="pubsub_v1.projects.html">projects</a> . <a href="pubsub_v1.projects.subscriptions.html">subscriptions</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]78 <code><a href="#acknowledge">acknowledge(subscription=None, body, x__xgafv=None)</a></code></p>
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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]81 <code><a href="#create">create(name=None, body, x__xgafv=None)</a></code></p>
82<p class="firstline">Creates a subscription to a given topic.</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]83<p class="toc_element">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]84 <code><a href="#delete">delete(subscription=None, x__xgafv=None)</a></code></p>
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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]87 <code><a href="#get">get(subscription=None, 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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]90 <code><a href="#getIamPolicy">getIamPolicy(resource=None, x__xgafv=None)</a></code></p>
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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]93 <code><a href="#list">list(project=None, 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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]99 <code><a href="#modifyAckDeadline">modifyAckDeadline(subscription=None, body, x__xgafv=None)</a></code></p>
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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]102 <code><a href="#modifyPushConfig">modifyPushConfig(subscription=None, body, x__xgafv=None)</a></code></p>
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">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]105 <code><a href="#pull">pull(subscription=None, body, x__xgafv=None)</a></code></p>
106<p class="firstline">Pulls messages from the server. Returns an empty list if there are no</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]107<p class="toc_element">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]108 <code><a href="#setIamPolicy">setIamPolicy(resource=None, body, x__xgafv=None)</a></code></p>
109<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]110<p class="toc_element">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]111 <code><a href="#testIamPermissions">testIamPermissions(resource=None, body, x__xgafv=None)</a></code></p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]112<p class="firstline">Returns permissions that a caller has on the specified resource.</p>
113<h3>Method Details</h3>
114<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]115 <code class="details" id="acknowledge">acknowledge(subscription=None, body, x__xgafv=None)</code>
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.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]123
124Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]125 subscription: string, The subscription whose message is being acknowledged.
126Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]127 body: object, The request body. (required)
128 The object takes the form of:
129
130{ # Request for the Acknowledge method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]131 "ackIds": [ # The acknowledgment ID for the messages being acknowledged that was returned
132 # by the Pub/Sub system in the `Pull` response. Must not be empty.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]133 "A String",
134 ],
135 }
136
137 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]138 Allowed values
139 1 - v1 error format
140 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]141
142Returns:
143 An object of the form:
144
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]145 { # A generic empty message that you can re-use to avoid defining duplicated
146 # empty messages in your APIs. A typical example is to use it as the request
147 # or the response type of an API method. For instance:
148 #
149 # service Foo {
150 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
151 # }
152 #
153 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]154 }</pre>
155</div>
156
157<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]158 <code class="details" id="create">create(name=None, body, x__xgafv=None)</code>
159 <pre>Creates a subscription to a given topic.
160If the subscription already exists, returns `ALREADY_EXISTS`.
161If the corresponding topic doesn't exist, returns `NOT_FOUND`.
162
163If the name is not provided in the request, the server will assign a random
164name for this subscription on the same project as the topic, conforming
165to the
166[resource name format](https://cloud.google.com/pubsub/docs/overview#names).
167The generated name is populated in the returned Subscription object.
168Note that for REST API requests, you must specify a name in the request.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]169
170Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]171 name: string, The name of the subscription. It must have the format
172`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
173start with a letter, and contain only letters (`[A-Za-z]`), numbers
174(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
175plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
176in length, and it must not start with `"goog"`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]177 body: object, The request body. (required)
178 The object takes the form of:
179
180{ # A subscription resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]181 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
182 # before the subscriber should acknowledge the message. After message
183 # delivery but before the ack deadline expires and before the message is
184 # acknowledged, it is an outstanding message and will not be delivered
185 # again during that time (on a best-effort basis).
186 #
187 # For pull subscriptions, this value is used as the initial value for the ack
188 # deadline. To override this value for a given message, call
189 # `ModifyAckDeadline` with the corresponding `ack_id` if using
190 # pull.
191 # The minimum custom deadline you can specify is 10 seconds.
192 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
193 # If this parameter is 0, a default value of 10 seconds is used.
194 #
195 # For push delivery, this value is also used to set the request timeout for
196 # the call to the push endpoint.
197 #
198 # If the subscriber never acknowledges the message, the Pub/Sub
199 # system will eventually redeliver the message.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]200 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
201 # Format is `projects/{project}/topics/{topic}`.
202 # The value of this field will be `_deleted-topic_` if the topic has been
203 # deleted.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]204 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
205 # used to configure it. An empty `pushConfig` signifies that the subscriber
206 # will pull and ack messages using API methods.
207 "attributes": { # Endpoint configuration attributes.
208 #
209 # Every endpoint has a set of API supported attributes that can be used to
210 # control different aspects of the message delivery.
211 #
212 # The currently supported attribute is `x-goog-version`, which you can
213 # use to change the format of the push message. This attribute
214 # indicates the version of the data expected by the endpoint. This
215 # controls the shape of the envelope (i.e. its fields and metadata).
216 # The endpoint version is based on the version of the Pub/Sub
217 # API.
218 #
219 # If not present during the `CreateSubscription` call, it will default to
220 # the version of the API used to make such call. If not present during a
221 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
222 # calls will always return a valid version, even if the subscription was
223 # created without this attribute.
224 #
225 # The possible values for this attribute are:
226 #
227 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
228 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]229 "a_key": "A String",
230 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]231 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
232 # For example, a Webhook endpoint might use "https://example.com/push".
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]233 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]234 "name": "A String", # The name of the subscription. It must have the format
235 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
236 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
237 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
238 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
239 # in length, and it must not start with `"goog"`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]240}
241
242 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]243 Allowed values
244 1 - v1 error format
245 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]246
247Returns:
248 An object of the form:
249
250 { # A subscription resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]251 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
252 # before the subscriber should acknowledge the message. After message
253 # delivery but before the ack deadline expires and before the message is
254 # acknowledged, it is an outstanding message and will not be delivered
255 # again during that time (on a best-effort basis).
256 #
257 # For pull subscriptions, this value is used as the initial value for the ack
258 # deadline. To override this value for a given message, call
259 # `ModifyAckDeadline` with the corresponding `ack_id` if using
260 # pull.
261 # The minimum custom deadline you can specify is 10 seconds.
262 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
263 # If this parameter is 0, a default value of 10 seconds is used.
264 #
265 # For push delivery, this value is also used to set the request timeout for
266 # the call to the push endpoint.
267 #
268 # If the subscriber never acknowledges the message, the Pub/Sub
269 # system will eventually redeliver the message.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]270 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
271 # Format is `projects/{project}/topics/{topic}`.
272 # The value of this field will be `_deleted-topic_` if the topic has been
273 # deleted.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]274 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
275 # used to configure it. An empty `pushConfig` signifies that the subscriber
276 # will pull and ack messages using API methods.
277 "attributes": { # Endpoint configuration attributes.
278 #
279 # Every endpoint has a set of API supported attributes that can be used to
280 # control different aspects of the message delivery.
281 #
282 # The currently supported attribute is `x-goog-version`, which you can
283 # use to change the format of the push message. This attribute
284 # indicates the version of the data expected by the endpoint. This
285 # controls the shape of the envelope (i.e. its fields and metadata).
286 # The endpoint version is based on the version of the Pub/Sub
287 # API.
288 #
289 # If not present during the `CreateSubscription` call, it will default to
290 # the version of the API used to make such call. If not present during a
291 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
292 # calls will always return a valid version, even if the subscription was
293 # created without this attribute.
294 #
295 # The possible values for this attribute are:
296 #
297 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
298 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]299 "a_key": "A String",
300 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]301 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
302 # For example, a Webhook endpoint might use "https://example.com/push".
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]303 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]304 "name": "A String", # The name of the subscription. It must have the format
305 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
306 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
307 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
308 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
309 # in length, and it must not start with `"goog"`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]310 }</pre>
311</div>
312
313<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]314 <code class="details" id="delete">delete(subscription=None, x__xgafv=None)</code>
315 <pre>Deletes an existing subscription. All messages retained in the subscription
316are immediately dropped. Calls to `Pull` after deletion will return
317`NOT_FOUND`. After a subscription is deleted, a new one may be created with
318the same name, but the new one has no association with the old
319subscription or its topic unless the same topic is specified.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]320
321Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]322 subscription: string, The subscription to delete.
323Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]324 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]325 Allowed values
326 1 - v1 error format
327 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]328
329Returns:
330 An object of the form:
331
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]332 { # A generic empty message that you can re-use to avoid defining duplicated
333 # empty messages in your APIs. A typical example is to use it as the request
334 # or the response type of an API method. For instance:
335 #
336 # service Foo {
337 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
338 # }
339 #
340 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]341 }</pre>
342</div>
343
344<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]345 <code class="details" id="get">get(subscription=None, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]346 <pre>Gets the configuration details of a subscription.
347
348Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]349 subscription: string, The name of the subscription to get.
350Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]351 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]352 Allowed values
353 1 - v1 error format
354 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]355
356Returns:
357 An object of the form:
358
359 { # A subscription resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]360 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
361 # before the subscriber should acknowledge the message. After message
362 # delivery but before the ack deadline expires and before the message is
363 # acknowledged, it is an outstanding message and will not be delivered
364 # again during that time (on a best-effort basis).
365 #
366 # For pull subscriptions, this value is used as the initial value for the ack
367 # deadline. To override this value for a given message, call
368 # `ModifyAckDeadline` with the corresponding `ack_id` if using
369 # pull.
370 # The minimum custom deadline you can specify is 10 seconds.
371 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
372 # If this parameter is 0, a default value of 10 seconds is used.
373 #
374 # For push delivery, this value is also used to set the request timeout for
375 # the call to the push endpoint.
376 #
377 # If the subscriber never acknowledges the message, the Pub/Sub
378 # system will eventually redeliver the message.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]379 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
380 # Format is `projects/{project}/topics/{topic}`.
381 # The value of this field will be `_deleted-topic_` if the topic has been
382 # deleted.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]383 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
384 # used to configure it. An empty `pushConfig` signifies that the subscriber
385 # will pull and ack messages using API methods.
386 "attributes": { # Endpoint configuration attributes.
387 #
388 # Every endpoint has a set of API supported attributes that can be used to
389 # control different aspects of the message delivery.
390 #
391 # The currently supported attribute is `x-goog-version`, which you can
392 # use to change the format of the push message. This attribute
393 # indicates the version of the data expected by the endpoint. This
394 # controls the shape of the envelope (i.e. its fields and metadata).
395 # The endpoint version is based on the version of the Pub/Sub
396 # API.
397 #
398 # If not present during the `CreateSubscription` call, it will default to
399 # the version of the API used to make such call. If not present during a
400 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
401 # calls will always return a valid version, even if the subscription was
402 # created without this attribute.
403 #
404 # The possible values for this attribute are:
405 #
406 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
407 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]408 "a_key": "A String",
409 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]410 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
411 # For example, a Webhook endpoint might use "https://example.com/push".
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]412 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]413 "name": "A String", # The name of the subscription. It must have the format
414 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
415 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
416 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
417 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
418 # in length, and it must not start with `"goog"`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]419 }</pre>
420</div>
421
422<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]423 <code class="details" id="getIamPolicy">getIamPolicy(resource=None, x__xgafv=None)</code>
424 <pre>Gets the access control policy for a resource.
425Returns an empty policy if the resource exists and does not have a policy
426set.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]427
428Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]429 resource: string, REQUIRED: The resource for which the policy is being requested.
430`resource` is usually specified as a path. For example, a Project
431resource is specified as `projects/{project}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]432 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]433 Allowed values
434 1 - v1 error format
435 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]436
437Returns:
438 An object of the form:
439
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]440 { # Defines an Identity and Access Management (IAM) policy. It is used to
441 # specify access control policies for Cloud Platform resources.
442 #
443 #
444 # A `Policy` consists of a list of `bindings`. A `Binding` binds a list of
445 # `members` to a `role`, where the members can be user accounts, Google groups,
446 # Google domains, and service accounts. A `role` is a named list of permissions
447 # defined by IAM.
448 #
449 # **Example**
450 #
451 # {
452 # "bindings": [
453 # {
454 # "role": "roles/owner",
455 # "members": [
456 # "user:mike@example.com",
457 # "group:admins@example.com",
458 # "domain:google.com",
459 # "serviceAccount:my-other-app@appspot.gserviceaccount.com",
460 # ]
461 # },
462 # {
463 # "role": "roles/viewer",
464 # "members": ["user:sean@example.com"]
465 # }
466 # ]
467 # }
468 #
469 # For a description of IAM and its features, see the
470 # [IAM developer's guide](https://cloud.google.com/iam).
471 "bindings": [ # Associates a list of `members` to a `role`.
472 # Multiple `bindings` must not be specified for the same `role`.
473 # `bindings` with no members will result in an error.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]474 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]475 "role": "A String", # Role that is assigned to `members`.
476 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
477 # Required
478 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
479 # `members` can have the following values:
480 #
481 # * `allUsers`: A special identifier that represents anyone who is
482 # on the internet; with or without a Google account.
483 #
484 # * `allAuthenticatedUsers`: A special identifier that represents anyone
485 # who is authenticated with a Google account or a service account.
486 #
487 # * `user:{emailid}`: An email address that represents a specific Google
488 # account. For example, `alice@gmail.com` or `joe@example.com`.
489 #
490 #
491 # * `serviceAccount:{emailid}`: An email address that represents a service
492 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
493 #
494 # * `group:{emailid}`: An email address that represents a Google group.
495 # For example, `admins@example.com`.
496 #
497 # * `domain:{domain}`: A Google Apps domain name that represents all the
498 # users of that domain. For example, `google.com` or `example.com`.
499 #
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]500 "A String",
501 ],
502 },
503 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]504 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
505 # prevent simultaneous updates of a policy from overwriting each other.
506 # It is strongly suggested that systems make use of the `etag` in the
507 # read-modify-write cycle to perform policy updates in order to avoid race
508 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
509 # systems are expected to put that etag in the request to `setIamPolicy` to
510 # ensure that their change will be applied to the same version of the policy.
511 #
512 # If no `etag` is provided in the call to `setIamPolicy`, then the existing
513 # policy is overwritten blindly.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]514 "version": 42, # Version of the `Policy`. The default version is 0.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]515 }</pre>
516</div>
517
518<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]519 <code class="details" id="list">list(project=None, pageSize=None, pageToken=None, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]520 <pre>Lists matching subscriptions.
521
522Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]523 project: string, The name of the cloud project that subscriptions belong to.
524Format is `projects/{project}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]525 pageSize: integer, Maximum number of subscriptions to return.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]526 pageToken: string, The value returned by the last `ListSubscriptionsResponse`; indicates that
527this is a continuation of a prior `ListSubscriptions` call, and that the
528system should return the next page of data.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]529 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]530 Allowed values
531 1 - v1 error format
532 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]533
534Returns:
535 An object of the form:
536
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]537 { # Response for the `ListSubscriptions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]538 "nextPageToken": "A String", # If not empty, indicates that there may be more subscriptions that match
539 # the request; this value should be passed in a new
540 # `ListSubscriptionsRequest` to get more subscriptions.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]541 "subscriptions": [ # The subscriptions that match the request.
542 { # A subscription resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]543 "ackDeadlineSeconds": 42, # This value is the maximum time after a subscriber receives a message
544 # before the subscriber should acknowledge the message. After message
545 # delivery but before the ack deadline expires and before the message is
546 # acknowledged, it is an outstanding message and will not be delivered
547 # again during that time (on a best-effort basis).
548 #
549 # For pull subscriptions, this value is used as the initial value for the ack
550 # deadline. To override this value for a given message, call
551 # `ModifyAckDeadline` with the corresponding `ack_id` if using
552 # pull.
553 # The minimum custom deadline you can specify is 10 seconds.
554 # The maximum custom deadline you can specify is 600 seconds (10 minutes).
555 # If this parameter is 0, a default value of 10 seconds is used.
556 #
557 # For push delivery, this value is also used to set the request timeout for
558 # the call to the push endpoint.
559 #
560 # If the subscriber never acknowledges the message, the Pub/Sub
561 # system will eventually redeliver the message.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]562 "topic": "A String", # The name of the topic from which this subscription is receiving messages.
563 # Format is `projects/{project}/topics/{topic}`.
564 # The value of this field will be `_deleted-topic_` if the topic has been
565 # deleted.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]566 "pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is
567 # used to configure it. An empty `pushConfig` signifies that the subscriber
568 # will pull and ack messages using API methods.
569 "attributes": { # Endpoint configuration attributes.
570 #
571 # Every endpoint has a set of API supported attributes that can be used to
572 # control different aspects of the message delivery.
573 #
574 # The currently supported attribute is `x-goog-version`, which you can
575 # use to change the format of the push message. This attribute
576 # indicates the version of the data expected by the endpoint. This
577 # controls the shape of the envelope (i.e. its fields and metadata).
578 # The endpoint version is based on the version of the Pub/Sub
579 # API.
580 #
581 # If not present during the `CreateSubscription` call, it will default to
582 # the version of the API used to make such call. If not present during a
583 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
584 # calls will always return a valid version, even if the subscription was
585 # created without this attribute.
586 #
587 # The possible values for this attribute are:
588 #
589 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
590 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]591 "a_key": "A String",
592 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]593 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
594 # For example, a Webhook endpoint might use "https://example.com/push".
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]595 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]596 "name": "A String", # The name of the subscription. It must have the format
597 # `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
598 # start with a letter, and contain only letters (`[A-Za-z]`), numbers
599 # (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
600 # plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
601 # in length, and it must not start with `"goog"`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]602 },
603 ],
604 }</pre>
605</div>
606
607<div class="method">
608 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
609 <pre>Retrieves the next page of results.
610
611Args:
612 previous_request: The request for the previous page. (required)
613 previous_response: The response from the request for the previous page. (required)
614
615Returns:
616 A request object that you can call 'execute()' on to request the next
617 page. Returns None if there are no more items in the collection.
618 </pre>
619</div>
620
621<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]622 <code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription=None, body, x__xgafv=None)</code>
623 <pre>Modifies the ack deadline for a specific message. This method is useful
624to indicate that more time is needed to process a message by the
625subscriber, or to make the message available for redelivery if the
626processing was interrupted. Note that this does not modify the
627subscription-level `ackDeadlineSeconds` used for subsequent messages.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]628
629Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]630 subscription: string, The name of the subscription.
631Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]632 body: object, The request body. (required)
633 The object takes the form of:
634
635{ # Request for the ModifyAckDeadline method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]636 "ackDeadlineSeconds": 42, # The new ack deadline with respect to the time this request was sent to
637 # the Pub/Sub system. For example, if the value is 10, the new
638 # ack deadline will expire 10 seconds after the `ModifyAckDeadline` call
639 # was made. Specifying zero may immediately make the message available for
640 # another pull request.
641 # The minimum deadline you can specify is 0 seconds.
642 # The maximum deadline you can specify is 600 seconds (10 minutes).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]643 "ackIds": [ # List of acknowledgment IDs.
644 "A String",
645 ],
646 }
647
648 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]649 Allowed values
650 1 - v1 error format
651 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]652
653Returns:
654 An object of the form:
655
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]656 { # A generic empty message that you can re-use to avoid defining duplicated
657 # empty messages in your APIs. A typical example is to use it as the request
658 # or the response type of an API method. For instance:
659 #
660 # service Foo {
661 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
662 # }
663 #
664 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]665 }</pre>
666</div>
667
668<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]669 <code class="details" id="modifyPushConfig">modifyPushConfig(subscription=None, body, x__xgafv=None)</code>
670 <pre>Modifies the `PushConfig` for a specified subscription.
671
672This may be used to change a push subscription to a pull one (signified by
673an empty `PushConfig`) or vice versa, or change the endpoint URL and other
674attributes of a push subscription. Messages will accumulate for delivery
675continuously through the call regardless of changes to the `PushConfig`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]676
677Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]678 subscription: string, The name of the subscription.
679Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]680 body: object, The request body. (required)
681 The object takes the form of:
682
683{ # Request for the ModifyPushConfig method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]684 "pushConfig": { # Configuration for a push delivery endpoint. # The push configuration for future deliveries.
685 #
686 # An empty `pushConfig` indicates that the Pub/Sub system should
687 # stop pushing messages from the given subscription and allow
688 # messages to be pulled and acknowledged - effectively pausing
689 # the subscription if `Pull` is not called.
690 "attributes": { # Endpoint configuration attributes.
691 #
692 # Every endpoint has a set of API supported attributes that can be used to
693 # control different aspects of the message delivery.
694 #
695 # The currently supported attribute is `x-goog-version`, which you can
696 # use to change the format of the push message. This attribute
697 # indicates the version of the data expected by the endpoint. This
698 # controls the shape of the envelope (i.e. its fields and metadata).
699 # The endpoint version is based on the version of the Pub/Sub
700 # API.
701 #
702 # If not present during the `CreateSubscription` call, it will default to
703 # the version of the API used to make such call. If not present during a
704 # `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
705 # calls will always return a valid version, even if the subscription was
706 # created without this attribute.
707 #
708 # The possible values for this attribute are:
709 #
710 # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
711 # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]712 "a_key": "A String",
713 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]714 "pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.
715 # For example, a Webhook endpoint might use "https://example.com/push".
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]716 },
717 }
718
719 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]720 Allowed values
721 1 - v1 error format
722 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]723
724Returns:
725 An object of the form:
726
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]727 { # A generic empty message that you can re-use to avoid defining duplicated
728 # empty messages in your APIs. A typical example is to use it as the request
729 # or the response type of an API method. For instance:
730 #
731 # service Foo {
732 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
733 # }
734 #
735 # The JSON representation for `Empty` is empty JSON object `{}`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]736 }</pre>
737</div>
738
739<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]740 <code class="details" id="pull">pull(subscription=None, body, x__xgafv=None)</code>
741 <pre>Pulls messages from the server. Returns an empty list if there are no
742messages available in the backlog. The server may return `UNAVAILABLE` if
743there are too many concurrent pull requests pending for the given
744subscription.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]745
746Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]747 subscription: string, The subscription from which messages should be pulled.
748Format is `projects/{project}/subscriptions/{sub}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]749 body: object, The request body. (required)
750 The object takes the form of:
751
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]752{ # Request for the `Pull` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]753 "returnImmediately": True or False, # If this field set to true, the system will respond immediately even if
754 # it there are no messages available to return in the `Pull` response.
755 # Otherwise, the system may wait (for a bounded amount of time) until at
756 # least one message is available, rather than returning no messages. The
757 # client may cancel the request if it does not wish to wait any longer for
758 # the response.
759 "maxMessages": 42, # The maximum number of messages returned for this request. The Pub/Sub
760 # system may return fewer than the number specified.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]761 }
762
763 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]764 Allowed values
765 1 - v1 error format
766 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]767
768Returns:
769 An object of the form:
770
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]771 { # Response for the `Pull` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]772 "receivedMessages": [ # Received Pub/Sub messages. The Pub/Sub system will return zero messages if
773 # there are no more available in the backlog. The Pub/Sub system may return
774 # fewer than the `maxMessages` requested even if there are more messages
775 # available in the backlog.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]776 { # A message and its corresponding acknowledgment ID.
777 "ackId": "A String", # This ID can be used to acknowledge the received message.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]778 "message": { # A message data and its attributes. The message payload must not be empty; # The message.
779 # it must contain either a non-empty data field, or at least one attribute.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]780 "attributes": { # Optional attributes for this message.
781 "a_key": "A String",
782 },
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]783 "data": "A String", # The message payload.
784 "publishTime": "A String", # The time at which the message was published, populated by the server when
785 # it receives the `Publish` call. It must not be populated by the
786 # publisher in a `Publish` call.
787 "messageId": "A String", # ID of this message, assigned by the server when the message is published.
788 # Guaranteed to be unique within the topic. This value may be read by a
789 # subscriber that receives a `PubsubMessage` via a `Pull` call or a push
790 # delivery. It must not be populated by the publisher in a `Publish` call.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]791 },
792 },
793 ],
794 }</pre>
795</div>
796
797<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]798 <code class="details" id="setIamPolicy">setIamPolicy(resource=None, body, x__xgafv=None)</code>
799 <pre>Sets the access control policy on the specified resource. Replaces any
800existing policy.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]801
802Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]803 resource: string, REQUIRED: The resource for which the policy is being specified.
804`resource` is usually specified as a path. For example, a Project
805resource is specified as `projects/{project}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]806 body: object, The request body. (required)
807 The object takes the form of:
808
809{ # Request message for `SetIamPolicy` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]810 "policy": { # Defines an Identity and Access Management (IAM) policy. It is used to # REQUIRED: The complete policy to be applied to the `resource`. The size of
811 # the policy is limited to a few 10s of KB. An empty policy is a
812 # valid policy but certain Cloud Platform services (such as Projects)
813 # might reject them.
814 # specify access control policies for Cloud Platform resources.
815 #
816 #
817 # A `Policy` consists of a list of `bindings`. A `Binding` binds a list of
818 # `members` to a `role`, where the members can be user accounts, Google groups,
819 # Google domains, and service accounts. A `role` is a named list of permissions
820 # defined by IAM.
821 #
822 # **Example**
823 #
824 # {
825 # "bindings": [
826 # {
827 # "role": "roles/owner",
828 # "members": [
829 # "user:mike@example.com",
830 # "group:admins@example.com",
831 # "domain:google.com",
832 # "serviceAccount:my-other-app@appspot.gserviceaccount.com",
833 # ]
834 # },
835 # {
836 # "role": "roles/viewer",
837 # "members": ["user:sean@example.com"]
838 # }
839 # ]
840 # }
841 #
842 # For a description of IAM and its features, see the
843 # [IAM developer's guide](https://cloud.google.com/iam).
844 "bindings": [ # Associates a list of `members` to a `role`.
845 # Multiple `bindings` must not be specified for the same `role`.
846 # `bindings` with no members will result in an error.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]847 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]848 "role": "A String", # Role that is assigned to `members`.
849 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
850 # Required
851 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
852 # `members` can have the following values:
853 #
854 # * `allUsers`: A special identifier that represents anyone who is
855 # on the internet; with or without a Google account.
856 #
857 # * `allAuthenticatedUsers`: A special identifier that represents anyone
858 # who is authenticated with a Google account or a service account.
859 #
860 # * `user:{emailid}`: An email address that represents a specific Google
861 # account. For example, `alice@gmail.com` or `joe@example.com`.
862 #
863 #
864 # * `serviceAccount:{emailid}`: An email address that represents a service
865 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
866 #
867 # * `group:{emailid}`: An email address that represents a Google group.
868 # For example, `admins@example.com`.
869 #
870 # * `domain:{domain}`: A Google Apps domain name that represents all the
871 # users of that domain. For example, `google.com` or `example.com`.
872 #
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]873 "A String",
874 ],
875 },
876 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]877 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
878 # prevent simultaneous updates of a policy from overwriting each other.
879 # It is strongly suggested that systems make use of the `etag` in the
880 # read-modify-write cycle to perform policy updates in order to avoid race
881 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
882 # systems are expected to put that etag in the request to `setIamPolicy` to
883 # ensure that their change will be applied to the same version of the policy.
884 #
885 # If no `etag` is provided in the call to `setIamPolicy`, then the existing
886 # policy is overwritten blindly.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]887 "version": 42, # Version of the `Policy`. The default version is 0.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]888 },
889 }
890
891 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]892 Allowed values
893 1 - v1 error format
894 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]895
896Returns:
897 An object of the form:
898
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]899 { # Defines an Identity and Access Management (IAM) policy. It is used to
900 # specify access control policies for Cloud Platform resources.
901 #
902 #
903 # A `Policy` consists of a list of `bindings`. A `Binding` binds a list of
904 # `members` to a `role`, where the members can be user accounts, Google groups,
905 # Google domains, and service accounts. A `role` is a named list of permissions
906 # defined by IAM.
907 #
908 # **Example**
909 #
910 # {
911 # "bindings": [
912 # {
913 # "role": "roles/owner",
914 # "members": [
915 # "user:mike@example.com",
916 # "group:admins@example.com",
917 # "domain:google.com",
918 # "serviceAccount:my-other-app@appspot.gserviceaccount.com",
919 # ]
920 # },
921 # {
922 # "role": "roles/viewer",
923 # "members": ["user:sean@example.com"]
924 # }
925 # ]
926 # }
927 #
928 # For a description of IAM and its features, see the
929 # [IAM developer's guide](https://cloud.google.com/iam).
930 "bindings": [ # Associates a list of `members` to a `role`.
931 # Multiple `bindings` must not be specified for the same `role`.
932 # `bindings` with no members will result in an error.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]933 { # Associates `members` with a `role`.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]934 "role": "A String", # Role that is assigned to `members`.
935 # For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
936 # Required
937 "members": [ # Specifies the identities requesting access for a Cloud Platform resource.
938 # `members` can have the following values:
939 #
940 # * `allUsers`: A special identifier that represents anyone who is
941 # on the internet; with or without a Google account.
942 #
943 # * `allAuthenticatedUsers`: A special identifier that represents anyone
944 # who is authenticated with a Google account or a service account.
945 #
946 # * `user:{emailid}`: An email address that represents a specific Google
947 # account. For example, `alice@gmail.com` or `joe@example.com`.
948 #
949 #
950 # * `serviceAccount:{emailid}`: An email address that represents a service
951 # account. For example, `my-other-app@appspot.gserviceaccount.com`.
952 #
953 # * `group:{emailid}`: An email address that represents a Google group.
954 # For example, `admins@example.com`.
955 #
956 # * `domain:{domain}`: A Google Apps domain name that represents all the
957 # users of that domain. For example, `google.com` or `example.com`.
958 #
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]959 "A String",
960 ],
961 },
962 ],
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]963 "etag": "A String", # `etag` is used for optimistic concurrency control as a way to help
964 # prevent simultaneous updates of a policy from overwriting each other.
965 # It is strongly suggested that systems make use of the `etag` in the
966 # read-modify-write cycle to perform policy updates in order to avoid race
967 # conditions: An `etag` is returned in the response to `getIamPolicy`, and
968 # systems are expected to put that etag in the request to `setIamPolicy` to
969 # ensure that their change will be applied to the same version of the policy.
970 #
971 # If no `etag` is provided in the call to `setIamPolicy`, then the existing
972 # policy is overwritten blindly.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]973 "version": 42, # Version of the `Policy`. The default version is 0.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]974 }</pre>
975</div>
976
977<div class="method">
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]978 <code class="details" id="testIamPermissions">testIamPermissions(resource=None, body, x__xgafv=None)</code>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]979 <pre>Returns permissions that a caller has on the specified resource.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]980If the resource does not exist, this will return an empty set of
981permissions, not a NOT_FOUND error.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]982
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]983Note: This operation is designed to be used for building permission-aware
984UIs and command-line tools, not for authorization checking. This operation
985may "fail open" without warning.
986
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]987Args:
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]988 resource: string, REQUIRED: The resource for which the policy detail is being requested.
989`resource` is usually specified as a path. For example, a Project
990resource is specified as `projects/{project}`. (required)
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]991 body: object, The request body. (required)
992 The object takes the form of:
993
994{ # Request message for `TestIamPermissions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]995 "permissions": [ # The set of permissions to check for the `resource`. Permissions with
996 # wildcards (such as '*' or 'storage.*') are not allowed. For more
997 # information see
998 # [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]999 "A String",
1000 ],
1001 }
1002
1003 x__xgafv: string, V1 error format.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1004 Allowed values
1005 1 - v1 error format
1006 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1007
1008Returns:
1009 An object of the form:
1010
1011 { # Response message for `TestIamPermissions` method.
Jon Wayne Parrott692617a2017-01-06 09:58:29 -0800[diff] [blame]1012 "permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is
1013 # allowed.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1014 "A String",
1015 ],
1016 }</pre>
1017</div>
1018
1019</body></html>