Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(iam): mark required params as required in docstring (via synth) #10006

Merged
merged 1 commit into from
Dec 20, 2019
Merged

docs(iam): mark required params as required in docstring (via synth) #10006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 36 additions & 20 deletions iam/google/cloud/iam_credentials_v1/gapic/iam_credentials_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,10 +234,12 @@ def generate_access_token(
>>> response = client.generate_access_token(name, scope)

Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
scope (list[str]): Code to identify the scopes to be included in the OAuth 2.0 access token.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
scope (list[str]): Required. Code to identify the scopes to be included in the OAuth 2.0 access token.
See https://developers.google.com/identity/protocols/googlescopes for more
information.
At least one value required.
Expand All @@ -249,7 +251,9 @@ def generate_access_token(
that is specified in the ``name`` field of the request.

The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
lifetime (Union[dict, ~google.cloud.iam_credentials_v1.types.Duration]): The desired lifetime duration of the access token in seconds.
Must be set to a value less than or equal to 3600 (1 hour). If a value is
not specified, the token's lifetime will be set to a default value of one
Expand Down Expand Up @@ -333,10 +337,12 @@ def generate_id_token(
>>> response = client.generate_id_token(name, audience)

Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
audience (str): The audience for the token, such as the API or account that this token
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
audience (str): Required. The audience for the token, such as the API or account that this token
grants access to.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
Expand All @@ -346,7 +352,9 @@ def generate_id_token(
that is specified in the ``name`` field of the request.

The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
include_email (bool): Include the service account email in the token. If set to ``true``, the
token will contain ``email`` and ``email_verified`` claims.
retry (Optional[google.api_core.retry.Retry]): A retry object used
Expand Down Expand Up @@ -427,10 +435,12 @@ def sign_blob(
>>> response = client.sign_blob(name, payload)

Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
payload (bytes): The bytes to sign.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
payload (bytes): Required. The bytes to sign.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
role on its next service account in the chain. The last service account
Expand All @@ -439,7 +449,9 @@ def sign_blob(
that is specified in the ``name`` field of the request.

The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down Expand Up @@ -515,10 +527,12 @@ def sign_jwt(
>>> response = client.sign_jwt(name, payload)

Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
payload (str): The JWT payload to sign: a JSON object that contains a JWT Claims Set.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
payload (str): Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
role on its next service account in the chain. The last service account
Expand All @@ -527,7 +541,9 @@ def sign_jwt(
that is specified in the ``name`` field of the request.

The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down
85 changes: 60 additions & 25 deletions iam/google/cloud/iam_credentials_v1/proto/common.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2018 Google LLC
// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand All @@ -11,11 +11,14 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package google.iam.credentials.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

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

message GenerateAccessTokenRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

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

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

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

message SignBlobRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

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

// The bytes to sign.
bytes payload = 5;
// Required. The bytes to sign.
bytes payload = 5 [(google.api.field_behavior) = REQUIRED];
}

message SignBlobResponse {
Expand All @@ -94,10 +115,16 @@ message SignBlobResponse {
}

message SignJwtRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

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

// The JWT payload to sign: a JSON object that contains a JWT Claims Set.
string payload = 5;
// Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
string payload = 5 [(google.api.field_behavior) = REQUIRED];
}

message SignJwtResponse {
Expand All @@ -123,10 +151,16 @@ message SignJwtResponse {
}

message GenerateIdTokenRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

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

// The audience for the token, such as the API or account that this token
// Required. The audience for the token, such as the API or account that this token
// grants access to.
string audience = 3;
string audience = 3 [(google.api.field_behavior) = REQUIRED];

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