Blame - docs/dyn/pubsub_v1.projects.subscriptions.html - platform/external/python/google-api-python-client

2015-09-11 13:55:40 -0700

[diff] [blame]

76

<h2>Instance Methods</h2>

77

Dan O'Meara

2020-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 Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

79

<p class="firstline">Acknowledges the messages associated with the `ack_ids` in the</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

80

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

81

<code><a href="#create">create(name, body=None, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

82

<p class="firstline">Creates a subscription to a given topic. See the</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

83

Thomas Coffee

2f24537

2017-03-27 10:39:26 -0700

[diff] [blame]

84

<code><a href="#delete">delete(subscription, x__xgafv=None)</a></code></p>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

85

<p class="firstline">Deletes an existing subscription. All messages retained in the subscription</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

86

Thomas Coffee

2f24537

2017-03-27 10:39:26 -0700

[diff] [blame]

87

<code><a href="#get">get(subscription, x__xgafv=None)</a></code></p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

88

<p class="firstline">Gets the configuration details of a subscription.</p>

89

Dan O'Meara

2020-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 Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

91

<p class="firstline">Gets the access control policy for a resource.</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

92

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

93

<code><a href="#list">list(project, pageToken=None, pageSize=None, x__xgafv=None)</a></code></p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

94

<p class="firstline">Lists matching subscriptions.</p>

95

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

Dan O'Meara

2020-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 Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

100

<p class="firstline">Modifies the ack deadline for a specific message. This method is useful</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

101

Dan O'Meara

2020-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 Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

103

<p class="firstline">Modifies the `PushConfig` for a specified subscription.</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

104

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

105

<code><a href="#patch">patch(name, body=None, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

106

<p class="firstline">Updates an existing subscription. Note that certain properties of a</p>

107

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

108

<code><a href="#pull">pull(subscription, body=None, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

109

<p class="firstline">Pulls messages from the server. The server may return `UNAVAILABLE` if</p>

110

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

111

<code><a href="#seek">seek(subscription, body=None, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

112

<p class="firstline">Seeks an existing subscription to a point in time or to a given snapshot,</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

113

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

114

<code><a href="#setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</a></code></p>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

115

<p class="firstline">Sets the access control policy on the specified resource. Replaces any</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

116

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

117

<code><a href="#testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</a></code></p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

118

<p class="firstline">Returns permissions that a caller has on the specified resource.</p>

119

<h3>Method Details</h3>

120

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

121

<code class="details" id="acknowledge">acknowledge(subscription, body=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

122

<pre>Acknowledges the messages associated with the `ack_ids` in the

123

`AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages

124

from the subscription.

125

126

Acknowledging a message whose ack deadline has expired may succeed,

127

but such a message may be redelivered later. Acknowledging a message more

128

than once will not result in an error.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

129

130

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

131

subscription: string, Required. The subscription whose message is being acknowledged.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

132

Format is `projects/{project}/subscriptions/{sub}`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

133

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

134

The object takes the form of:

135

136

{ # Request for the Acknowledge method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

137

"ackIds": [ # Required. The acknowledgment ID for the messages being acknowledged that was returned

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

138

# by the Pub/Sub system in the `Pull` response. Must not be empty.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

139

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

],

}

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

144

Allowed values

145

1 - v1 error format

146

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

147

148

Returns:

149

An object of the form:

150

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

151

{ # A generic empty message that you can re-use to avoid defining duplicated

152

# empty messages in your APIs. A typical example is to use it as the request

153

# or the response type of an API method. For instance:

154

#

155

# service Foo {

156

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

157

# }

158

#

159

# The JSON representation for `Empty` is empty JSON object `{}`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

164

<code class="details" id="create">create(name, body=None, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

165

<pre>Creates a subscription to a given topic. See the

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

166

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

167

resource name rules</a>.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

168

If the subscription already exists, returns `ALREADY_EXISTS`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

169

If the corresponding topic doesn't exist, returns `NOT_FOUND`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

170

171

If the name is not provided in the request, the server will assign a random

172

name for this subscription on the same project as the topic, conforming

173

to the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

174

[resource name

175

format](https://cloud.google.com/pubsub/docs/admin#resource_names). The

176

generated name is populated in the returned Subscription object. Note that

177

for REST API requests, you must specify a name in the request.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

178

179

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

180

name: string, Required. The name of the subscription. It must have the format

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

181

`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

182

start with a letter, and contain only letters (`[A-Za-z]`), numbers

183

(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

184

plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

185

in length, and it must not start with `"goog"`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

186

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

187

The object takes the form of:

188

189

{ # A subscription resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

190

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

191

# used to configure it. An empty `pushConfig` signifies that the subscriber

192

# will pull and ack messages using API methods.

193

"attributes": { # Endpoint configuration attributes that can be used to control different

194

# aspects of the message delivery.

195

#

196

# The only currently supported attribute is `x-goog-version`, which you can

197

# use to change the format of the pushed message. This attribute

198

# indicates the version of the data expected by the endpoint. This

199

# controls the shape of the pushed message (i.e., its fields and metadata).

200

#

201

# If not present during the `CreateSubscription` call, it will default to

202

# the version of the Pub/Sub API used to make such call. If not present in a

203

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

204

# calls will always return a valid version, even if the subscription was

205

# created without this attribute.

206

#

207

# The only supported values for the `x-goog-version` attribute are:

208

#

209

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

210

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

211

#

212

# For example:

213

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

214

"a_key": "A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

215

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

216

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

217

# For example, a Webhook endpoint might use `https://example.com/push`.

218

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

219

# `Authorization` header in the HTTP request for every pushed message.

220

# [OpenID Connect

221

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

222

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

223

# identifies the recipients that the JWT is intended for. The audience

224

# value is a single case-sensitive string. Having multiple values (array)

225

# for the audience field is not supported. More info about the OIDC JWT

226

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

227

# Note: if not specified, the Push endpoint URL will be used.

228

"serviceAccountEmail": "A String", # [Service account

229

# email](https://cloud.google.com/iam/docs/service-accounts)

230

# to be used for generating the OIDC token. The caller (for

231

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

232

# have the iam.serviceAccounts.actAs permission for the service account.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

233

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

234

},

235

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

236

# then only `PubsubMessage`s whose `attributes` field matches the filter are

237

# delivered on this subscription. If empty, then no messages are filtered

238

# out.

239

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

240

# API might be changed in backward-incompatible ways and is not recommended

241

# for production use. It is not subject to any SLA or deprecation policy.

242

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

243

# the subscriber to acknowledge receipt before resending the message. In the

244

# interval after the message is delivered and before it is acknowledged, it

245

# is considered to be <i>outstanding</i>. During that time period, the

246

# message will not be redelivered (on a best-effort basis).

247

#

248

# For pull subscriptions, this value is used as the initial value for the ack

249

# deadline. To override this value for a given message, call

250

# `ModifyAckDeadline` with the corresponding `ack_id` if using

251

# non-streaming pull or send the `ack_id` in a

252

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

253

# The minimum custom deadline you can specify is 10 seconds.

254

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

255

# If this parameter is 0, a default value of 10 seconds is used.

256

#

257

# For push delivery, this value is also used to set the request timeout for

258

# the call to the push endpoint.

259

#

260

# If the subscriber never acknowledges the message, the Pub/Sub

261

# system will eventually redeliver the message.

262

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

263

# from the moment a message is published.

264

# If `retain_acked_messages` is true, then this also configures the retention

265

# of acknowledged messages, and thus configures how far back in time a `Seek`

266

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

267

# minutes.

268

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

269

# messages are not expunged from the subscription's backlog, even if they are

270

# acknowledged, until they fall out of the `message_retention_duration`

271

# window. This must be true if you would like to

272

# <a

273

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

274

# Seek to a timestamp</a>.

275

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

276

# managing labels</a>.

277

"a_key": "A String",

278

},

279

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

280

# this subscription. If dead_letter_policy is not set, dead lettering

281

# is disabled.

282

#

283

# The Cloud Pub/Sub service account associated with this subscriptions's

284

# parent project (i.e.,

285

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

286

# permission to Acknowledge() messages on this subscription.

287

# dead lettered multiple times.

288

#

289

# If validation on any of the fields fails at subscription creation/updation,

290

# the create/update subscription request will fail.

291

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

292

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

293

# account associated with the enclosing subscription's parent project (i.e.,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

294

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

295

# permission to Publish() to this topic.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

296

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

297

# The operation will fail if the topic does not exist.

298

# Users should ensure that there is a subscription attached to this topic

299

# since messages published to a topic with no subscriptions are lost.

300

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

301

# between 5 and 100.

302

#

303

# The number of delivery attempts is defined as 1 + (the sum of number of

304

# NACKs and number of times the acknowledgement deadline has been exceeded

305

# for the message).

306

#

307

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

308

# client libraries may automatically extend ack_deadlines.

309

#

310

# This field will be honored on a best effort basis.

311

#

312

# If this parameter is 0, a default value of 5 is used.

313

},

314

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

315

# A subscription is considered active as long as any connected subscriber is

316

# successfully consuming messages from the subscription or is issuing

317

# operations on the subscription. If `expiration_policy` is not set, a

318

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

319

# value for `expiration_policy.ttl` is 1 day.

320

# automatic resource deletion).

321

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

322

# resource expires if it is not active for a period of `ttl`. The definition

323

# of "activity" depends on the type of the associated resource. The minimum

324

# and maximum allowed values for `ttl` depend on the type of the associated

325

# resource, as well. If `ttl` is not set, the associated resource never

326

# expires.

327

},

328

"name": "A String", # Required. 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"`.

334

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

335

# Format is `projects/{project}/topics/{topic}`.

336

# The value of this field will be `_deleted-topic_` if the topic has been

# deleted.

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

347

348

{ # A subscription resource.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

349

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

350

# used to configure it. An empty `pushConfig` signifies that the subscriber

351

# will pull and ack messages using API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

352

"attributes": { # Endpoint configuration attributes that can be used to control different

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

353

# aspects of the message delivery.

354

#

355

# The only currently supported attribute is `x-goog-version`, which you can

356

# use to change the format of the pushed message. This attribute

357

# indicates the version of the data expected by the endpoint. This

358

# controls the shape of the pushed message (i.e., its fields and metadata).

359

#

360

# If not present during the `CreateSubscription` call, it will default to

361

# the version of the Pub/Sub API used to make such call. If not present in a

362

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

363

# calls will always return a valid version, even if the subscription was

364

# created without this attribute.

365

#

366

# The only supported values for the `x-goog-version` attribute are:

367

#

368

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

369

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

370

#

371

# For example:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

372

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

373

"a_key": "A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

374

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

375

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

376

# For example, a Webhook endpoint might use `https://example.com/push`.

377

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

378

# `Authorization` header in the HTTP request for every pushed message.

379

# [OpenID Connect

380

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

381

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

382

# identifies the recipients that the JWT is intended for. The audience

383

# value is a single case-sensitive string. Having multiple values (array)

384

# for the audience field is not supported. More info about the OIDC JWT

385

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

386

# Note: if not specified, the Push endpoint URL will be used.

387

"serviceAccountEmail": "A String", # [Service account

388

# email](https://cloud.google.com/iam/docs/service-accounts)

389

# to be used for generating the OIDC token. The caller (for

390

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

391

# have the iam.serviceAccounts.actAs permission for the service account.

392

},

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

393

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

394

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

395

# then only `PubsubMessage`s whose `attributes` field matches the filter are

396

# delivered on this subscription. If empty, then no messages are filtered

397

# out.

398

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

399

# API might be changed in backward-incompatible ways and is not recommended

400

# for production use. It is not subject to any SLA or deprecation policy.

401

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

402

# the subscriber to acknowledge receipt before resending the message. In the

403

# interval after the message is delivered and before it is acknowledged, it

404

# is considered to be <i>outstanding</i>. During that time period, the

405

# message will not be redelivered (on a best-effort basis).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

406

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

407

# For pull subscriptions, this value is used as the initial value for the ack

408

# deadline. To override this value for a given message, call

409

# `ModifyAckDeadline` with the corresponding `ack_id` if using

410

# non-streaming pull or send the `ack_id` in a

411

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

412

# The minimum custom deadline you can specify is 10 seconds.

413

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

414

# If this parameter is 0, a default value of 10 seconds is used.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

415

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

416

# For push delivery, this value is also used to set the request timeout for

417

# the call to the push endpoint.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

418

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

419

# If the subscriber never acknowledges the message, the Pub/Sub

420

# system will eventually redeliver the message.

421

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

422

# from the moment a message is published.

423

# If `retain_acked_messages` is true, then this also configures the retention

424

# of acknowledged messages, and thus configures how far back in time a `Seek`

425

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

426

# minutes.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

427

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

428

# messages are not expunged from the subscription's backlog, even if they are

429

# acknowledged, until they fall out of the `message_retention_duration`

430

# window. This must be true if you would like to

431

# <a

432

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

433

# Seek to a timestamp</a>.

434

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

435

# managing labels</a>.

436

"a_key": "A String",

437

},

438

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

439

# this subscription. If dead_letter_policy is not set, dead lettering

440

# is disabled.

441

#

442

# The Cloud Pub/Sub service account associated with this subscriptions's

443

# parent project (i.e.,

444

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

445

# permission to Acknowledge() messages on this subscription.

446

# dead lettered multiple times.

447

#

448

# If validation on any of the fields fails at subscription creation/updation,

449

# the create/update subscription request will fail.

450

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

451

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

452

# account associated with the enclosing subscription's parent project (i.e.,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

453

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

454

# permission to Publish() to this topic.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

455

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

456

# The operation will fail if the topic does not exist.

457

# Users should ensure that there is a subscription attached to this topic

458

# since messages published to a topic with no subscriptions are lost.

459

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

460

# between 5 and 100.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

461

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

462

# The number of delivery attempts is defined as 1 + (the sum of number of

463

# NACKs and number of times the acknowledgement deadline has been exceeded

464

# for the message).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

465

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

466

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

467

# client libraries may automatically extend ack_deadlines.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

468

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

469

# This field will be honored on a best effort basis.

470

#

471

# If this parameter is 0, a default value of 5 is used.

472

},

473

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

474

# A subscription is considered active as long as any connected subscriber is

475

# successfully consuming messages from the subscription or is issuing

476

# operations on the subscription. If `expiration_policy` is not set, a

477

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

478

# value for `expiration_policy.ttl` is 1 day.

479

# automatic resource deletion).

480

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

481

# resource expires if it is not active for a period of `ttl`. The definition

482

# of "activity" depends on the type of the associated resource. The minimum

483

# and maximum allowed values for `ttl` depend on the type of the associated

484

# resource, as well. If `ttl` is not set, the associated resource never

485

# expires.

486

},

487

"name": "A String", # Required. The name of the subscription. It must have the format

488

# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

489

# start with a letter, and contain only letters (`[A-Za-z]`), numbers

490

# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

491

# plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

492

# in length, and it must not start with `"goog"`.

493

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

494

# Format is `projects/{project}/topics/{topic}`.

495

# The value of this field will be `_deleted-topic_` if the topic has been

496

# deleted.

497

}</pre>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

501

<code class="details" id="delete">delete(subscription, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

502

<pre>Deletes an existing subscription. All messages retained in the subscription

503

are immediately dropped. Calls to `Pull` after deletion will return

504

`NOT_FOUND`. After a subscription is deleted, a new one may be created with

505

the same name, but the new one has no association with the old

506

subscription or its topic unless the same topic is specified.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

507

508

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

509

subscription: string, Required. The subscription to delete.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

510

Format is `projects/{project}/subscriptions/{sub}`. (required)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

511

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

512

Allowed values

513

1 - v1 error format

514

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

515

516

Returns:

517

An object of the form:

518

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

519

{ # A generic empty message that you can re-use to avoid defining duplicated

520

# empty messages in your APIs. A typical example is to use it as the request

521

# or the response type of an API method. For instance:

522

#

523

# service Foo {

524

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

525

# }

526

#

527

# The JSON representation for `Empty` is empty JSON object `{}`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

532

<code class="details" id="get">get(subscription, x__xgafv=None)</code>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

533

<pre>Gets the configuration details of a subscription.

534

535

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

536

subscription: string, Required. The name of the subscription to get.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

537

Format is `projects/{project}/subscriptions/{sub}`. (required)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

538

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

539

Allowed values

540

1 - v1 error format

541

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

542

543

Returns:

544

An object of the form:

545

546

{ # A subscription resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

547

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

548

# used to configure it. An empty `pushConfig` signifies that the subscriber

549

# will pull and ack messages using API methods.

550

"attributes": { # Endpoint configuration attributes that can be used to control different

551

# aspects of the message delivery.

552

#

553

# The only currently supported attribute is `x-goog-version`, which you can

554

# use to change the format of the pushed message. This attribute

555

# indicates the version of the data expected by the endpoint. This

556

# controls the shape of the pushed message (i.e., its fields and metadata).

557

#

558

# If not present during the `CreateSubscription` call, it will default to

559

# the version of the Pub/Sub API used to make such call. If not present in a

560

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

561

# calls will always return a valid version, even if the subscription was

562

# created without this attribute.

563

#

564

# The only supported values for the `x-goog-version` attribute are:

565

#

566

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

567

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

568

#

569

# For example:

570

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

571

"a_key": "A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

572

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

573

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

574

# For example, a Webhook endpoint might use `https://example.com/push`.

575

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

576

# `Authorization` header in the HTTP request for every pushed message.

577

# [OpenID Connect

578

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

579

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

580

# identifies the recipients that the JWT is intended for. The audience

581

# value is a single case-sensitive string. Having multiple values (array)

582

# for the audience field is not supported. More info about the OIDC JWT

583

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

584

# Note: if not specified, the Push endpoint URL will be used.

585

"serviceAccountEmail": "A String", # [Service account

586

# email](https://cloud.google.com/iam/docs/service-accounts)

587

# to be used for generating the OIDC token. The caller (for

588

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

589

# have the iam.serviceAccounts.actAs permission for the service account.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

590

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

591

},

592

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

593

# then only `PubsubMessage`s whose `attributes` field matches the filter are

594

# delivered on this subscription. If empty, then no messages are filtered

595

# out.

596

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

597

# API might be changed in backward-incompatible ways and is not recommended

598

# for production use. It is not subject to any SLA or deprecation policy.

599

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

600

# the subscriber to acknowledge receipt before resending the message. In the

601

# interval after the message is delivered and before it is acknowledged, it

602

# is considered to be <i>outstanding</i>. During that time period, the

603

# message will not be redelivered (on a best-effort basis).

604

#

605

# For pull subscriptions, this value is used as the initial value for the ack

606

# deadline. To override this value for a given message, call

607

# `ModifyAckDeadline` with the corresponding `ack_id` if using

608

# non-streaming pull or send the `ack_id` in a

609

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

610

# The minimum custom deadline you can specify is 10 seconds.

611

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

612

# If this parameter is 0, a default value of 10 seconds is used.

613

#

614

# For push delivery, this value is also used to set the request timeout for

615

# the call to the push endpoint.

616

#

617

# If the subscriber never acknowledges the message, the Pub/Sub

618

# system will eventually redeliver the message.

619

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

620

# from the moment a message is published.

621

# If `retain_acked_messages` is true, then this also configures the retention

622

# of acknowledged messages, and thus configures how far back in time a `Seek`

623

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

624

# minutes.

625

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

626

# messages are not expunged from the subscription's backlog, even if they are

627

# acknowledged, until they fall out of the `message_retention_duration`

628

# window. This must be true if you would like to

629

# <a

630

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

631

# Seek to a timestamp</a>.

632

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

633

# managing labels</a>.

634

"a_key": "A String",

635

},

636

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

637

# this subscription. If dead_letter_policy is not set, dead lettering

638

# is disabled.

639

#

640

# The Cloud Pub/Sub service account associated with this subscriptions's

641

# parent project (i.e.,

642

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

643

# permission to Acknowledge() messages on this subscription.

644

# dead lettered multiple times.

645

#

646

# If validation on any of the fields fails at subscription creation/updation,

647

# the create/update subscription request will fail.

648

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

649

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

650

# account associated with the enclosing subscription's parent project (i.e.,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

651

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

652

# permission to Publish() to this topic.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

653

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

654

# The operation will fail if the topic does not exist.

655

# Users should ensure that there is a subscription attached to this topic

656

# since messages published to a topic with no subscriptions are lost.

657

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

658

# between 5 and 100.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

659

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

660

# The number of delivery attempts is defined as 1 + (the sum of number of

661

# NACKs and number of times the acknowledgement deadline has been exceeded

662

# for the message).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

663

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

664

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

665

# client libraries may automatically extend ack_deadlines.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

666

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

667

# This field will be honored on a best effort basis.

668

#

669

# If this parameter is 0, a default value of 5 is used.

670

},

671

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

672

# A subscription is considered active as long as any connected subscriber is

673

# successfully consuming messages from the subscription or is issuing

674

# operations on the subscription. If `expiration_policy` is not set, a

675

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

676

# value for `expiration_policy.ttl` is 1 day.

677

# automatic resource deletion).

678

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

679

# resource expires if it is not active for a period of `ttl`. The definition

680

# of "activity" depends on the type of the associated resource. The minimum

681

# and maximum allowed values for `ttl` depend on the type of the associated

682

# resource, as well. If `ttl` is not set, the associated resource never

683

# expires.

684

},

685

"name": "A String", # Required. The name of the subscription. It must have the format

686

# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

687

# start with a letter, and contain only letters (`[A-Za-z]`), numbers

688

# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

689

# plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

690

# in length, and it must not start with `"goog"`.

691

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

692

# Format is `projects/{project}/topics/{topic}`.

693

# The value of this field will be `_deleted-topic_` if the topic has been

694

# deleted.

695

}</pre>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

