Package google.iam.v1

索引

• IAMPolicy（接口）
• Binding（消息）
• GetIamPolicyRequest（消息）
• GetPolicyOptions（消息）
• Policy（消息）
• SetIamPolicyRequest（消息）
• TestIamPermissionsRequest（消息）
• TestIamPermissionsResponse（消息）

IAMPolicy

API 概览

此接口管理 Identity and Access Management (IAM) 政策。

任何提供访问权限控制功能的 API 的实现都会实现 google.iam.v1.IAMPolicy 接口。

数据模型

当主体（用户或服务账号）对服务提供的资源执行操作时，系统就会执行访问权限控制。由类似 URI 的名称标识的资源是访问权限控制规范的基本单元。服务实现可以选择访问权限控制的粒度以及其资源支持的权限。例如，一个数据库服务可能仅允许在表级层指定访问权限控制，而另一个数据库服务可能还允许在列级层指定访问权限控制。

政策结构

请参阅 google.iam.v1.Policy

我们特意不采用 CRUD 式的 API，因为访问控制政策是与其附加到的资源一并隐式创建和删除的。

GetIamPolicy
rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy) 获取资源的访问权限控制政策。如果资源存在但未设置政策，则返回空政策。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

SetIamPolicy
rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy) 设置对指定资源的访问权限控制政策。替换任何现有政策。 可能返回 NOT_FOUND、INVALID_ARGUMENT、PERMISSION_DENIED 错误。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

TestIamPermissions
rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse) 返回调用者对指定资源拥有的权限。如果资源不存在，则返回一个空权限集，而非返回 NOT_FOUND 错误。 注意：此操作旨在用于构建权限感知型界面和命令行工具，而不是用于授权检查。此操作可能会在没有警告的情况下“应急开启”。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/cloud-platform 如需了解详情，请参阅身份验证概览。

绑定

将 members 或主账号与 role 关联。

字段
role	string 分配给 members 或主账号列表的角色。例如 roles/viewer、roles/editor 或 roles/owner。
members[]	string 指定请求访问 Google Cloud 资源的身份。members 可以具有以下值： allUsers：一个特殊的标识符，表示互联网上的任何人（无论是否拥有 Google 账号）。 allAuthenticatedUsers：一个特殊的标识符，表示使用 Google 账号或服务账号进行身份验证的任何用户。 不包括来自外部身份提供方 (IdP) 通过身份联合的身份。 user:{emailid}：表示特定 Google 账号的电子邮件地址。例如 [e-mail]。 serviceAccount:{emailid}：表示 Google 服务账号的电子邮件地址。例如 [e-mail]。 serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]：Kubernetes 服务账号的标识符。例如 my-project.svc.id.goog[my-namespace/my-kubernetes-sa]。 group:{emailid}：表示 Google 群组的电子邮件地址。例如 [e-mail]。 domain:{domain}：G Suite 网域（主网域），表示该网域中的所有用户。例如 google.com 或 example.com。 deleted:user:{emailid}?uid={uniqueid}：表示最近被删除的用户的电子邮件地址（以及唯一标识符）。例如 [e-mail]?uid=123456789012345678901。如果用户已恢复，则此值会恢复为 user:{emailid}，而且恢复的用户将保留绑定中的角色。 deleted:serviceAccount:{emailid}?uid={uniqueid}：表示最近被删除的服务账号的电子邮件地址（以及唯一标识符）。例如 [e-mail]?uid=123456789012345678901。如果恢复删除的服务账号，则此值会还原为 serviceAccount:{emailid}，而且删除的服务账号在恢复后将保留绑定中的角色。 deleted:group:{emailid}?uid={uniqueid}：表示最近被删除的 Google 群组的电子邮件地址（以及唯一标识符）。例如 [e-mail]?uid=123456789012345678901。如果群组已恢复，则此值会恢复为 group:{emailid}，而且恢复的群组将保留绑定中的角色。
condition	Expr 与此绑定关联的条件。 如果条件的计算结果为 true，则此绑定会应用于当前请求。 如果条件的计算结果为 false，则此绑定不会应用于当前请求。但是，不同的角色绑定可能会向此绑定中的一个或多个主账号授予相同角色。 如需了解哪些资源支持在其 IAM 政策中使用条件，请参阅 IAM 文档。

GetIamPolicyRequest

GetIamPolicy 方法的请求消息。

字段
resource	string 必需字段：要为其请求政策的资源。如需了解此字段的适当值，请参阅资源名称。
options	GetPolicyOptions 可选：用于指定 GetIamPolicy 选项的 GetPolicyOptions 对象。

GetPolicyOptions

封装提供给 GetIamPolicy 的设置。

