google.iam.v1 软件包

索引

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)

设置对指定资源的访问权限控制政策。替换任何现有政策。

授权范围

需要以下 OAuth 范围:

  • https://www.googleapis.com/auth/cloud-platform

如需了解详情,请参阅身份验证概览

TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

返回调用者对指定资源拥有的权限。如果资源不存在,则返回一个空权限集,而非返回 NOT_FOUND 错误。

注意:此操作旨在用于构建可感知权限的界面和命令行工具,而不是用于授权检查。此操作可能会在遇到故障时仍然执行而不发出任何警告。

授权范围

需要以下 OAuth 范围:

  • https://www.googleapis.com/auth/cloud-platform

如需了解详情,请参阅身份验证概览

AuditConfig

指定服务的审核配置。该配置决定在日志记录中包含哪些权限类型,以及排除哪些身份(若有)。AuditConfig 必须具有一个或多个 AuditLogConfig。

如果 allServices 和特定服务都有 AuditConfig,则两个 AuditConfig 的并集用于该服务:启用每个 AuditConfig 中指定的 log_type,并且排除每个 AuditLogConfig 中的 exempted_members。

具有多个 AuditConfig 的示例政策如下所示:

{
  "audit_configs": [
    {
      "service": "allServices"
      "audit_log_configs": [
        {
          "log_type": "DATA_READ",
          "exempted_members": [
            "user:foo@gmail.com"
          ]
        },
        {
          "log_type": "DATA_WRITE",
        },
        {
          "log_type": "ADMIN_READ",
        }
      ]
    },
    {
      "service": "fooservice.googleapis.com"
      "audit_log_configs": [
        {
          "log_type": "DATA_READ",
        },
        {
          "log_type": "DATA_WRITE",
          "exempted_members": [
            "user:bar@gmail.com"
          ]
        }
      ]
    }
  ]
}

对于 fooservice,此政策为 DATA_READ、DATA_WRITE 和 ADMIN_READ 活动启用日志记录。此政策还在日志记录中排除 foo@gmail.com 的 DATA_READ 活动和 bar@gmail.com 的 DATA_WRITE 活动。

字段
service

string

指定将为审核日志记录启用的服务,例如 storage.googleapis.comcloudsql.googleapis.comallServices 是一个涵盖所有服务的特殊值。

audit_log_configs[]

AuditLogConfig

对每种类型权限进行日志记录的配置。

AuditLogConfig

提供用于对一种权限进行日志记录的配置。示例:

{
  "audit_log_configs": [
    {
      "log_type": "DATA_READ",
      "exempted_members": [
        "user:foo@gmail.com"
      ]
    },
    {
      "log_type": "DATA_WRITE",
    }
  ]
}

这会为“DATA_READ”和“DATA_WRITE”活动启用日志记录,同时从日志记录中排除 foo@gmail.com 的 DATA_READ 活动。

字段
log_type

LogType

此配置启用的日志类型。

exempted_members[]

string

指定对于哪些身份不在日志记录中记录此类权限的活动。遵循与 Binding.members 相同的格式。

LogType

可以配置日志记录的有效权限类型的列表。管理员写入活动始终会被记录,并且不可配置。

枚举
LOG_TYPE_UNSPECIFIED 默认情况。切勿使用此值。
ADMIN_READ 管理员读取。示例:CloudIAM getIamPolicy
DATA_WRITE 数据写入。示例:CloudSQL 用户创建
DATA_READ 数据读取。示例:CloudSQL 用户列出

Binding

membersrole 关联。

字段
role

string

分配给 members 的角色,例如 roles/viewerroles/editorroles/owner

members[]

string

指定请求访问 Cloud Platform 资源的身份。members 可以具有以下值:

  • allUsers:一个特殊的标识符,代表互联网上的任何人(无论是否有 Google 帐号)。

  • allAuthenticatedUsers:一个特殊的标识符,代表已使用 Google 帐号或服务帐号进行身份验证的任何人。

  • user:{emailid}:一个代表特定 Google 帐号的电子邮件地址,例如 alice@gmail.com

  • serviceAccount:{emailid}:一个代表服务帐号的电子邮件地址,例如 my-other-app@appspot.gserviceaccount.com

  • group:{emailid}:一个代表 Google 群组的电子邮件地址,例如 admins@example.com

  • domain:{domain}:一个 Google Apps 域名,代表该网域的所有用户,例如 google.comexample.com

condition

Expr

未实现。与此绑定关联的条件。注意:若不满足条件,则不允许用户通过当前绑定进行访问。不同的绑定(包括其条件)是独立检查的。

GetIamPolicyRequest

GetIamPolicy 方法的请求消息。

字段
resource

string

必需:所请求的政策应用到的资源。如需了解此字段的相应值,请参阅操作文档。

政策

定义 Identity and Access Management (IAM) 政策,指定 Cloud Platform 资源的访问权限控制政策。

Policy 由一系列 bindings 组成。binding 将一系列 members 绑定到一个 role,其中成员可以是用户帐号、Google 群组、Google 网域及服务帐号。role 是 IAM 定义的权限的命名列表。

JSON 示例

{
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:mike@example.com",
        "group:admins@example.com",
        "domain:google.com",
        "serviceAccount:my-other-app@appspot.gserviceaccount.com"
      ]
    },
    {
      "role": "roles/viewer",
      "members": ["user:sean@example.com"]
    }
  ]
}

YAML 示例

bindings:
- members:
  - user:mike@example.com
  - group:admins@example.com
  - domain:google.com
  - serviceAccount:my-other-app@appspot.gserviceaccount.com
  role: roles/owner
- members:
  - user:sean@example.com
  role: roles/viewer

如需了解 IAM 及其功能,请参阅 IAM 开发者指南

字段
version
(deprecated)

int32

已弃用。

bindings[]

Binding

将一系列 members 关联到 role。没有成员的 bindings 将导致错误。

audit_configs[]

AuditConfig

指定此政策的 Cloud Audit Logging 配置。

etag

bytes

etag 用于乐观并发控制,帮助防止对政策的同时更新相互覆盖。强烈建议系统在读取-修改-写入周期中使用 etag 来执行政策更新以避免竞争条件:返回 etag 来响应 getIamPolicy,并且系统应将该 etag 放入对 setIamPolicy 的请求中,以确保其更改将应用于同一版本的政策。

如果在调用 setIamPolicy 时未提供 etag,则现有政策将被覆盖而毫无提示。

SetIamPolicyRequest

SetIamPolicy 方法的请求消息。

字段
resource

string

必需:为其指定政策的资源。如需了解此字段的相应值,请参阅操作文档。

policy

Policy

必需:要应用于 resource 的完整政策。政策的大小限制为几十 KB。空政策是有效的政策,但可能被某些 Cloud Platform 服务(例如项目)拒绝。

update_mask

FieldMask

可选:指定要修改政策的哪些字段的 FieldMask。只有掩码中的字段会被修改。如果未提供掩码,则使用下列默认掩码:paths: "bindings, etag"。此字段仅供 Cloud IAM 使用。

TestIamPermissionsRequest

TestIamPermissions 方法的请求消息。

字段
resource

string

必填:要请求其政策详情的资源。如需了解此字段的相应值,请参阅操作文档。

permissions[]

string

用于检查 resource 的权限集。不允许使用带通配符(例如“*”或“storage.*”)的权限。如需了解详情,请参阅 IAM 概览

TestIamPermissionsResponse

TestIamPermissions 方法的响应消息。

字段
permissions[]

string

调用者拥有的 TestPermissionsRequest.permissions 的子集。