699

<code class="details" id="getIamPolicy">getIamPolicy(resource, options_requestedPolicyVersion=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

700

<pre>Gets the access control policy for a resource.

701

Returns an empty policy if the resource exists and does not have a policy

702

set.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

703

704

Args:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

705

resource: string, REQUIRED: The resource for which the policy is being requested.

Sai Cheemalapati

e833b79

2017-03-24 15:06:46 -0700

[diff] [blame]

706

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

707

options_requestedPolicyVersion: integer, Optional. The policy format version to be returned.

708

709

Valid values are 0, 1, and 3. Requests specifying an invalid value will be

710

rejected.

711

712

Requests for policies with any conditional bindings must specify version 3.

713

Policies without any conditional bindings may specify any valid value or

714

leave the field unset.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

715

716

To learn which resources support conditions in their IAM policies, see the

717

[IAM

718

documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

719

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

720

Allowed values

721

1 - v1 error format

722

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

723

724

Returns:

725

An object of the form:

726

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

727

{ # An Identity and Access Management (IAM) policy, which specifies access

728

# controls for Google Cloud resources.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

729

#

730

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

731

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

732

# `members` to a single `role`. Members can be user accounts, service accounts,

733

# Google groups, and domains (such as G Suite). A `role` is a named list of

734

# permissions; each `role` can be an IAM predefined role or a user-created

735

# custom role.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

736

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

737

# For some types of Google Cloud resources, a `binding` can also specify a

738

# `condition`, which is a logical expression that allows access to a resource

739

# only if the expression evaluates to `true`. A condition can add constraints

740

# based on attributes of the request, the resource, or both. To learn which

741

# resources support conditions in their IAM policies, see the

742

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

743

#

744

# **JSON example:**

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

745

#

746

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

747

# "bindings": [

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

748

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

749

# "role": "roles/resourcemanager.organizationAdmin",

750

# "members": [

751

# "user:mike@example.com",

752

# "group:admins@example.com",

753

# "domain:google.com",

754

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

755

# ]

756

# },

757

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

758

# "role": "roles/resourcemanager.organizationViewer",

759

# "members": [

760

# "user:eve@example.com"

761

# ],

762

# "condition": {

763

# "title": "expirable access",

764

# "description": "Does not grant access after Sep 2020",

765

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

766

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

767

# }

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

768

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

769

# "etag": "BwWWja0YfJA=",

770

# "version": 3

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

771

# }

772

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

773

# **YAML example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

778

# - group:admins@example.com

779

# - domain:google.com

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

780

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

781

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

782

# - members:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

783

# - user:eve@example.com

784

# role: roles/resourcemanager.organizationViewer

785

# condition:

786

# title: expirable access

787

# description: Does not grant access after Sep 2020

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

788

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

789

# - etag: BwWWja0YfJA=

790

# - version: 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

791

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

792

# For a description of IAM and its features, see the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

793

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

794

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

795

# `condition` that determines how and when the `bindings` are applied. Each

796

# of the `bindings` must contain at least one member.

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

797

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

798

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

799

#

800

# If the condition evaluates to `true`, then this binding applies to the

801

# current request.

802

#

803

# If the condition evaluates to `false`, then this binding does not apply to

804

# the current request. However, a different role binding might grant the same

805

# role to one or more of the members in this binding.

806

#

807

# To learn which resources support conditions in their IAM policies, see the

808

# [IAM

809

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

810

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

811

# are documented at https://github.com/google/cel-spec.

812

#

813

# Example (Comparison):

814

#

815

# title: "Summary size limit"

816

# description: "Determines if a summary is less than 100 chars"

817

# expression: "document.summary.size() < 100"

818

#

819

# Example (Equality):

820

#

821

# title: "Requestor is owner"

822

# description: "Determines if requestor is the document owner"

823

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

828

# description: "Determine whether the document should be publicly visible"

829

# expression: "document.type != 'private' && document.type != 'internal'"

830

#

831

# Example (Data Manipulation):

832

#

833

# title: "Notification string"

834

# description: "Create a notification string with a timestamp."

835

# expression: "'New message received at ' + string(document.create_time)"

836

#

837

# The exact variables and functions that may be referenced within an expression

838

# are determined by the service that evaluates it. See the service

839

# documentation for additional information.

840

"location": "A String", # Optional. String indicating the location of the expression for error

841

# reporting, e.g. a file name and a position in the file.

842

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

843

# its purpose. This can be used e.g. in UIs which allow to enter the

844

# expression.

845

"description": "A String", # Optional. Description of the expression. This is a longer text which

846

# describes the expression, e.g. when hovered over it in a UI.

847

"expression": "A String", # Textual representation of an expression in Common Expression Language

848

# syntax.

849

},

850

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

851

# `members` can have the following values:

852

#

853

# * `allUsers`: A special identifier that represents anyone who is

854

# on the internet; with or without a Google account.

855

#

856

# * `allAuthenticatedUsers`: A special identifier that represents anyone

857

# who is authenticated with a Google account or a service account.

858

#

859

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

860

# account. For example, `alice@example.com` .

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

861

#

862

#

863

# * `serviceAccount:{emailid}`: An email address that represents a service

864

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

865

#

866

# * `group:{emailid}`: An email address that represents a Google group.

867

# For example, `admins@example.com`.

868

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

869

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

870

# identifier) representing a user that has been recently deleted. For

871

# example, `alice@example.com?uid=123456789012345678901`. If the user is

872

# recovered, this value reverts to `user:{emailid}` and the recovered user

873

# retains the role in the binding.

874

#

875

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

876

# unique identifier) representing a service account that has been recently

877

# deleted. For example,

878

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

879

# If the service account is undeleted, this value reverts to

880

# `serviceAccount:{emailid}` and the undeleted service account retains the

881

# role in the binding.

882

#

883

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

884

# identifier) representing a Google group that has been recently

885

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

886

# the group is recovered, this value reverts to `group:{emailid}` and the

887

# recovered group retains the role in the binding.

888

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

889

#

890

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

891

# users of that domain. For example, `google.com` or `example.com`.

892

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

893

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

894

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

895

"role": "A String", # Role that is assigned to `members`.

896

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

897

},

898

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

899

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

900

# prevent simultaneous updates of a policy from overwriting each other.

901

# It is strongly suggested that systems make use of the `etag` in the

902

# read-modify-write cycle to perform policy updates in order to avoid race

903

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

904

# systems are expected to put that etag in the request to `setIamPolicy` to

905

# ensure that their change will be applied to the same version of the policy.

906

#

907

# **Important:** If you use IAM Conditions, you must include the `etag` field

908

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

909

# you to overwrite a version `3` policy with a version `1` policy, and all of

910

# the conditions in the version `3` policy are lost.

911

"version": 42, # Specifies the format of the policy.

912

#

913

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

914

# are rejected.

915

#

916

# Any operation that affects conditional role bindings must specify version

917

# `3`. This requirement applies to the following operations:

918

#

919

# * Getting a policy that includes a conditional role binding

920

# * Adding a conditional role binding to a policy

921

# * Changing a conditional role binding in a policy

922

# * Removing any role binding, with or without a condition, from a policy

923

# that includes conditions

924

#

925

# **Important:** If you use IAM Conditions, you must include the `etag` field

926

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

927

# you to overwrite a version `3` policy with a version `1` policy, and all of

928

# the conditions in the version `3` policy are lost.

929

#

930

# If a policy does not include any conditions, operations on that policy may

931

# specify any valid version or leave the field unset.

932

#

933

# To learn which resources support conditions in their IAM policies, see the

934

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

939

<code class="details" id="list">list(project, pageToken=None, pageSize=None, x__xgafv=None)</code>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

940

<pre>Lists matching subscriptions.

941

942

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

943

project: string, Required. The name of the project in which to list subscriptions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

944

Format is `projects/{project-id}`. (required)

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

945

pageToken: string, The value returned by the last `ListSubscriptionsResponse`; indicates that

946

this is a continuation of a prior `ListSubscriptions` call, and that the

947

system should return the next page of data.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

948

pageSize: integer, Maximum number of subscriptions to return.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

949

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

950

Allowed values

951

1 - v1 error format

952

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

953

954

Returns:

955

An object of the form:

956

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

957

{ # Response for the `ListSubscriptions` method.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

958

"subscriptions": [ # The subscriptions that match the request.

959

{ # A subscription resource.

960

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

961

# used to configure it. An empty `pushConfig` signifies that the subscriber

962

# will pull and ack messages using API methods.

963

"attributes": { # Endpoint configuration attributes that can be used to control different

964

# aspects of the message delivery.

965

#

966

# The only currently supported attribute is `x-goog-version`, which you can

967

# use to change the format of the pushed message. This attribute

968

# indicates the version of the data expected by the endpoint. This

969

# controls the shape of the pushed message (i.e., its fields and metadata).

970

#

971

# If not present during the `CreateSubscription` call, it will default to

972

# the version of the Pub/Sub API used to make such call. If not present in a

973

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

974

# calls will always return a valid version, even if the subscription was

975

# created without this attribute.

976

#

977

# The only supported values for the `x-goog-version` attribute are:

978

#

979

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

980

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

981

#

982

# For example:

983

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

984

"a_key": "A String",

985

},

986

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

987

# For example, a Webhook endpoint might use `https://example.com/push`.

988

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

989

# `Authorization` header in the HTTP request for every pushed message.

990

# [OpenID Connect

991

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

992

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

993

# identifies the recipients that the JWT is intended for. The audience

994

# value is a single case-sensitive string. Having multiple values (array)

995

# for the audience field is not supported. More info about the OIDC JWT

996

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

997

# Note: if not specified, the Push endpoint URL will be used.

998

"serviceAccountEmail": "A String", # [Service account

999

# email](https://cloud.google.com/iam/docs/service-accounts)

1000

# to be used for generating the OIDC token. The caller (for

1001

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

1002

# have the iam.serviceAccounts.actAs permission for the service account.

1003

},

1004

},

1005

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

1006

# then only `PubsubMessage`s whose `attributes` field matches the filter are

1007

# delivered on this subscription. If empty, then no messages are filtered

1008

# out.

1009

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

1010

# API might be changed in backward-incompatible ways and is not recommended

1011

# for production use. It is not subject to any SLA or deprecation policy.

1012

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

1013

# the subscriber to acknowledge receipt before resending the message. In the

1014

# interval after the message is delivered and before it is acknowledged, it

1015

# is considered to be <i>outstanding</i>. During that time period, the

1016

# message will not be redelivered (on a best-effort basis).

1017

#

1018

# For pull subscriptions, this value is used as the initial value for the ack

1019

# deadline. To override this value for a given message, call

1020

# `ModifyAckDeadline` with the corresponding `ack_id` if using

1021

# non-streaming pull or send the `ack_id` in a

1022

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

1023

# The minimum custom deadline you can specify is 10 seconds.

1024

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

1025

# If this parameter is 0, a default value of 10 seconds is used.

1026

#

1027

# For push delivery, this value is also used to set the request timeout for

1028

# the call to the push endpoint.

1029

#

1030

# If the subscriber never acknowledges the message, the Pub/Sub

1031

# system will eventually redeliver the message.

1032

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

1033

# from the moment a message is published.

1034

# If `retain_acked_messages` is true, then this also configures the retention

1035

# of acknowledged messages, and thus configures how far back in time a `Seek`

1036

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

1037

# minutes.

1038

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

1039

# messages are not expunged from the subscription's backlog, even if they are

1040

# acknowledged, until they fall out of the `message_retention_duration`

1041

# window. This must be true if you would like to

1042

# <a

1043

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

1044

# Seek to a timestamp</a>.

1045

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

1046

# managing labels</a>.

1047

"a_key": "A String",

1048

},

1049

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

1050

# this subscription. If dead_letter_policy is not set, dead lettering

1051

# is disabled.

1052

#

1053

# The Cloud Pub/Sub service account associated with this subscriptions's

1054

# parent project (i.e.,

1055

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1056

# permission to Acknowledge() messages on this subscription.

1057

# dead lettered multiple times.

1058

#

1059

# If validation on any of the fields fails at subscription creation/updation,

1060

# the create/update subscription request will fail.

1061

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

1062

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

1063

# account associated with the enclosing subscription's parent project (i.e.,

1064

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1065

# permission to Publish() to this topic.

1066

#

1067

# The operation will fail if the topic does not exist.

1068

# Users should ensure that there is a subscription attached to this topic

1069

# since messages published to a topic with no subscriptions are lost.

1070

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

1071

# between 5 and 100.

1072

#

1073

# The number of delivery attempts is defined as 1 + (the sum of number of

1074

# NACKs and number of times the acknowledgement deadline has been exceeded

1075

# for the message).

1076

#

1077

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

1078

# client libraries may automatically extend ack_deadlines.

1079

#

1080

# This field will be honored on a best effort basis.

1081

#

1082

# If this parameter is 0, a default value of 5 is used.

1083

},