字段
requested_policy_version	int32 可选。将用于设置政策格式的最高政策版本。 有效值包括 0、1 和 3。指定无效值的请求将被拒绝。 对具有任何条件角色绑定的政策的请求必须指定版本 3。没有任何条件角色绑定的政策可以指定任何有效值，也可以不设置该字段。 响应中的政策可能会使用您指定的政策版本，也可能会使用较低的政策版本。例如，如果您指定版本 3，但政策没有任何条件角色绑定，则响应将使用版本 1。 如需了解哪些资源支持在其 IAM 政策中使用条件，请参阅 IAM 文档。

Policy

Identity and Access Management (IAM) 政策，用于指定 Google Cloud 资源的访问权限控制。

Policy 是 bindings 的集合。binding 会将一个或多个 members 或主账号绑定到单个 role。主账号可以是用户账号、服务账号、Google 群组以及网域（例如 G Suite）。role 是命名的权限列表；每个 role 可以是 IAM 预定义角色或用户创建的自定义角色。

对于某些类型的 Google Cloud 资源，binding 还可以指定 condition，这是一个逻辑表达式。只有在此表达式的计算结果为 true 时才允许访问资源。条件可以根据请求和/或资源的特性添加限制条件。如需了解哪些资源支持在其 IAM 政策中使用条件，请参阅 IAM 文档。

JSON 示例：

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:[e-mail]",
            "group:[e-mail]",
            "domain:google.com",
            "serviceAccount:[e-mail]"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:[e-mail]"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

YAML 示例：

    bindings:
    - members:
      - user:[e-mail]
      - group:[e-mail]
      - domain:google.com
      - serviceAccount:[e-mail]
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:[e-mail]
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

如需了解 IAM 及其功能，请参阅 IAM 文档。

字段
version	int32 指定政策的格式。 有效值为 0、1 和 3。指定无效值的请求将被拒绝。 任何影响条件角色绑定的操作都必须指定版本 3。此要求适用于以下操作： 获取包含条件角色绑定的政策 向政策添加条件角色绑定 更改政策中的条件角色绑定 从包含条件的政策中移除任何角色绑定，而无论此绑定是否含有条件 重要提示：如果您使用 IAM 条件，则必须在调用 setIamPolicy 时包含 etag 字段。如果您省略此字段，则 IAM 允许您使用版本 1 政策覆盖版本 3 政策，而且版本 3 政策中的所有条件都会丢失。 如果政策不包含任何条件，则对该政策执行的操作可以指定任何有效版本，也可以不设置该字段。 如需了解哪些资源支持在其 IAM 政策中使用条件，请参阅 IAM 文档。
bindings[]	Binding 将一组 members 或主账号与一个 role 相关联。（可选）可以指定一个 condition 以确定如何及何时应用 bindings。每个 bindings 必须至少包含一个主账号。 Policy 中的 bindings 最多可以引用 1,500 个主账号；其中，最多有 250 个主账号可以是 Google 群组。主账号的每个实例都会计入相应限制。例如，如果 bindings 向 user:[e-mail] 授予了 50 个不同的角色且没有向任何其他主账号授予角色，那么您最多还可以向 Policy 中的 bindings 添加 1,450 个主账号。
etag	bytes etag 用于乐观并发控制，可帮助防止同时对政策进行的更新相互覆盖。强烈建议系统在“读取-修改-写入”周期中使用 etag 来执行政策更新以避免冲突：返回 etag 来响应 getIamPolicy，系统应将该 etag 放入对 setIamPolicy 的请求中，以确保其更改将应用于同一版本的政策。 重要提示：如果您使用 IAM 条件，则必须在调用 setIamPolicy 时包含 etag 字段。如果您省略此字段，则 IAM 允许您使用版本 1 政策覆盖版本 3 政策，而且版本 3 政策中的所有条件都会丢失。

SetIamPolicyRequest

SetIamPolicy 方法的请求消息。

字段
resource	string 必需：要为其指定政策的资源。如需了解此字段的适当值，请参阅资源名称。
policy	Policy 必需：要应用于 resource 的完整政策。政策的大小限制为几十 KB。空政策是有效的政策，但可能被某些 Google Cloud 服务（例如项目）拒绝。

TestIamPermissionsRequest

TestIamPermissions 方法的请求消息。

字段
resource	string 必需字段：要为其请求政策详情的资源。如需了解此字段的适当值，请参阅资源名称。
permissions[]	string 要用于检查 resource 的权限集。不允许使用带通配符（例如 * 或 storage.*）的权限。如需了解详情，请参阅 IAM 概览。

TestIamPermissionsResponse

TestIamPermissions 方法的响应消息。

字段
permissions[]	string 调用者可以使用的 TestPermissionsRequest.permissions 的子集。