8000 docs(iam): mark required params as required in docstring (via synth) … · googleapis/google-cloud-python@a4fa353 · GitHub
[go: up one dir, main page]
Skip to content

Commit a4fa353

Browse files
yoshi-automationbusunkim96
yoshi-automation
authored and
busunkim96
committed
docs(iam): mark required params as required in docstring (via synth) (#10006)
1 parent 0ef6eb4 commit a4fa353

File tree

6 files changed

+3616
-108
lines changed

6 files changed

+3616
-108
lines changed

‎packages/google-cloud-iam/google/cloud/iam_credentials_v1/gapic/iam_credentials_client.py‎

Lines changed: 36 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -234,10 +234,12 @@ def generate_access_token(
234234
>>> response = client.generate_access_token(name, scope)
235235
236236
Args:
237-
name (str): The resource name of the service account for which the credentials are
238-
requested, in the following format:
239-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
240-
scope (list[str]): Code to identify the scopes to be included in the OAuth 2.0 access token.
237+
name (str): Required. The resource name of the service account for which the
238+
credentials are requested, in the following format:
239+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
240+
wildcard character is required; replacing it with a project ID is
241+
invalid.
242+
scope (list[str]): Required. Code to identify the scopes to be included in the OAuth 2.0 access token.
241243
See https://developers.google.com/identity/protocols/googlescopes for more
242244
information.
243245
At least one value required.
@@ -249,7 +251,9 @@ def generate_access_token(
249251
that is specified in the ``name`` field of the request.
250252
251253
The delegates must have the following format:
252-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
254+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
255+
wildcard character is required; replacing it with a project ID is
256+
invalid.
253257
lifetime (Union[dict, ~google.cloud.iam_credentials_v1.types.Duration]): The desired lifetime duration of the access token in seconds.
254258
Must be set to a value less than or equal to 3600 (1 hour). If a value is
255259
not specified, the token's lifetime will be set to a default value of one
@@ -333,10 +337,12 @@ def generate_id_token(
333337
>>> response = client.generate_id_token(name, audience)
334338
335339
Args:
336-
name (str): The resource name of the service account for which the credentials are
337-
requested, in the following format:
338-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
339-
audience (str): The audience for the token, such as the API or account that this token
340+
name (str): Required. The resource name of the service account for which the
341+
credentials are requested, in the following format:
342+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
343+
wildcard character is required; replacing it with a project ID is
344+
invalid.
345+
audience (str): Required. The audience for the token, such as the API or account that this token
340346
grants access to.
341347
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
342348
account must be granted the ``roles/iam.serviceAccountTokenCreator``
@@ -346,7 +352,9 @@ def generate_id_token(
346352
that is specified in the ``name`` field of the request.
347353
348354
The delegates must have the following format:
349-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
355+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
356+
wildcard character is required; replacing it with a project ID is
357+
invalid.
350358
include_email (bool): Include the service account email in the token. If set to ``true``, the
351359
token will contain ``email`` and ``email_verified`` claims.
352360
retry (Optional[google.api_core.retry.Retry]): A retry object used
@@ -427,10 +435,12 @@ def sign_blob(
427435
>>> response = client.sign_blob(name, payload)
428436
429437
Args:
430-
name (str): The resource name of the service account for which the credentials are
431-
requested, in the following format:
432-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
433-
payload (bytes): The bytes to sign.
438+
name (str): Required. The resource name of the service account for which the
439+
credentials are requested, in the following format:
440+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
441+
wildcard character is required; replacing it with a project ID is
442+
invalid.
443+
payload (bytes): Required. The bytes to sign.
434444
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
435445
account must be granted the ``roles/iam.serviceAccountTokenCreator``
436446
role on its next service account in the chain. The last service account
@@ -439,7 +449,9 @@ def sign_blob(
439449
that is specified in the ``name`` field of the request.
440450
441451
The delegates must have the following format:
442-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
452+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
453+
wildcard character is required; replacing it with a project ID is
454+
invalid.
443455
retry (Optional[google.api_core.retry.Retry]): A retry object used
444456
to retry requests. If ``None`` is specified, requests will
445457
be retried using a default configuration.
@@ -515,10 +527,12 @@ def sign_jwt(
515527
>>> response = client.sign_jwt(name, payload)
516528
517529
Args:
518-
name (str): The resource name of the service account for which the credentials are
519-
requested, in the following format:
520-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
521-
payload (str): The JWT payload to sign: a JSON object that contains a JWT Claims Set.
530+
name (str): Required. The resource name of the service account for which the
531+
credentials are requested, in the following format:
532+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
533+
wildcard character is required; replacing it with a project ID is
534+
invalid.
535+
payload (str): Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
522536
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
523537
account must be granted the ``roles/iam.serviceAccountTokenCreator``
524538
role on its next service account in the chain. The last service account
@@ -527,7 +541,9 @@ def sign_jwt(
527541
that is specified in the ``name`` field of the request.
528542
529543
The delegates must have the following format:
530-
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
544+
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
545+
wildcard character is required; replacing it with a project ID is
546+
invalid.
531547
retry (Optional[google.api_core.retry.Retry]): A retry object used
532548
to retry requests. If ``None`` is specified, requests will
533549
be retried using a default configuration.

‎packages/google-cloud-iam/google/cloud/iam_credentials_v1/proto/common.proto‎

Lines changed: 60 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2018 Google LLC
1+
// Copyright 2019 Google LLC.
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -11,11 +11,14 @@
1111
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
// See the License for the specific language governing permissions and
1313
// limitations under the License.
14+
//
1415

1516
syntax = "proto3";
1617

1718
package google.iam.credentials.v1;
1819

20+
import "google/api/field_behavior.proto";
21+
import "google/api/resource.proto";
1922
import "google/protobuf/duration.proto";
2023
import "google/protobuf/timestamp.proto";
2124

@@ -24,12 +27,22 @@ option go_package = "google.golang.org/genproto/googleapis/iam/credentials/v1;cr
2427
option java_multiple_files = true;
2528
option java_outer_classname = "IAMCredentialsCommonProto";
2629
option java_package = "com.google.cloud.iam.credentials.v1";
30+
option (google.api.resource_definition) = {
31+
type: "iam.googleapis.com/ServiceAccount"
32+
pattern: "projects/{project}/serviceAccounts/{service_account}"
33+
};
2734

2835
message GenerateAccessTokenRequest {
29-
// The resource name of the service account for which the credentials
36+
// Required. The resource name of the service account for which the credentials
3037
// are requested, in the following format:
31-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
32-
string name = 1;
38+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
39+
// character is required; replacing it with a project ID is invalid.
40+
string name = 1 [
41+
(google.api.field_behavior) = REQUIRED,
42+
(google.api.resource_reference) = {
43+
type: "iam.googleapis.com/ServiceAccount"
44+
}
45+
];
3346

3447
// The sequence of service accounts in a delegation chain. Each service
3548
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
@@ -39,14 +52,15 @@ message GenerateAccessTokenRequest {
3952
// request.
4053
//
4154
// The delegates must have the following format:
42-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
55+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
56+
// character is required; replacing it with a project ID is invalid.
4357
repeated string delegates = 2;
4458

45-
// Code to identify the scopes to be included in the OAuth 2.0 access token.
59+
// Required. Code to identify the scopes to be included in the OAuth 2.0 access token.
4660
// See https://developers.google.com/identity/protocols/googlescopes for more
4761
// information.
4862
// At least one value required.
49-
repeated string scope = 4;
63+
repeated string scope = 4 [(google.api.field_behavior) = REQUIRED];
5064

5165
// The desired lifetime duration of the access token in seconds.
5266
// Must be set to a value less than or equal to 3600 (1 hour). If a value is
@@ -65,10 +79,16 @@ message GenerateAccessTokenResponse {
6579
}
6680

6781
message SignBlobRequest {
68-
// The resource name of the service account for which the credentials
82+
// Required. The resource name of the service account for which the credentials
6983
// are requested, in the following format:
70-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
71-
string name = 1;
84+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
85+
// character is required; replacing it with a project ID is invalid.
86+
string name = 1 [
87+
(google.api.field_behavior) = REQUIRED,
88+
(google.api.resource_reference) = {
89+
type: "iam.googleapis.com/ServiceAccount"
90+
}
91+
];
7292

7393
// The sequence of service accounts in a delegation chain. Each service
7494
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
@@ -78,11 +98,12 @@ message SignBlobRequest {
7898
// request.
7999
//
80100
// The delegates must have the following format:
81-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
101+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
102+
// character is required; replacing it with a project ID is invalid.
82103
repeated string delegates = 3;
83104

84-
// The bytes to sign.
85-
bytes payload = 5;
105+
// Required. The bytes to sign.
106+
bytes payload = 5 [(google.api.field_behavior) = REQUIRED];
86107
}
87108

88109
message SignBlobResponse {
@@ -94,10 +115,16 @@ message SignBlobResponse {
94115
}
95116

96117
message SignJwtRequest {
97-
// The resource name of the service account for which the credentials
118+
// Required. The resource name of the service account for which the credentials
98119
// are requested, in the following format:
99-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
100-
string name = 1;
120+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
121+
// character is required; replacing it with a project ID is invalid.
122+
string name = 1 [
123+
(google.api.field_behavior) = REQUIRED,
124+
(google.api.resource_reference) = {
125+
type: "iam.googleapis.com/ServiceAccount"
126+
}
127+
];
101128

102129
// The sequence of service accounts in a delegation chain. Each service
103130
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
@@ -107,11 +134,12 @@ message SignJwtRequest {
107134
// request.
108135
//
109136
// The delegates must have the following format:
110-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
137+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
138+
// character is required; replacing it with a project ID is invalid.
111139
repeated string delegates = 3;
112140

113-
// The JWT payload to sign: a JSON object that contains a JWT Claims Set.
114-
string payload = 5;
141+
// Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
142+
string payload = 5 [(google.api.field_behavior) = REQUIRED];
115143
}
116144

117145
message SignJwtResponse {
@@ -123,10 +151,16 @@ message SignJwtResponse {
123151
}
124152

125153
message GenerateIdTokenRequest {
126-
// The resource name of the service account for which the credentials
154+
// Required. The resource name of the service account for which the credentials
127155
// are requested, in the following format:
128-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
129-
string name = 1;
156+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
157+
// character is required; replacing it with a project ID is invalid.
158+
string name = 1 [
159+
(google.api.field_behavior) = REQUIRED,
160+
(google.api.resource_reference) = {
161+
type: "iam.googleapis.com/ServiceAccount"
162+
}
163+
];
130164

131165
// The sequence of service accounts in a delegation chain. Each service
132166
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
@@ -136,12 +170,13 @@ message GenerateIdTokenRequest {
136170
// request.
137171
//
138172
// The delegates must have the following format:
139-
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
173+
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
174+
// character is required; replacing it with a project ID is invalid.
140175
repeated string delegates = 2;
141176

142-
// The audience for the token, such as the API or account that this token
177+
// Required. The audience for the token, such as the API or account that this token
143178
// grants access to.
144-
string audience = 3;
179+
string audience = 3 [(google.api.field_behavior) = REQUIRED];
145180

146181
// Include the service account email in the token. If set to `true`, the
147182
// token will contain `email` and `email_verified` claims.

0 commit comments

Comments
 (0)
0