1084

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

1085

# A subscription is considered active as long as any connected subscriber is

1086

# successfully consuming messages from the subscription or is issuing

1087

# operations on the subscription. If `expiration_policy` is not set, a

1088

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

1089

# value for `expiration_policy.ttl` is 1 day.

1090

# automatic resource deletion).

1091

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

1092

# resource expires if it is not active for a period of `ttl`. The definition

1093

# of "activity" depends on the type of the associated resource. The minimum

1094

# and maximum allowed values for `ttl` depend on the type of the associated

1095

# resource, as well. If `ttl` is not set, the associated resource never

1096

# expires.

1097

},

1098

"name": "A String", # Required. The name of the subscription. It must have the format

1099

# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

1100

# start with a letter, and contain only letters (`[A-Za-z]`), numbers

1101

# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

1102

# plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

1103

# in length, and it must not start with `"goog"`.

1104

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

1105

# Format is `projects/{project}/topics/{topic}`.

1106

# The value of this field will be `_deleted-topic_` if the topic has been

1107

# deleted.

1108

},

1109

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1110

"nextPageToken": "A String", # If not empty, indicates that there may be more subscriptions that match

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1111

# the request; this value should be passed in a new

1112

# `ListSubscriptionsRequest` to get more subscriptions.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

1118

<pre>Retrieves the next page of results.

1119

1120

Args:

1121

previous_request: The request for the previous page. (required)

1122

previous_response: The response from the request for the previous page. (required)

1123

1124

Returns:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1125

A request object that you can call 'execute()' on to request the next

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1126

page. Returns None if there are no more items in the collection.

</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1131

<code class="details" id="modifyAckDeadline">modifyAckDeadline(subscription, body=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1132

<pre>Modifies the ack deadline for a specific message. This method is useful

1133

to indicate that more time is needed to process a message by the

1134

subscriber, or to make the message available for redelivery if the

1135

processing was interrupted. Note that this does not modify the

1136

subscription-level `ackDeadlineSeconds` used for subsequent messages.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1137

1138

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1139

subscription: string, Required. The name of the subscription.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1140

Format is `projects/{project}/subscriptions/{sub}`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1141

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1142

The object takes the form of:

1143

1144

{ # Request for the ModifyAckDeadline method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1145

"ackDeadlineSeconds": 42, # Required. The new ack deadline with respect to the time this request was sent to

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1146

# the Pub/Sub system. For example, if the value is 10, the new

1147

# ack deadline will expire 10 seconds after the `ModifyAckDeadline` call

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1148

# was made. Specifying zero might immediately make the message available for

1149

# delivery to another subscriber client. This typically results in an

1150

# increase in the rate of message redeliveries (that is, duplicates).

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1151

# The minimum deadline you can specify is 0 seconds.

1152

# The maximum deadline you can specify is 600 seconds (10 minutes).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1153

"ackIds": [ # Required. List of acknowledgment IDs.

1154

"A String",

1155

],

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1156

}

1157

1158

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1159

Allowed values

1160

1 - v1 error format

1161

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1162

1163

Returns:

1164

An object of the form:

1165

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1166

{ # A generic empty message that you can re-use to avoid defining duplicated

1167

# empty messages in your APIs. A typical example is to use it as the request

1168

# or the response type of an API method. For instance:

1169

#

1170

# service Foo {

1171

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

1172

# }

1173

#

1174

# The JSON representation for `Empty` is empty JSON object `{}`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1179

<code class="details" id="modifyPushConfig">modifyPushConfig(subscription, body=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1180

<pre>Modifies the `PushConfig` for a specified subscription.

1181

1182

This may be used to change a push subscription to a pull one (signified by

1183

an empty `PushConfig`) or vice versa, or change the endpoint URL and other

1184

attributes of a push subscription. Messages will accumulate for delivery

1185

continuously through the call regardless of changes to the `PushConfig`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1186

1187

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1188

subscription: string, Required. The name of the subscription.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1189

Format is `projects/{project}/subscriptions/{sub}`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1190

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1191

The object takes the form of:

1192

1193

{ # Request for the ModifyPushConfig method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1194

"pushConfig": { # Configuration for a push delivery endpoint. # Required. The push configuration for future deliveries.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1195

#

1196

# An empty `pushConfig` indicates that the Pub/Sub system should

1197

# stop pushing messages from the given subscription and allow

1198

# messages to be pulled and acknowledged - effectively pausing

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1199

# the subscription if `Pull` or `StreamingPull` is not called.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1200

"attributes": { # Endpoint configuration attributes that can be used to control different

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1201

# aspects of the message delivery.

1202

#

1203

# The only currently supported attribute is `x-goog-version`, which you can

1204

# use to change the format of the pushed message. This attribute

1205

# indicates the version of the data expected by the endpoint. This

1206

# controls the shape of the pushed message (i.e., its fields and metadata).

1207

#

1208

# If not present during the `CreateSubscription` call, it will default to

1209

# the version of the Pub/Sub API used to make such call. If not present in a

1210

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

1211

# calls will always return a valid version, even if the subscription was

1212

# created without this attribute.

1213

#

1214

# The only supported values for the `x-goog-version` attribute are:

1215

#

1216

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

1217

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

1218

#

1219

# For example:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1220

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

1221

"a_key": "A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1222

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1223

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

1224

# For example, a Webhook endpoint might use `https://example.com/push`.

1225

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

1226

# `Authorization` header in the HTTP request for every pushed message.

1227

# [OpenID Connect

1228

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

1229

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

1230

# identifies the recipients that the JWT is intended for. The audience

1231

# value is a single case-sensitive string. Having multiple values (array)

1232

# for the audience field is not supported. More info about the OIDC JWT

1233

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

1234

# Note: if not specified, the Push endpoint URL will be used.

1235

"serviceAccountEmail": "A String", # [Service account

1236

# email](https://cloud.google.com/iam/docs/service-accounts)

1237

# to be used for generating the OIDC token. The caller (for

1238

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

1239

# have the iam.serviceAccounts.actAs permission for the service account.

1240

},

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1245

Allowed values

1246

1 - v1 error format

1247

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1248

1249

Returns:

1250

An object of the form:

1251

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1252

{ # A generic empty message that you can re-use to avoid defining duplicated

1253

# empty messages in your APIs. A typical example is to use it as the request

1254

# or the response type of an API method. For instance:

1255

#

1256

# service Foo {

1257

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

1258

# }

1259

#

1260

# The JSON representation for `Empty` is empty JSON object `{}`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1265

<code class="details" id="patch">patch(name, body=None, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1266

<pre>Updates an existing subscription. Note that certain properties of a

1267

subscription, such as its topic, are not modifiable.

1268

1269

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1270

name: string, Required. The name of the subscription. It must have the format

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1271

`"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1272

start with a letter, and contain only letters (`[A-Za-z]`), numbers

1273

(`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

1274

plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1275

in length, and it must not start with `"goog"`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1276

body: object, The request body.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1277

The object takes the form of:

1278

1279

{ # Request for the UpdateSubscription method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1280

"updateMask": "A String", # Required. Indicates which fields in the provided subscription to update.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1281

# Must be specified and non-empty.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1282

"subscription": { # A subscription resource. # Required. The updated subscription object.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1283

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1284

# used to configure it. An empty `pushConfig` signifies that the subscriber

1285

# will pull and ack messages using API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1286

"attributes": { # Endpoint configuration attributes that can be used to control different

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1287

# aspects of the message delivery.

1288

#

1289

# The only currently supported attribute is `x-goog-version`, which you can

1290

# use to change the format of the pushed message. This attribute

1291

# indicates the version of the data expected by the endpoint. This

1292

# controls the shape of the pushed message (i.e., its fields and metadata).

1293

#

1294

# If not present during the `CreateSubscription` call, it will default to

1295

# the version of the Pub/Sub API used to make such call. If not present in a

1296

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

1297

# calls will always return a valid version, even if the subscription was

1298

# created without this attribute.

1299

#

1300

# The only supported values for the `x-goog-version` attribute are:

1301

#

1302

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

1303

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

1304

#

1305

# For example:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1306

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

1307

"a_key": "A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1308

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1309

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

1310

# For example, a Webhook endpoint might use `https://example.com/push`.

1311

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

1312

# `Authorization` header in the HTTP request for every pushed message.

1313

# [OpenID Connect

1314

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

1315

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

1316

# identifies the recipients that the JWT is intended for. The audience

1317

# value is a single case-sensitive string. Having multiple values (array)

1318

# for the audience field is not supported. More info about the OIDC JWT

1319

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

1320

# Note: if not specified, the Push endpoint URL will be used.

1321

"serviceAccountEmail": "A String", # [Service account

1322

# email](https://cloud.google.com/iam/docs/service-accounts)

1323

# to be used for generating the OIDC token. The caller (for

1324

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

1325

# have the iam.serviceAccounts.actAs permission for the service account.

1326

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1327

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1328

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

1329

# then only `PubsubMessage`s whose `attributes` field matches the filter are

1330

# delivered on this subscription. If empty, then no messages are filtered

1331

# out.

1332

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

1333

# API might be changed in backward-incompatible ways and is not recommended

1334

# for production use. It is not subject to any SLA or deprecation policy.

1335

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

1336

# the subscriber to acknowledge receipt before resending the message. In the

1337

# interval after the message is delivered and before it is acknowledged, it

1338

# is considered to be <i>outstanding</i>. During that time period, the

1339

# message will not be redelivered (on a best-effort basis).

1340

#

1341

# For pull subscriptions, this value is used as the initial value for the ack

1342

# deadline. To override this value for a given message, call

1343

# `ModifyAckDeadline` with the corresponding `ack_id` if using

1344

# non-streaming pull or send the `ack_id` in a

1345

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

1346

# The minimum custom deadline you can specify is 10 seconds.

1347

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

1348

# If this parameter is 0, a default value of 10 seconds is used.

1349

#

1350

# For push delivery, this value is also used to set the request timeout for

1351

# the call to the push endpoint.

1352

#

1353

# If the subscriber never acknowledges the message, the Pub/Sub

1354

# system will eventually redeliver the message.

1355

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1356

# from the moment a message is published.

1357

# If `retain_acked_messages` is true, then this also configures the retention

1358

# of acknowledged messages, and thus configures how far back in time a `Seek`

1359

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

1360

# minutes.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1361

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

1362

# messages are not expunged from the subscription's backlog, even if they are

1363

# acknowledged, until they fall out of the `message_retention_duration`

1364

# window. This must be true if you would like to

1365

# <a

1366

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

1367

# Seek to a timestamp</a>.

1368

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

1369

# managing labels</a>.

1370

"a_key": "A String",

1371

},

1372

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

1373

# this subscription. If dead_letter_policy is not set, dead lettering

1374

# is disabled.

1375

#

1376

# The Cloud Pub/Sub service account associated with this subscriptions's

1377

# parent project (i.e.,

1378

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1379

# permission to Acknowledge() messages on this subscription.

1380

# dead lettered multiple times.

1381

#

1382

# If validation on any of the fields fails at subscription creation/updation,

1383

# the create/update subscription request will fail.

1384

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

1385

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

1386

# account associated with the enclosing subscription's parent project (i.e.,

1387

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1388

# permission to Publish() to this topic.

1389

#

1390

# The operation will fail if the topic does not exist.

1391

# Users should ensure that there is a subscription attached to this topic

1392

# since messages published to a topic with no subscriptions are lost.

1393

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

1394

# between 5 and 100.

1395

#

1396

# The number of delivery attempts is defined as 1 + (the sum of number of

1397

# NACKs and number of times the acknowledgement deadline has been exceeded

1398

# for the message).

1399

#

1400

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

1401

# client libraries may automatically extend ack_deadlines.

1402

#

1403

# This field will be honored on a best effort basis.

1404

#

1405

# If this parameter is 0, a default value of 5 is used.

1406

},

1407

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

1408

# A subscription is considered active as long as any connected subscriber is

1409

# successfully consuming messages from the subscription or is issuing

1410

# operations on the subscription. If `expiration_policy` is not set, a

1411

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

1412

# value for `expiration_policy.ttl` is 1 day.

1413

# automatic resource deletion).

1414

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

1415

# resource expires if it is not active for a period of `ttl`. The definition

1416

# of "activity" depends on the type of the associated resource. The minimum

1417

# and maximum allowed values for `ttl` depend on the type of the associated

1418

# resource, as well. If `ttl` is not set, the associated resource never

1419

# expires.

1420

},

1421

"name": "A String", # Required. The name of the subscription. It must have the format

1422

# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

1423

# start with a letter, and contain only letters (`[A-Za-z]`), numbers

1424

# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

1425

# plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

1426

# in length, and it must not start with `"goog"`.

1427

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

1428

# Format is `projects/{project}/topics/{topic}`.

1429

# The value of this field will be `_deleted-topic_` if the topic has been

# deleted.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1441

1442

{ # A subscription resource.

1443

"pushConfig": { # Configuration for a push delivery endpoint. # If push delivery is used with this subscription, this field is

1444

# used to configure it. An empty `pushConfig` signifies that the subscriber

1445

# will pull and ack messages using API methods.

1446

"attributes": { # Endpoint configuration attributes that can be used to control different

1447

# aspects of the message delivery.

1448

#

1449

# The only currently supported attribute is `x-goog-version`, which you can

1450

# use to change the format of the pushed message. This attribute

1451

# indicates the version of the data expected by the endpoint. This

1452

# controls the shape of the pushed message (i.e., its fields and metadata).

1453

#

1454

# If not present during the `CreateSubscription` call, it will default to

1455

# the version of the Pub/Sub API used to make such call. If not present in a

1456

# `ModifyPushConfig` call, its value will not be changed. `GetSubscription`

1457

# calls will always return a valid version, even if the subscription was

1458

# created without this attribute.

1459

#

1460

# The only supported values for the `x-goog-version` attribute are:

1461

#

1462

# * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.

1463

# * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.

1464

#

1465

# For example:

1466

# <pre><code>attributes { "x-goog-version": "v1" } </code></pre>

1467

"a_key": "A String",

1468

},

1469

"pushEndpoint": "A String", # A URL locating the endpoint to which messages should be pushed.

1470

# For example, a Webhook endpoint might use `https://example.com/push`.

1471

"oidcToken": { # Contains information needed for generating an # If specified, Pub/Sub will generate and attach an OIDC JWT token as an

1472

# `Authorization` header in the HTTP request for every pushed message.

1473

# [OpenID Connect

1474

# token](https://developers.google.com/identity/protocols/OpenIDConnect).

1475

"audience": "A String", # Audience to be used when generating OIDC token. The audience claim

1476

# identifies the recipients that the JWT is intended for. The audience

1477

# value is a single case-sensitive string. Having multiple values (array)

1478

# for the audience field is not supported. More info about the OIDC JWT

1479

# token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3

1480

# Note: if not specified, the Push endpoint URL will be used.

1481

"serviceAccountEmail": "A String", # [Service account

1482

# email](https://cloud.google.com/iam/docs/service-accounts)

1483

# to be used for generating the OIDC token. The caller (for

1484

# CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must

1485

# have the iam.serviceAccounts.actAs permission for the service account.

1486

},

1487

},

1488

"filter": "A String", # An expression written in the Cloud Pub/Sub filter language. If non-empty,

1489

# then only `PubsubMessage`s whose `attributes` field matches the filter are

1490

# delivered on this subscription. If empty, then no messages are filtered

1491

# out.

1492

# <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This

1493

# API might be changed in backward-incompatible ways and is not recommended

1494

# for production use. It is not subject to any SLA or deprecation policy.

1495

"ackDeadlineSeconds": 42, # The approximate amount of time (on a best-effort basis) Pub/Sub waits for

1496

# the subscriber to acknowledge receipt before resending the message. In the

1497

# interval after the message is delivered and before it is acknowledged, it

1498

# is considered to be <i>outstanding</i>. During that time period, the

1499

# message will not be redelivered (on a best-effort basis).

1500

#

1501

# For pull subscriptions, this value is used as the initial value for the ack

1502

# deadline. To override this value for a given message, call

1503

# `ModifyAckDeadline` with the corresponding `ack_id` if using

1504

# non-streaming pull or send the `ack_id` in a

1505

# `StreamingModifyAckDeadlineRequest` if using streaming pull.

1506

# The minimum custom deadline you can specify is 10 seconds.

1507

# The maximum custom deadline you can specify is 600 seconds (10 minutes).

1508

# If this parameter is 0, a default value of 10 seconds is used.

1509

#

1510

# For push delivery, this value is also used to set the request timeout for

1511

# the call to the push endpoint.

1512

#

1513

# If the subscriber never acknowledges the message, the Pub/Sub

1514

# system will eventually redeliver the message.

1515

"messageRetentionDuration": "A String", # How long to retain unacknowledged messages in the subscription's backlog,

1516

# from the moment a message is published.

1517

# If `retain_acked_messages` is true, then this also configures the retention

1518

# of acknowledged messages, and thus configures how far back in time a `Seek`

1519

# can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10

1520

# minutes.

1521

"retainAckedMessages": True or False, # Indicates whether to retain acknowledged messages. If true, then

1522

# messages are not expunged from the subscription's backlog, even if they are

1523

# acknowledged, until they fall out of the `message_retention_duration`

1524

# window. This must be true if you would like to

1525

# <a

1526

# href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">

1527

# Seek to a timestamp</a>.

1528

"labels": { # See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and

1529

# managing labels</a>.

1530

"a_key": "A String",

1531

},

1532

"deadLetterPolicy": { # Dead lettering is done on a best effort basis. The same message might be # A policy that specifies the conditions for dead lettering messages in

1533

# this subscription. If dead_letter_policy is not set, dead lettering

1534

# is disabled.

1535

#

1536

# The Cloud Pub/Sub service account associated with this subscriptions's

1537

# parent project (i.e.,

1538

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1539

# permission to Acknowledge() messages on this subscription.

1540

# dead lettered multiple times.

1541

#

1542

# If validation on any of the fields fails at subscription creation/updation,

1543

# the create/update subscription request will fail.

1544

"deadLetterTopic": "A String", # The name of the topic to which dead letter messages should be published.

1545

# Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service

1546

# account associated with the enclosing subscription's parent project (i.e.,

1547

# service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have

1548

# permission to Publish() to this topic.

1549

#

1550

# The operation will fail if the topic does not exist.

1551

# Users should ensure that there is a subscription attached to this topic

1552

# since messages published to a topic with no subscriptions are lost.

1553

"maxDeliveryAttempts": 42, # The maximum number of delivery attempts for any message. The value must be

1554

# between 5 and 100.

1555

#

1556

# The number of delivery attempts is defined as 1 + (the sum of number of

1557

# NACKs and number of times the acknowledgement deadline has been exceeded

1558

# for the message).

1559

#

1560

# A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that

1561

# client libraries may automatically extend ack_deadlines.

1562

#

1563

# This field will be honored on a best effort basis.

1564

#

1565

# If this parameter is 0, a default value of 5 is used.

1566

},

1567

"expirationPolicy": { # A policy that specifies the conditions for resource expiration (i.e., # A policy that specifies the conditions for this subscription's expiration.

1568

# A subscription is considered active as long as any connected subscriber is

1569

# successfully consuming messages from the subscription or is issuing

1570

# operations on the subscription. If `expiration_policy` is not set, a

1571

# *default policy* with `ttl` of 31 days will be used. The minimum allowed

1572

# value for `expiration_policy.ttl` is 1 day.

1573

# automatic resource deletion).

1574

"ttl": "A String", # Specifies the "time-to-live" duration for an associated resource. The

1575

# resource expires if it is not active for a period of `ttl`. The definition

1576

# of "activity" depends on the type of the associated resource. The minimum

1577

# and maximum allowed values for `ttl` depend on the type of the associated

1578

# resource, as well. If `ttl` is not set, the associated resource never

1579

# expires.

1580

},

1581

"name": "A String", # Required. The name of the subscription. It must have the format

1582

# `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must

1583

# start with a letter, and contain only letters (`[A-Za-z]`), numbers

1584

# (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),

1585

# plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters

1586

# in length, and it must not start with `"goog"`.

1587

"topic": "A String", # Required. The name of the topic from which this subscription is receiving messages.

1588

# Format is `projects/{project}/topics/{topic}`.

1589

# The value of this field will be `_deleted-topic_` if the topic has been

1590

# deleted.

1591

}</pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1595

<code class="details" id="pull">pull(subscription, body=None, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1596

<pre>Pulls messages from the server. The server may return `UNAVAILABLE` if

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1597

there are too many concurrent pull requests pending for the given

1598

subscription.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1599

1600

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1601

subscription: string, Required. The subscription from which messages should be pulled.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1602

Format is `projects/{project}/subscriptions/{sub}`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1603

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1604

The object takes the form of:

1605

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

1606

{ # Request for the `Pull` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1607

"returnImmediately": True or False, # Optional. If this field set to true, the system will respond immediately even if

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1608

# it there are no messages available to return in the `Pull` response.

1609

# Otherwise, the system may wait (for a bounded amount of time) until at

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1610

# least one message is available, rather than returning no messages. Warning:

1611

# setting this field to `true` is discouraged because it adversely impacts

1612

# the performance of `Pull` operations. We recommend that users do not set

1613

# this field.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1614

"maxMessages": 42, # Required. The maximum number of messages to return for this request. Must be a

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1615

# positive integer. The Pub/Sub system may return fewer than the number

1616

# specified.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1617

}

1618

1619

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1620

Allowed values

1621

1 - v1 error format

1622

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1623

1624

Returns:

1625

An object of the form:

1626

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

1627

{ # Response for the `Pull` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1628

"receivedMessages": [ # Received Pub/Sub messages. The list will be empty if there are no more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1629

# messages available in the backlog. For JSON, the response can be entirely

1630

# empty. The Pub/Sub system may return fewer than the `maxMessages` requested

1631

# even if there are more messages available in the backlog.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1632

{ # A message and its corresponding acknowledgment ID.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1633

"deliveryAttempt": 42, # The approximate number of times that Cloud Pub/Sub has attempted to deliver

1634

# the associated message to a subscriber.

1635

#

1636

# More precisely, this is 1 + (number of NACKs) +

1637

# (number of ack_deadline exceeds) for this message.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1638

#

1639

# A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline

1640

# exceeds event is whenever a message is not acknowledged within

1641

# ack_deadline. Note that ack_deadline is initially

1642

# Subscription.ackDeadlineSeconds, but may get extended automatically by

1643

# the client library.

1644

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1645

# Upon the first delivery of a given message, `delivery_attempt` will have a

1646

# value of 1. The value is calculated at best effort and is approximate.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1647

#

1648

# If a DeadLetterPolicy is not set on the subscription, this will be 0.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1649

"message": { # A message that is published by publishers and consumed by subscribers. The # The message.

1650

# message must contain either a non-empty data field or at least one attribute.

1651

# Note that client libraries represent this object differently

1652

# depending on the language. See the corresponding

1653

# <a href="https://cloud.google.com/pubsub/docs/reference/libraries">client

1654

# library documentation</a> for more information. See

1655

# <a href="https://cloud.google.com/pubsub/quotas">Quotas and limits</a>

1656

# for more information about message limits.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1657

"publishTime": "A String", # The time at which the message was published, populated by the server when

1658

# it receives the `Publish` call. It must not be populated by the

1659

# publisher in a `Publish` call.

1660

"data": "A String", # The message data field. If this field is empty, the message must contain

1661

# at least one attribute.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1662

"messageId": "A String", # ID of this message, assigned by the server when the message is published.

1663

# Guaranteed to be unique within the topic. This value may be read by a

1664

# subscriber that receives a `PubsubMessage` via a `Pull` call or a push

1665

# delivery. It must not be populated by the publisher in a `Publish` call.

1666

"attributes": { # Attributes for this message. If this field is empty, the message must

1667

# contain non-empty data.

1668

"a_key": "A String",

1669

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1670

},

1671

"ackId": "A String", # This ID can be used to acknowledge the received message.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

},

],

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1678

<code class="details" id="seek">seek(subscription, body=None, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1679

<pre>Seeks an existing subscription to a point in time or to a given snapshot,

1680

whichever is provided in the request. Snapshots are used in

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1681

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1682

operations, which allow

1683

you to manage message acknowledgments in bulk. That is, you can set the

1684

acknowledgment state of messages in an existing subscription to the state

1685

captured by a snapshot. Note that both the subscription and the snapshot

1686

must be on the same topic.

1687

1688

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1689

subscription: string, Required. The subscription to affect. (required)

1690

body: object, The request body.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1691

The object takes the form of:

1692

1693

{ # Request for the `Seek` method.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1694

"snapshot": "A String", # The snapshot to seek to. The snapshot's topic must be the same as that of

1695

# the provided subscription.

1696

# Format is `projects/{project}/snapshots/{snap}`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1697

"time": "A String", # The time to seek to.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1698

# Messages retained in the subscription that were published before this

1699

# time are marked as acknowledged, and messages retained in the

1700

# subscription that were published after this time are marked as

1701

# unacknowledged. Note that this operation affects only those messages

1702

# retained in the subscription (configured by the combination of

1703

# `message_retention_duration` and `retain_acked_messages`). For example,

1704

# if `time` corresponds to a point before the message retention

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1705

# window (or to a point before the system's notion of the subscription

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1706

# creation time), only retained messages will be marked as unacknowledged,

1707

# and already-expunged messages will not be restored.

1708

}

1709

1710

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1717

1718

{ # Response for the `Seek` method (this response is empty).

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1723

<code class="details" id="setIamPolicy">setIamPolicy(resource, body=None, x__xgafv=None)</code>

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1724

<pre>Sets the access control policy on the specified resource. Replaces any

1725

existing policy.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1726

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1727

Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED` errors.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1728

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1729

Args:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1730

resource: string, REQUIRED: The resource for which the policy is being specified.

Sai Cheemalapati

e833b79

2017-03-24 15:06:46 -0700

[diff] [blame]

1731

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1732

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1733

The object takes the form of:

1734

1735

{ # Request message for `SetIamPolicy` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1736

"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 Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1737

# the policy is limited to a few 10s of KB. An empty policy is a

1738

# valid policy but certain Cloud Platform services (such as Projects)

1739

# might reject them.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1740

# controls for Google Cloud resources.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1741

#

1742

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1743

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

1744

# `members` to a single `role`. Members can be user accounts, service accounts,

1745

# Google groups, and domains (such as G Suite). A `role` is a named list of

1746

# permissions; each `role` can be an IAM predefined role or a user-created

1747

# custom role.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1748

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1749

# For some types of Google Cloud resources, a `binding` can also specify a

1750

# `condition`, which is a logical expression that allows access to a resource

1751

# only if the expression evaluates to `true`. A condition can add constraints

1752

# based on attributes of the request, the resource, or both. To learn which

1753

# resources support conditions in their IAM policies, see the

1754

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1755

#

1756

# **JSON example:**

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1757

#

1758

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1759

# "bindings": [

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1760

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1761

# "role": "roles/resourcemanager.organizationAdmin",

1762

# "members": [

1763

# "user:mike@example.com",

1764

# "group:admins@example.com",

1765

# "domain:google.com",

1766

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1767

# ]

1768

# },

1769

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1770

# "role": "roles/resourcemanager.organizationViewer",

1771

# "members": [

1772

# "user:eve@example.com"

1773

# ],

1774

# "condition": {

1775

# "title": "expirable access",

1776

# "description": "Does not grant access after Sep 2020",

1777

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1778

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1779

# }

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1780

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1781

# "etag": "BwWWja0YfJA=",

1782

# "version": 3

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1783

# }

1784

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1785

# **YAML example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

1790

# - group:admins@example.com

1791

# - domain:google.com

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1792

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

1793

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1794

# - members:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1795

# - user:eve@example.com

1796

# role: roles/resourcemanager.organizationViewer

1797

# condition:

1798

# title: expirable access

1799

# description: Does not grant access after Sep 2020

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1800

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1801

# - etag: BwWWja0YfJA=

1802

# - version: 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1803

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1804

# For a description of IAM and its features, see the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1805

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1806

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1807

# `condition` that determines how and when the `bindings` are applied. Each

1808

# of the `bindings` must contain at least one member.

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

1809

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1810

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

1811

#

1812

# If the condition evaluates to `true`, then this binding applies to the

1813

# current request.

1814

#

1815

# If the condition evaluates to `false`, then this binding does not apply to

1816

# the current request. However, a different role binding might grant the same

1817

# role to one or more of the members in this binding.

1818

#

1819

# To learn which resources support conditions in their IAM policies, see the

1820

# [IAM

1821

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

1822

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

1823

# are documented at https://github.com/google/cel-spec.

1824

#

1825

# Example (Comparison):

1826

#

1827

# title: "Summary size limit"

1828

# description: "Determines if a summary is less than 100 chars"

1829

# expression: "document.summary.size() < 100"

1830

#

1831

# Example (Equality):

1832

#

1833

# title: "Requestor is owner"

1834

# description: "Determines if requestor is the document owner"

1835

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

1840

# description: "Determine whether the document should be publicly visible"

1841

# expression: "document.type != 'private' && document.type != 'internal'"

1842

#

1843

# Example (Data Manipulation):

1844

#

1845

# title: "Notification string"

1846

# description: "Create a notification string with a timestamp."

1847

# expression: "'New message received at ' + string(document.create_time)"

1848

#

1849

# The exact variables and functions that may be referenced within an expression

1850

# are determined by the service that evaluates it. See the service

1851

# documentation for additional information.

1852

"location": "A String", # Optional. String indicating the location of the expression for error

1853

# reporting, e.g. a file name and a position in the file.

1854

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

1855

# its purpose. This can be used e.g. in UIs which allow to enter the

1856

# expression.

1857

"description": "A String", # Optional. Description of the expression. This is a longer text which

1858

# describes the expression, e.g. when hovered over it in a UI.

1859

"expression": "A String", # Textual representation of an expression in Common Expression Language

1860

# syntax.

1861

},

1862

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1863

# `members` can have the following values:

1864

#

1865

# * `allUsers`: A special identifier that represents anyone who is

1866

# on the internet; with or without a Google account.

1867

#

1868

# * `allAuthenticatedUsers`: A special identifier that represents anyone

1869

# who is authenticated with a Google account or a service account.

1870

#

1871

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1872

# account. For example, `alice@example.com` .

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1873

#

1874

#

1875

# * `serviceAccount:{emailid}`: An email address that represents a service

1876

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

1877

#

1878

# * `group:{emailid}`: An email address that represents a Google group.

1879

# For example, `admins@example.com`.

1880

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1881

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

1882

# identifier) representing a user that has been recently deleted. For

1883

# example, `alice@example.com?uid=123456789012345678901`. If the user is

1884

# recovered, this value reverts to `user:{emailid}` and the recovered user

1885

# retains the role in the binding.

1886

#

1887

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

1888

# unique identifier) representing a service account that has been recently

1889

# deleted. For example,

1890

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

1891

# If the service account is undeleted, this value reverts to

1892

# `serviceAccount:{emailid}` and the undeleted service account retains the

1893

# role in the binding.

1894

#

1895

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

1896

# identifier) representing a Google group that has been recently

1897

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

1898

# the group is recovered, this value reverts to `group:{emailid}` and the

1899

# recovered group retains the role in the binding.

1900

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1901

#

1902

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1903

# users of that domain. For example, `google.com` or `example.com`.

1904

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1905

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1906

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1907

"role": "A String", # Role that is assigned to `members`.

1908

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1909

},

1910

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1911

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

1912

# prevent simultaneous updates of a policy from overwriting each other.

1913

# It is strongly suggested that systems make use of the `etag` in the

1914

# read-modify-write cycle to perform policy updates in order to avoid race

1915

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

1916

# systems are expected to put that etag in the request to `setIamPolicy` to

1917

# ensure that their change will be applied to the same version of the policy.

1918

#

1919

# **Important:** If you use IAM Conditions, you must include the `etag` field

1920

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1921

# you to overwrite a version `3` policy with a version `1` policy, and all of

1922

# the conditions in the version `3` policy are lost.

1923

"version": 42, # Specifies the format of the policy.

1924

#

1925

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

1926

# are rejected.

1927

#

1928

# Any operation that affects conditional role bindings must specify version

1929

# `3`. This requirement applies to the following operations:

1930

#

1931

# * Getting a policy that includes a conditional role binding

1932

# * Adding a conditional role binding to a policy

1933

# * Changing a conditional role binding in a policy

1934

# * Removing any role binding, with or without a condition, from a policy

1935

# that includes conditions

1936

#

1937

# **Important:** If you use IAM Conditions, you must include the `etag` field

1938

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

1939

# you to overwrite a version `3` policy with a version `1` policy, and all of

1940

# the conditions in the version `3` policy are lost.

1941

#

1942

# If a policy does not include any conditions, operations on that policy may

1943

# specify any valid version or leave the field unset.

1944

#

1945

# To learn which resources support conditions in their IAM policies, see the

1946

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1951

Allowed values

1952

1 - v1 error format

1953

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1954

1955

Returns:

1956

An object of the form:

1957

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1958

{ # An Identity and Access Management (IAM) policy, which specifies access

1959

# controls for Google Cloud resources.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1960

#

1961

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1962

# A `Policy` is a collection of `bindings`. A `binding` binds one or more

1963

# `members` to a single `role`. Members can be user accounts, service accounts,

1964

# Google groups, and domains (such as G Suite). A `role` is a named list of

1965

# permissions; each `role` can be an IAM predefined role or a user-created

1966

# custom role.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1967

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1968

# For some types of Google Cloud resources, a `binding` can also specify a

1969

# `condition`, which is a logical expression that allows access to a resource

1970

# only if the expression evaluates to `true`. A condition can add constraints

1971

# based on attributes of the request, the resource, or both. To learn which

1972

# resources support conditions in their IAM policies, see the

1973

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1974

#

1975

# **JSON example:**

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1976

#

1977

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1978

# "bindings": [

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1979

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1980

# "role": "roles/resourcemanager.organizationAdmin",

1981

# "members": [

1982

# "user:mike@example.com",

1983

# "group:admins@example.com",

1984

# "domain:google.com",

1985

# "serviceAccount:my-project-id@appspot.gserviceaccount.com"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1986

# ]

1987

# },

1988

# {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1989

# "role": "roles/resourcemanager.organizationViewer",

1990

# "members": [

1991

# "user:eve@example.com"

1992

# ],

1993

# "condition": {

1994

# "title": "expirable access",

1995

# "description": "Does not grant access after Sep 2020",

1996

# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1997

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1998

# }

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1999

# ],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2000

# "etag": "BwWWja0YfJA=",

2001

# "version": 3

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2002

# }

2003

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2004

# **YAML example:**

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

#

# bindings:

# - members:

# - user:mike@example.com

2009

# - group:admins@example.com

2010

# - domain:google.com

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2011

# - serviceAccount:my-project-id@appspot.gserviceaccount.com

2012

# role: roles/resourcemanager.organizationAdmin

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2013

# - members:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2014

# - user:eve@example.com

2015

# role: roles/resourcemanager.organizationViewer

2016

# condition:

2017

# title: expirable access

2018

# description: Does not grant access after Sep 2020

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2019

# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2020

# - etag: BwWWja0YfJA=

2021

# - version: 3

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2022

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2023

# For a description of IAM and its features, see the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2024

# [IAM documentation](https://cloud.google.com/iam/docs/).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2025

"bindings": [ # Associates a list of `members` to a `role`. Optionally, may specify a

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2026

# `condition` that determines how and when the `bindings` are applied. Each

2027

# of the `bindings` must contain at least one member.

Jon Wayne Parrott

2016-02-19 16:02:29 -0800

[diff] [blame]

2028

{ # Associates `members` with a `role`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2029

"condition": { # Represents a textual expression in the Common Expression Language (CEL) # The condition that is associated with this binding.

2030

#

2031

# If the condition evaluates to `true`, then this binding applies to the

2032

# current request.

2033

#

2034

# If the condition evaluates to `false`, then this binding does not apply to

2035

# the current request. However, a different role binding might grant the same

2036

# role to one or more of the members in this binding.

2037

#

2038

# To learn which resources support conditions in their IAM policies, see the

2039

# [IAM

2040

# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

2041

# syntax. CEL is a C-like expression language. The syntax and semantics of CEL

2042

# are documented at https://github.com/google/cel-spec.

2043

#

2044

# Example (Comparison):

2045

#

2046

# title: "Summary size limit"

2047

# description: "Determines if a summary is less than 100 chars"

2048

# expression: "document.summary.size() < 100"

2049

#

2050

# Example (Equality):

2051

#

2052

# title: "Requestor is owner"

2053

# description: "Determines if requestor is the document owner"

2054

# expression: "document.owner == request.auth.claims.email"

#

# Example (Logic):

#

# title: "Public documents"

2059

# description: "Determine whether the document should be publicly visible"

2060

# expression: "document.type != 'private' && document.type != 'internal'"

2061

#

2062

# Example (Data Manipulation):

2063

#

2064

# title: "Notification string"

2065

# description: "Create a notification string with a timestamp."

2066

# expression: "'New message received at ' + string(document.create_time)"

2067

#

2068

# The exact variables and functions that may be referenced within an expression

2069

# are determined by the service that evaluates it. See the service

2070

# documentation for additional information.

2071

"location": "A String", # Optional. String indicating the location of the expression for error

2072

# reporting, e.g. a file name and a position in the file.

2073

"title": "A String", # Optional. Title for the expression, i.e. a short string describing

2074

# its purpose. This can be used e.g. in UIs which allow to enter the

2075

# expression.

2076

"description": "A String", # Optional. Description of the expression. This is a longer text which

2077

# describes the expression, e.g. when hovered over it in a UI.

2078

"expression": "A String", # Textual representation of an expression in Common Expression Language

2079

# syntax.

2080

},

2081

"members": [ # Specifies the identities requesting access for a Cloud Platform resource.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2082

# `members` can have the following values:

2083

#

2084

# * `allUsers`: A special identifier that represents anyone who is

2085

# on the internet; with or without a Google account.

2086

#

2087

# * `allAuthenticatedUsers`: A special identifier that represents anyone

2088

# who is authenticated with a Google account or a service account.

2089

#

2090

# * `user:{emailid}`: An email address that represents a specific Google

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2091

# account. For example, `alice@example.com` .

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2092

#

2093

#

2094

# * `serviceAccount:{emailid}`: An email address that represents a service

2095

# account. For example, `my-other-app@appspot.gserviceaccount.com`.

2096

#

2097

# * `group:{emailid}`: An email address that represents a Google group.

2098

# For example, `admins@example.com`.

2099

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2100

# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique

2101

# identifier) representing a user that has been recently deleted. For

2102

# example, `alice@example.com?uid=123456789012345678901`. If the user is

2103

# recovered, this value reverts to `user:{emailid}` and the recovered user

2104

# retains the role in the binding.

2105

#

2106

# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus

2107

# unique identifier) representing a service account that has been recently

2108

# deleted. For example,

2109

# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.

2110

# If the service account is undeleted, this value reverts to

2111

# `serviceAccount:{emailid}` and the undeleted service account retains the

2112

# role in the binding.

2113

#

2114

# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique

2115

# identifier) representing a Google group that has been recently

2116

# deleted. For example, `admins@example.com?uid=123456789012345678901`. If

2117

# the group is recovered, this value reverts to `group:{emailid}` and the

2118

# recovered group retains the role in the binding.

2119

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2120

#

2121

# * `domain:{domain}`: The G Suite domain (primary) that represents all the

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2122

# users of that domain. For example, `google.com` or `example.com`.

2123

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2124

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2125

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2126

"role": "A String", # Role that is assigned to `members`.

2127

# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2128

},

2129

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2130

"etag": "A String", # `etag` is used for optimistic concurrency control as a way to help

2131

# prevent simultaneous updates of a policy from overwriting each other.

2132

# It is strongly suggested that systems make use of the `etag` in the

2133

# read-modify-write cycle to perform policy updates in order to avoid race

2134

# conditions: An `etag` is returned in the response to `getIamPolicy`, and

2135

# systems are expected to put that etag in the request to `setIamPolicy` to

2136

# ensure that their change will be applied to the same version of the policy.

2137

#

2138

# **Important:** If you use IAM Conditions, you must include the `etag` field

2139

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

2140

# you to overwrite a version `3` policy with a version `1` policy, and all of

2141

# the conditions in the version `3` policy are lost.

2142

"version": 42, # Specifies the format of the policy.

2143

#

2144

# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value

2145

# are rejected.

2146

#

2147

# Any operation that affects conditional role bindings must specify version

2148

# `3`. This requirement applies to the following operations:

2149

#

2150

# * Getting a policy that includes a conditional role binding

2151

# * Adding a conditional role binding to a policy

2152

# * Changing a conditional role binding in a policy

2153

# * Removing any role binding, with or without a condition, from a policy

2154

# that includes conditions

2155

#

2156

# **Important:** If you use IAM Conditions, you must include the `etag` field

2157

# whenever you call `setIamPolicy`. If you omit this field, then IAM allows

2158

# you to overwrite a version `3` policy with a version `1` policy, and all of

2159

# the conditions in the version `3` policy are lost.

2160

#

2161

# If a policy does not include any conditions, operations on that policy may

2162

# specify any valid version or leave the field unset.

2163

#

2164

# To learn which resources support conditions in their IAM policies, see the

2165

# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2170

<code class="details" id="testIamPermissions">testIamPermissions(resource, body=None, x__xgafv=None)</code>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2171

<pre>Returns permissions that a caller has on the specified resource.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2172

If the resource does not exist, this will return an empty set of

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2173

permissions, not a `NOT_FOUND` error.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2174

Sai Cheemalapati

c30d2b5

2017-03-13 12:12:03 -0400

[diff] [blame]

2175

Note: This operation is designed to be used for building permission-aware

2176

UIs and command-line tools, not for authorization checking. This operation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2177

may "fail open" without warning.

Sai Cheemalapati

c30d2b5

2017-03-13 12:12:03 -0400

[diff] [blame]

2178

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2179

Args:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2180

resource: string, REQUIRED: The resource for which the policy detail is being requested.

Sai Cheemalapati

e833b79

2017-03-24 15:06:46 -0700

[diff] [blame]

2181

See the operation documentation for the appropriate value for this field. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2182

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2183

The object takes the form of:

2184

2185

{ # Request message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2186

"permissions": [ # The set of permissions to check for the `resource`. Permissions with

2187

# wildcards (such as '*' or 'storage.*') are not allowed. For more

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2188

# information see

2189

# [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2190

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

],

}

x__xgafv: string, V1 error format.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2195

Allowed values

2196

1 - v1 error format

2197

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

2198

2199

Returns:

2200

An object of the form:

2201

2202

{ # Response message for `TestIamPermissions` method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2203

"permissions": [ # A subset of `TestPermissionsRequest.permissions` that the caller is

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2204

# allowed.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2205

"A String",

Takashi Matsuo