IAM Conditions 的属性参考文档

本文档介绍了条件表达式中支持的属性。

支持的条件特性

以下几个部分总结了支持的属性，并指出了可识别每个属性的 Google Cloud 服务。

资源特性

以下特性与作为请求主体的资源有关。

属性 用途摘要 支持的 Google Cloud 服务
资源服务特性

根据正在使用的 Google Cloud 服务管理访问权限。

您可以在允许政策角色绑定中使用此属性。
  • Apigee
  • 应用集成
  • 备份和灾难恢复服务
  • BigQuery
  • BigQuery Reservation API
  • Bigtable
  • Binary Authorization
  • Cloud Deploy
  • Cloud Key Management Service
  • Cloud Logging
  • Cloud SQL
  • Cloud Storage
  • Compute Engine
  • Dataform
  • Google Kubernetes Engine
  • Identity-Aware Proxy
  • 集成连接器
  • Pub/Sub Lite
  • Resource Manager
  • Secret Manager
  • Spanner
资源类型特性

根据资源类型管理访问权限。

您可以在允许政策角色绑定中使用此属性。
  • Apigee
  • 应用集成
  • BigQuery
  • BigQuery Reservation API
  • Bigtable
  • Binary Authorization
  • Cloud Key Management Service
  • Cloud Logging
  • Cloud SQL
  • Cloud Storage
  • Compute Engine
  • Dataform
  • Google Kubernetes Engine
  • Identity-Aware Proxy
  • 集成连接器
  • Pub/Sub Lite
  • Resource Manager
  • Secret Manager
  • Spanner
资源名称特性

根据资源名称管理访问权限。

您可以在允许政策角色绑定中使用此属性。
  • Apigee
  • 应用集成
  • 备份和灾难恢复服务
  • BigQuery
  • BigQuery Reservation API
  • Bigtable
  • Binary Authorization
  • Cloud Deploy
  • Cloud Key Management Service
  • Cloud Logging
  • Cloud SQL
  • Cloud Storage
  • Compute Engine
  • Dataform
  • Google Kubernetes Engine
  • Integration Connectors
  • Pub/Sub Lite
  • Secret Manager
  • Spanner
资源标记

根据关联到资源的标记管理访问权限。

您可以在以下位置使用此属性：

  • 允许政策角色绑定
  • 拒绝政策拒绝规则
 所有 Google Cloud 服务（请参阅对继承条件的支持）

如需详细了解资源特性，请参阅本页面上的资源特性。

请求属性

以下特性与请求的详细信息有关。

属性 用途摘要 支持的 Google Cloud 服务

访问权限级别特性

根据特定的访问权限级别管理访问权限。

访问权限级别是一种基于请求和请求者相关原始特性（例如源 IP 地址、设备特性、一天中的时间）计算得出的特性。例如，onNetwork 访问权限级别可能要求发出请求的设备的 IP 地址源自特定的 IP 地址范围。访问权限级别由组织的管理员定义。

您可以在允许政策角色绑定中使用此属性。

Identity-Aware Proxy

API 特性

根据特定 Google Cloud API 或服务提供的数据管理访问权限。

您可以在允许政策角色绑定中使用此属性。
  • Identity and Access Management
  • API Gateway
  • AutoML
  • Certificate Authority Service
  • Cloud Run functions
  • Cloud Healthcare API
  • Cloud IoT
  • Cloud Key Management Service
  • Cloud Run
  • Cloud Runtime Configuration API
  • Cloud Storage
  • Compute Engine
  • Artifact Analysis
  • Dataproc
  • Earth Engine
  • Game Servers
  • Identity and Access Management
  • Identity-Aware Proxy
  • Managed Service for Microsoft Active Directory
  • 用户管理的笔记本
  • Resource Manager
  • Secret Manager
  • 服务管理

日期/时间特性

设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。

您可以在允许政策角色绑定中使用这些属性。

所有 Google Cloud 服务（请参阅对继承条件的支持）

目标 IP 地址/端口特性

根据请求的目标 IP 地址和/或端口管理访问权限。例如，Compute Engine 虚拟机 (VM) 实例可能会公开一个外部 IP 地址（如 10.0.0.2），但端口 22 可能仅会出于管理目的公开。

用于 Identity-Aware Proxy TCP 转发。

您可以在允许政策角色绑定中使用这些属性。

Identity-Aware Proxy

转发规则特性

指定主账号可以创建的转发规则的类型。例如，您可以允许主账号为内部 Google Cloud 负载均衡器（用于处理源自 Google Cloud 网络的流量）创建转发规则，但不允许为外部 Google Cloud 负载均衡器（用于处理源自互联网的流量）创建转发规则。

您可以在允许政策角色绑定中使用这些属性。
  • Cloud Load Balancing
  • Cloud VPN
  • Compute Engine 协议转发
  • Cloud Service Mesh

网址路径/主机特性

根据请求的网址路径和/或主机管理访问权限。例如，某个条件可以指定 https://example.com 是可通过用户的常规网域访问的主应用，而 https://hr.example.com/admin 则用于访问仅人力资源管理员才有权访问的应用中的页面。

您可以在允许政策角色绑定中使用这些属性。
  • Identity-Aware Proxy
  • Cloud Run

如需详细了解请求特性，请参阅本页面上的请求特性。

支持继承条件

某些类型的 Google Cloud 资源不允许在其允许政策中使用条件。不过，您可以在组织、文件夹或项目级层添加条件角色绑定，其他资源将通过资源层次结构沿用这些角色绑定。如需了解详情，请参阅接受有条件角色绑定的资源类型。

在组织、文件夹或项目级使用特性时，请注意，大多数特性仅适用于特定资源类型。如果条件的一部分使用的特性不可用，则系统绝不会将该部分条件解释为授予访问权限。例如，条件 destination.port == 21 绝不会授予任何 BigQuery 资源的访问权限，因为 BigQuery 资源不提供目标 IP 地址/端口属性。

要避免此问题，请使用本页面介绍的资源类型和资源服务特性来限制条件的范围。例如，对于除 Identity-Aware Proxy 隧道实例之外的所有资源类型，以下条件的计算结果为 true；而对于 Identity-Aware Proxy 隧道实例，该条件会检查目标端口：

resource.type != 'iap.googleapis.com/TunnelInstance' ||
    destination.port == 21

您不必限制用于检查关联到资源的标记的条件范围。当某个条件检查标记键和值时，无法检查任何其他特性，包括资源类型和资源服务。

资源特性

资源服务、资源类型和资源名称特性通常用于更改角色绑定提供的访问授权的范围。如果角色包含适用于不同资源特定特性的权限，则可以使用基于资源的条件，授予角色权限中针对特定类型或特定服务的一部分权限。

resource.service 特性

借助 resource.service 特性，您可以根据正在使用的 Google Cloud 服务设置条件。例如，您可以设置条件，限制用户访问使用 cloudresourcemanager.googleapis.com 服务的资源。 如需查看支持的值列表，请参阅资源服务值。

您可以在允许政策角色绑定中使用 resource.service 属性。

特性变量 resource.service
特性类型

string

如需查看支持的值列表，请参阅资源服务值。
支持的运算符 ,
详情 在条件中使用 resource.type 特性时，检查与特性完全相等 () 还是完全不相等 ()。其他比较（例如检查前缀或后缀）可能会造成意外的结果。
示例

对 Compute Engine 资源返回 true：

resource.service == "compute.googleapis.com"
支持的服务
  • Apigee
  • 应用集成
  • 备份和灾难恢复服务
  • BigQuery
  • BigQuery Reservation API
  • Bigtable
  • Binary Authorization
  • Cloud Deploy
  • Cloud Key Management Service
  • Cloud Logging
  • Cloud SQL
  • Cloud Storage
  • Compute Engine
  • Dataform
  • Google Kubernetes Engine
  • Identity-Aware Proxy
  • 集成连接器
  • Pub/Sub Lite
  • Resource Manager
  • Secret Manager
  • Spanner

resource.type 特性

借助 resource.type 特性，您可以根据资源类型设置条件。例如，您可以设置条件，限制用户访问 storage.googleapis.com/Object 类型的资源。 如需查看支持的值列表，请参阅资源类型值。

如果您的条件使用 resource.name 特性，我们强烈建议您使用 resource.type 特性来控制条件适用的资源类型。如需了解详情，请参阅本页面上的 resource.name 特性。

您可以在允许政策角色绑定中使用 resource.type 属性。

特性变量 resource.type
特性类型

string

如需查看支持的值列表，请参阅资源类型值。
支持的运算符 ,
详情 在条件中使用 resource.type 特性时，检查与特性完全相等 () 还是完全不相等 ()。其他比较（例如检查前缀或后缀）可能会造成意外的结果。
示例

除非资源是 Compute Engine 映像，否则返回 true：

resource.type != "compute.googleapis.com/Image"

仅当资源是 Compute Engine 映像或永久性磁盘时，才返回 true：

(resource.type == "compute.googleapis.com/Image" ||
 resource.type == "compute.googleapis.com/Disk")
支持的资源类型
Apigee
  • API 产品特性
  • API 产品
  • API 代理
  • API 代理键值对映射条目
  • API 代理键值对映射
  • API 代理修订版本
  • 缓存
  • 开发者应用特性
  • 开发者应用
  • 开发者特性
  • 开发者
  • 环境键值对映射条目
  • 环境键值对映射
  • 导出内容
  • 流钩子
  • 密钥库别名
  • 密钥库
  • 查询
  • 费率方案
  • 引用
  • 共享流修订版本
  • 共享流
  • 目标服务器
  • 跟踪（调试）会话
备份和灾难恢复服务
  • 备份保险柜
BigQuery
  • 数据集
  • 模型
  • 例程
  • 表
BigQuery Reservation API
  • 作业
  • BI 预留
  • 容量承诺
  • 位置
  • 预订
应用集成
  • Auth 配置
  • 执行
  • 集成版本
  • 集成
  • 位置
  • 暂停
Binary Authorization
  • 证明者
  • 持续验证配置
  • 政策
Bigtable
  • 集群
  • 实例
  • 表
Cloud Key Management Service
  • 加密密钥版本
  • 加密密钥
  • 密钥环
Cloud Logging
  • 日志存储桶
  • 日志视图
Spanner
  • 备份
  • 数据库
  • 实例
Cloud SQL
  • 备份作业
  • 实例
Cloud Storage
  • 存储桶
  • 代管式文件夹
  • 对象
Compute Engine
  • 后端服务（全球和区域）
  • 防火墙
  • 转发规则（全球和区域）
  • 图片
  • 实例模板
  • 实例
  • 永久性磁盘（区域和可用区）
  • 快照
  • 目标 HTTP(S) 代理（全球和区域）
  • 目标 SSL 代理
  • 目标 TCP 代理数
Dataform
  • 编译结果
  • 位置
  • 版本配置
  • 代码库
  • 工作流配置
  • 工作流调用
  • 工作区
Google Cloud
  • 位置1
Google Kubernetes Engine
  • 集群
Firestore
  • 数据库
Identity-Aware Proxy
  • 所有后端服务和 App Engine 应用
  • 所有隧道资源
  • 所有隧道可用区
  • 所有 Web 服务
  • App Engine 应用服务版本
  • App Engine 应用服务
  • Compute Engine 后端服务
  • 隧道实例
集成连接器
  • 连接
  • 连接架构元数据
  • 端点连接
  • 事件订阅
  • 托管式区域
Pub/Sub Lite
  • 位置
  • 订阅
  • 主题
Resource Manager
  • 项目
Secret Manager
  • 密文版本
  • Secret

1 Cloud Key Management Service 将此资源类型用作密钥环资源的父级。

resource.name 特性

借助 resource.name 属性，您可以根据资源名称的全部或部分内容设置条件。如需查看资源名称格式列表，请参阅资源名称格式。

resource.name 属性仅适用于本部分表格中列出的特定资源类型。我们强烈建议您将条件的适用范围限制为目标资源类型。如果角色包含对未提供 resource.name 属性的资源类型的权限，您应确保这些权限不受检查 resource.name 的条件的一部分限制。

以下示例演示如何确保此行为。在此示例中，条件允许访问除 Cloud Storage 存储桶和对象以外的所有资源类型。相比之下，对于存储桶和对象，条件仅允许访问存储桶 example-bucket 及其包含的对象：

(resource.type != 'storage.googleapis.com/Bucket' &&
 resource.type != 'storage.googleapis.com/Object') ||
resource.name.startsWith('projects/_/buckets/example-bucket')

请注意，条件的第一部分会检查资源是否不是存储桶和对象。如果资源的类型不同，则无论资源名称如何，整个条件求得的值为 true。

另请注意，条件会检查 resource.type 特性而非 resource.service 特性。检查 resource.type 特性有以下几个好处：

  • 它会将 resource.name 检查限制为适当的资源集。例如，如果您要授予具有特定名称的 Compute Engine 实例的访问权限，则可以排除 Compute Engine 实例以外的所有资源类型。
  • 如果服务将来添加了新的资源类型，它将阻止条件范围更改。

最后，请注意，条件使用 startsWith() 函数来评估资源名称，而不是使用 运算符检查是否相等。由于该条件查看资源名称的开头，因此它与存储桶以及该存储桶中的对象匹配。如果检查是否相等，则仅匹配存储桶。

您不能使用 * 等通配符字符来匹配多个资源名称。请考虑以下替代方案：

  • 使用 extract() 函数从资源名称中提取值。例如，您可以从 Compute Engine 虚拟机实例的资源名称中提取项目 ID，然后编写引用该项目 ID 的条件表达式。

    如需了解详情，请参阅本页面上的从特性中提取值。

  • 使用 startsWith() 或 endsWith() 函数编写一个条件，用于评估资源名称的开始或结束。

您可以在允许政策角色绑定中使用 resource.name 属性。

特性变量 resource.name
特性类型

string

每种资源类型都为资源名称使用一种特定格式。如需查看这些格式的列表，请参阅资源名称格式。
支持的函数和运算符 startsWith(), endsWith(), extract(), ,
详情

resource.name 包含请求中目标资源的相关资源名称。相关资源名称是不带正斜线 (/) 的 URI 路径。

startsWith() 函数接受前缀字符串字面量，并针对 resource.name 执行计算。

endsWith() 函数接受后缀字符串字面量，并针对 resource.name 执行计算。

extract() 函数使用提取模板来提取 resource.name 的子字符串。如需了解详情，请参见本页面上的从资源名称中提取值。

和 运算符用于与完整的 resource.name 或者 resource.name 的提取部分进行比较。
示例

除非资源名称标识名为 secret-bucket-123 的 Cloud Storage 存储桶，否则返回 true：

resource.name != "projects/_/buckets/secret-bucket-123"

如果资源名称以指定前缀开头并采用 Compute Engine 虚拟机实例使用的格式，则返回 true：

resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod-")

如果资源名称以指定的前缀开头并采用 Cloud Storage 存储桶使用的格式，返回 true：

resource.name.startsWith("projects/_/buckets/my_bucket/objects/test-object-")

如果资源名称以指定的后缀（例如 Cloud Storage 对象的文件扩展名）结尾，则返回 true：

resource.name.endsWith(".jpg")

返回项目名称或编号（如果存在）：

resource.name.extract("projects/{project}/")
支持的资源类型
Apigee
  • API 产品特性
  • API 产品
  • API 代理
  • API 代理键值对映射条目
  • API 代理键值对映射
  • API 代理修订版本
  • 缓存
  • 开发者应用特性
  • 开发者应用
  • 开发者特性
  • 开发者
  • 环境键值对映射条目
  • 环境键值对映射
  • 导出内容
  • 流钩子
  • 密钥库别名
  • 密钥库
  • 查询
  • 费率方案
  • 引用
  • 共享流修订版本
  • 共享流
  • 目标服务器
  • 跟踪（调试）会话
备份和灾难恢复服务
  • 备份保险柜
BigQuery
  • 数据集
  • 模型
  • 例程
  • 表
BigQuery Reservation API
  • 作业
  • BI 预留
  • 容量承诺
  • 位置
  • 预订
应用集成
  • Auth 配置
  • 执行
  • 集成版本
  • 集成
  • 位置
  • 暂停
Binary Authorization
  • 证明者
  • 持续验证配置
  • 政策
Bigtable
  • 集群
  • 实例
  • 表
Cloud Deploy
  • 自动化运行
  • 自动化功能
  • 自定义目标类型
  • 交付流水线
  • 作业运行
  • 版本
  • 发布
  • 目标
Cloud Key Management Service
  • 加密密钥
  • 加密密钥版本
  • 密钥环
Cloud Logging
  • 日志存储桶
  • 日志视图
Spanner
  • 备份
  • 数据库
  • 实例
Cloud SQL
  • 备份作业
  • 实例
Cloud Storage
  • 存储桶
  • 代管式文件夹
  • 对象
Compute Engine
  • 后端服务（全球和区域）
  • 防火墙
  • 转发规则（全球和区域）
  • 图片
  • 实例模板
  • 实例
  • 永久性磁盘（区域和可用区）
  • 快照
  • 目标 HTTP(S) 代理（全球和区域）
  • 目标 SSL 代理
  • 目标 TCP 代理数
Google Kubernetes Engine
  • 集群
Firestore
  • 数据库
Dataform
  • 编译结果
  • 位置
  • 版本配置
  • 代码库
  • 工作流配置
  • 工作流调用
  • 工作区
集成连接器
  • 连接
  • 连接架构元数据
  • 端点连接
  • 事件订阅
  • 托管式区域
Pub/Sub Lite
  • 位置
  • 订阅
  • 主题
Secret Manager
  • 密文版本
  • Secret

资源标记

借助资源标记的函数，您可以根据资源关联到或继承自的标记设置条件。例如，您可以设置条件，以仅对关联了标记 env: prod 的资源授予角色。如需详细了解如何使用标记控制访问权限，请参阅标记和访问权限控制。

每个标记由一个键和一个值组成。每个键和值都有几种不同类型的标识符：

  • 永久 ID，它是全局唯一的，并且永远不能重复使用。例如，标记键可以具有永久 ID tagKeys/123456789012，而标记值可以是永久 ID tagValues/567890123456。
  • 短名称。每个键的简称必须在定义该键的项目或组织内具有唯一性，并且每个值的简称对于关联的键而言必须是唯一的。例如，标记键可以具有短名称 env，标记值可以简称为 prod。
  • 命名空间名称：将组织的数字 ID 或项目的 ID 添加到标记键的简称。例如，为组织创建的标记键可以具有命名空间名称 123456789012/env。如需了解如何获取组织 ID，请参阅获取组织资源 ID。为项目创建的标记键可以具有命名空间名称 myproject/env。如需了解如何获取项目 ID，请参阅识别项目。

如需了解如何选择要在条件中使用的标识符类型，请参阅标记定义和标识符。

您可以使用基于标记的条件来有条件地授予对任何资源的访问权限。这包括具有其自身标记的资源，以及从其他资源继承标记的资源。如需详细了解如何通过资源层次结构继承标记，请参阅标记继承。

您可以在以下情况下使用基于标签的条件：

  • 允许政策角色绑定
  • 拒绝政策拒绝规则

您可以使用以下函数根据标记设置条件：

函数 说明
resource.hasTagKey(
  keyName: string
)   bool

检查请求的资源是否包含具有指定键的标记。标记键通过其命名空间名称查找。如需使用标记键的永久 ID 检查是否存在标记键，请使用函数 resource.hasTagKeyId()。

参数
keyName：标记键的命名空间名称，以组织的数字 ID 和正斜线作为前缀。例如，123456789012/env。
示例

如果请求的资源带有键为 env 的标记，则返回 true。

resource.hasTagKey('123456789012/env')
resource.hasTagKeyId(
  keyId: string
)   bool

检查请求的资源是否包含具有指定键的标记。标记键通过其永久 ID 查找。如需使用标记键的命名空间名称检查是否存在标记键，请使用函数 resource.hasTagKey()。

参数
keyId：标记键的永久 ID。例如，tagKeys/123456789012。
示例

如果请求的资源带有键为 tagKeys/123456789012 的标记，则返回 true。

resource.hasTagKeyId('tagKeys/123456789012')
resource.matchTag(
  keyName: string,
  valueShortName: string
)   bool

检查请求的资源是否包含带有指定键和值的标记。键通过其命名空间名称查询，值通过其短名称查询。如需使用永久 ID 检查标记键和值，请使用函数 resource.matchTagId()。

参数
  • keyName：标记键的命名空间名称，以组织的数字 ID 和正斜线作为前缀。例如，123456789012/env。
  • valueShortName：标记值的短名称。例如，prod。
示例

如果请求的资源具有键为 123456789012/env 且值为 prod 的标记，则返回 true。

resource.matchTag('123456789012/env', 'prod')
resource.matchTagId(
  keyId: string,
  valueId: string
)   bool

检查请求的资源是否包含带有指定键和值的标记。键和值通过其永久 ID 查找。如需使用标记键的命名空间名称和使用其短名称的值检查标记键，请使用函数 resource.matchTag()。

参数
  • keyId：标记键的永久 ID。例如，tagKeys/123456789012。
  • valueId：标记值的永久 ID。例如，tagValues/567890123456。
示例

如果请求的资源具有键为 tagKeys/123456789012 且值为 tagValues/567890123456 的标记，则返回 true。 

resource.matchTagId('tagKeys/123456789012', 'tagValues/567890123456')

请求属性

通过“请求属性”，您可以创建条件来评估请求的详细信息，例如其访问权限级别、日期/时间、目标 IP 地址和端口（适用于 IAP TCP 隧道）或预期网址路径/主机（适用于 IAP 和 Cloud Run）。

访问权限级别特性

访问权限级别特性使用户可以设置条件，要求请求满足一个或多个访问权限级别才能获得授权。 您可以在允许政策角色绑定中使用访问权限级别属性。

访问权限级别特性派生自请求的特性（例如源 IP 地址、设备特性、一天中的时间）。例如，名为 fullyTrusted 的访问权限级别可能会要求发出请求的设备归公司所有，并设置了屏幕锁定。onNetwork 访问权限级别可能要求发出请求的设备源自特定的 IP 地址范围。如需详细了解访问权限级别，请参阅 Access Context Manager 文档。

访问权限级别特性仅适用于以下情况：您使用 Identity-Aware Proxy 访问隧道实例，或者访问在 App Engine 或 Compute Engine 后端服务上运行的 Web 应用。具体而言，访问权限级别特性仅适用于检查以下其中一项权限的请求：

  • iap.tunnelInstances.accessViaIAP
  • iap.webServiceVersions.accessViaIAP

有条件地授予以下预定义角色时，您可以使用访问权限级别特性：

  • IAP-secured Tunnel User (roles/iap.tunnelResourceAccessor)

    包含一项权限：iap.tunnelInstances.accessViaIAP。

  • IAP-secured Web App User (roles/iap.httpsResourceAccessor)

    包含一项权限：iap.webServiceVersions.accessViaIAP。

您还可以使用访问权限级别特性来有条件地授予包含这些权限的自定义角色。自定义角色不得包含任何其他权限。

request.auth.access_levels 特性

特性变量 request.auth.access_levels
特性类型 list<string>
支持的运算符 in
详情

如需检查请求是否符合特定访问权限级别，请使用 in 运算符：

ACCESS_LEVEL_FULL_NAME in request.auth.access_levels

访问权限级别的全名采用以下格式：

accessPolicies/POLICY_NUMBER/accessLevels/ACCESS_LEVEL
示例

如果请求满足 CorpNet 访问权限级别，则返回 true：

"accessPolicies/199923665455/accessLevels/CorpNet"
    in request.auth.access_levels
支持的资源类型 适用于使用 Identity-Aware Proxy 访问隧道实例、隧道目标组、在 Google Cloud Load Balancing 上运行的 Web 应用或在 App Engine 上运行的 Web 应用的请求。

API 特性

API 特性可帮助您根据特定 Google Cloud API 或服务提供的数据管理访问权限。 您可以在允许政策角色绑定中使用 API 属性。

例如，当您使用 Cloud Storage 列出存储桶中的对象时，可以在请求中使用 prefix 参数，以便仅包含名称以特定前缀开头的对象。如果您使用凭据访问边界来缩小短期有效的凭据范围，则可以创建凭据访问边界，用于通过检查 API 特性 storage.googleapis.com/objectListPrefix 来限制列出对象的权限。此 API 特性包含请求中 prefix 参数的值。

如需查看何时可能需要在条件中使用 API 特性的示例，请参阅以下页面：

并非所有服务都可以识别 API 特性。以下部分介绍了哪些服务可识别每个 API 特性。

适用于 API 特性的函数

您可以使用以下函数来处理 API 特性：

函数 说明
api.getAttribute(
  attributeName: string,
  defaultValue: V<T>
)   V<T>

获取请求的 API 属性。

参数
  • attributeName：要获取的 API 特性。如需了解支持的值，请参阅本页面上的 Cloud Storage API 特性和 IAM API 特性。

  • defaultValue：API 特性不可用时使用的默认值 (V)。值 V 的类型为 T，其中 T 与 API 特性的值的类型相同。例如，如果 API 特性的值是字符串，则您可以使用空字符串或占位符字符串，例如 undefined。

示例

返回以下值之一：

  • 对于列出 Cloud Storage 存储桶中的对象的请求，如果请求包含 prefix 参数，则该函数返回其值。
  • 对于省略 prefix 参数的列出对象请求以及所有其他类型的请求，该函数返回空字符串。
api.getAttribute("storage.googleapis.com/objectListPrefix", "")
hasOnly(
  items: list<T>
)   bool

检查列表是仅包含允许的项，还是其中部分项。您可以对 api.getAttribute() 返回的列表调用该函数。

参数
items：类型为 T 的项的列表。每个项都是允许 API 特性包含的值。
示例

检查请求将授予还是撤消 Pub/Sub Editor (roles/pubsub.editor) 或 Pub/Sub Publisher (roles/pubsub.publisher) 以外的任何角色：

api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', [])
    .hasOnly(['roles/pubsub.editor', 'roles/pubsub.publisher'])

下面显示了不同请求值的结果：

授予/撤消的角色 结果
无

true

如果未修改任何角色，api.getAttribute() 返回默认值。对于此特性，默认值始终为空列表。根据定义，空列表不包含不在许可名单中的值。
roles/pubsub.editor

true

该角色在许可名单中。

roles/pubsub.editor
roles/pubsub.publisher

true

这两个角色都在许可名单中。

roles/billing.admin

false

该角色不在许可名单中。

roles/billing.admin
roles/pubsub.editor

false

一个角色在许可名单中，另一个角色不在许可名单中。

Cloud Storage API 特性

Cloud Storage 提供以下 API 特性。

特性变量 storage.googleapis.com/objectListPrefix
特性类型 string
详情

对于列出存储桶中的对象的请求，包含请求中 prefix 参数的值。如果请求省略 prefix 参数，则表示该特性未定义。

对于其他类型的请求，该特性未定义。
可识别此特性的服务 Cloud Storage

IAM API 特性

IAM 提供以下 API 属性：

特性变量 iam.googleapis.com/modifiedGrantsByRole
特性类型 list<string>
详情

对于用于设置资源的允许政策的请求，此特性包含请求修改的角色绑定中的角色名称。

对于其他类型的请求，该特性未定义。
接受此特性的资源类型

以下资源类型接受其允许政策中具有 modifiedGrantsByRole 特性的条件：

  • 项目
  • 文件夹
  • 组织
可识别此特性的服务

以下服务可识别 modifiedGrantsByRole 特性：

  • API Gateway
  • AutoML
  • Certificate Authority Service
  • Cloud Run functions
  • Cloud Healthcare API
  • Cloud IoT
  • Cloud Key Management Service
  • Cloud Run
  • Cloud Runtime Configuration API
  • Cloud Storage
  • Compute Engine
  • Artifact Analysis
  • Dataproc
  • Earth Engine
  • Game Servers
  • Identity and Access Management
  • Identity-Aware Proxy
  • Managed Service for Microsoft Active Directory
  • 用户管理的笔记本
  • Resource Manager
  • Secret Manager
  • 服务管理

日期/时间特性

日期/时间特性用于设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。 您可以在允许政策角色绑定中使用日期/时间属性。

所有 Google Cloud 服务和资源类型都支持此特性。如需了解如何将日期/时间条件应用于不直接支持它们的资源，请参阅本页面上的对继承条件的支持。

request.time 特性包含请求的时间戳。您可以将此时间戳与另一个时间戳或时长进行比较。

以下部分列出了可用于根据时间戳和时长设置条件的函数。

创建、比较和修改时间戳和时长

函数或运算符 说明
date(
  value: string
)   Timestamp

将日期从 string 转换为 Timestamp。

参数
value：格式为 YYYY-MM-DD 的日期，其中 YYYY 为年份，MM 为两位数的月份，DD 为两位数的日期。生成的 Timestamp 包含指定日期和时间 00:00:00.000 UTC。
示例

创建表示日期 2023-02-01 和时间 00:00:00.000 UTC 的 Timestamp：

date("2023-02-01")
duration(
  value: string
)   Duration

将时长从 string 转换为 Duration。

参数
value：以秒为单位的 Duration，后跟 s。
示例

创建表示 1.5 分钟的时长：

duration("90s")

创建表示 30 天的时长：

duration("2592000s")
timestamp(
  value: string
)   Timestamp

将 string 转换为 Timestamp。

参数

value：符合 RFC 3339 的 UTC 时间戳。

示例

创建表示世界协调时间 (UTC) 2023 年 4 月 12 日 23:20:50.52 的时间戳：

timestamp("2023-04-12T23:20:50.52Z")
, , ,

比较两个 Timestamp 值。

示例

如果请求时间早于世界协调时间 (UTC) 2022 年 4 月 12 日 00:00:00，则返回 true：

request.time < timestamp("2022-04-12T00:00:00.00Z")

如果请求时间早于或等于世界协调时间 (UTC) 2022 年 4 月 12 日 00:00:00，则返回 true：

request.time <= timestamp("2022-04-12T00:00:00.00Z")

如果请求时间晚于世界协调时间 (UTC) 2022 年 4 月 12 日 00:00:00，则返回 true：

request.time > timestamp("2022-04-12T00:00:00.00Z")

如果请求时间晚于或等于世界协调时间 (UTC) 2022 年 4 月 12 日 00:00:00，则返回 true：

request.time >= timestamp("2022-04-12T00:00:00.00Z")
  • timestamp + duration   Timestamp
  • timestamp - duration   Timestamp

从 Timestamp 中加上或减去 Duration。

示例

返回世界协调时间 (UTC) 2024-04-12 14:30:00 之后 30 分钟的 Timestamp：

timestamp("2024-04-12T14:30:00.00Z") + duration("1800s")

返回世界协调时间 (UTC) 2024-04-12 14:30:00 之前 60 天的 Timestamp：

timestamp("2024-04-12T14:30:00.00Z") - duration("5184000s")

从时间戳中提取信息

您可以使用本部分中的函数从时间戳中提取信息，例如时间戳所在的星期几。

在 IAM Conditions 中，所有时间戳均采用世界协调时间 (UTC)。但是，您可能希望根据其他时区提取信息。例如，您可能想知道某个世界协调时间 (UTC) 时间戳是否是德国柏林时区的星期一。

如需指定其他时区，请将时区传递给函数。使用 IETF 时区数据库中的名称或世界协调时间 (UTC) 偏移量。例如，您可以使用 Europe/Berlin 或 +01:00 表示中欧时间 (CET)。

支持的函数和运算符 说明
Timestamp.getDate(
  timeZone: string
)   int

从 Timestamp 获取一个月中的某一天。该值使用从 1 开始的索引。一个月的第一天是 1。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间晚于该月的 15 日（UTC 时间），则返回 true：

request.time.getDate() > 15
Timestamp.getDayOfMonth(
  timeZone: string
)   int

从 Timestamp 获取一个月中的某一天。该值使用从 0 开始的索引。一个月的第一天是 0。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间晚于该月的 15 日（UTC 时间），则返回 true：

request.time.getDayOfMonth() > 14
Timestamp.getDayOfWeek(
  timeZone: string
)   int

从 Timestamp 获取一周中的某一天。该值使用从零开始的索引；例如，星期日为 0。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间在德国柏林的星期一和星期五之间，则返回 true：

request.time.getDayOfWeek("Europe/Berlin") > 0 &&
    request.time.getDayOfWeek("Europe/Berlin") < 6
Timestamp.getDayOfYear(
  timeZone: string
)   int

从 Timestamp 获取一年中的某一天。该值使用从 0 开始的索引。一年的第一天是 0。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间是加利福尼亚州山景城一年中的前 5 天，则返回 true：

request.time.getDayOfYear("America/Los_Angeles") >= 0 &&
    request.time.getDayOfYear("America/Los_Angeles") < 5
Timestamp.getFullYear(
  timeZone: string
)   int

从 Timestamp 获取年份。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求在加利福尼亚州山景城的 2023 年期间发送，则返回 true：

request.time.getFullYear("America/Los_Angeles") == 2023

如果请求在世界协调时间 (UTC) 2022 年期间发送，则返回 true：

request.time.getFullYear() == 2022
Timestamp.getHours(
  timeZone: string
)   int

从 Timestamp 获取一天中的小时。该值使用从 0 开始的索引；值的范围为 0 到 23。

您可以将此函数与 getDayofWeek() 结合使用，以仅在您的管辖区允许的工作时间内授予访问权限。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间在德国柏林工作日的 09:00（上午 9:00）到 17:00（下午 5:00）之间，则返回 true：

request.time.getDayOfWeek("Europe/Berlin") >= 1 &&
    request.time.getDayOfWeek("Europe/Berlin") <= 5 &&
    request.time.getHours("Europe/Berlin") >= 9 &&
    request.time.getHours("Europe/Berlin") <= 17
Timestamp.getMilliseconds(
  timeZone: string
)   int

从 Timestamp 获取毫秒数。该值使用从 0 开始的索引；值的范围为 0 到 999。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
Timestamp.getMinutes(
  timeZone: string
)   int

从 Timestamp 获取小时之后的分钟数。该值使用从 0 开始的索引；值的范围为 0 到 59。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间等于或晚于德国柏林的 09:30（上午 9:30），则返回 true：

request.time.getHours("Europe/Berlin") >= 9 &&
    request.time.getMinutes("Europe/Berlin") >= 30
Timestamp.getMonth(
  timeZone: string
)   int

从 Timestamp 获取一年中的月份。该值使用从 0 开始的索引；值的范围为 0 到 11。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
示例

如果请求的发送时间是加利福尼亚州山景城的 4 月份，则返回 true：

request.time.getMonth("America/Los_Angeles") == 3
Timestamp.getSeconds(
  timeZone: string
)   int

从 Timestamp 获取秒数。该值使用从 0 开始的索引；值的范围为 0 到 59。

参数
timeZone：要为其计算结果的时区。默认为 UTC。
, , ,

比较此表中两个函数的输出。

目标 IP/端口特性

目标 IP 地址/端口属性允许用户根据请求的内部目标 IP 地址和端口来管理访问权限。您可以在允许政策角色绑定中使用目标 IP/端口属性。

例如，Compute Engine 虚拟机实例可能会将外部 IP 地址和端口 132.168.42.21:3001 映射到内部 IP 地址和端口 10.0.0.1:2300以供一般使用。相比之下，内部 IP 地址和端口 10.0.0.1:22 可能仅在内部供管理使用。您可以使用目的地 IP/端口特性，根据内部 IP 地址和端口授予不同数量的访问权限。

如需详细了解 TCP 转发，请参阅 Identity-Aware Proxy 文档。

destination.ip 属性

特性变量 destination.ip
特性类型 string
支持的运算符 ,
详情

变量 destination.ip 标识 IPv4 格式的内部 IP 地址。
示例

如果目标 IP 地址为 10.0.0.1，则返回 true：

destination.ip == "10.0.0.1"

除非目标 IP 地址为 10.0.0.1，否则返回 true：

destination.ip != "10.0.0.1"
支持的资源类型 适用于使用 Identity-Aware Proxy 访问隧道实例的请求

destination.port 特性

特性变量 destination.port
特性类型 int
支持的运算符 , , , , ,
详情

变量 destination.port 标识内部 TCP 端口号。
示例

如果目标端口为 21，则返回 true： 

destination.port == 21

如果目标端口小于 3001，则返回 true： 

destination.port < 3001
支持的资源类型 适用于使用 Identity-Aware Proxy 访问隧道实例的请求

转发规则特性

借助转发规则属性，您可以指定主账号可以创建的转发规则的类型。例如，您可以允许主账号为内部 Google Cloud 负载均衡器（用于处理源自 Google Cloud 网络的流量）创建转发规则，但不允许为外部 Google Cloud 负载均衡器（用于处理源自互联网的流量）创建转发规则。您可以在允许政策角色绑定中使用转发规则属性。

对于 Cloud Load Balancing，转发规则属性不会影响创建 Google Cloud 负载均衡器的其他组件（例如后端服务、目标代理、健康检查和网址映射）的能力。

支持的函数

函数 说明
compute.isForwardingRuleCreationOperation()   bool

检查请求是否正在创建转发规则。

示例
请参阅 compute.matchLoadBalancingSchemes() 的示例。
compute.matchLoadBalancingSchemes(
  schemes: list<string>
)   bool

检查请求是否会影响指定类型的负载均衡方案。如需查找每种负载均衡方案的标识符以及更多详细信息，请参阅在 Google Cloud 负载均衡器上使用 IAM Conditions。

参数
schemes：允许请求影响的负载均衡方案。
示例

返回以下值之一：

  • 如果请求不是创建转发规则，则返回 true。
  • 如果请求是创建转发规则，则仅在转发规则影响 INTERNAL、INTERNAL_MANAGED 或 INTERNAL_SELF_MANAGED 负载均衡方案时返回 true。
!compute.isForwardingRuleCreationOperation() || (
  compute.isForwardingRuleCreationOperation() &&
  compute.matchLoadBalancingSchemes([
    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
  ])
)

支持的资源类型

此特性适用于创建以下资源类型的请求：

服务 资源类型
Cloud Load Balancing 转发规则
Cloud VPN 转发规则（全球和区域）
Compute Engine 转发规则（用于协议转发）
Cloud Service Mesh1 转发规则

1 使用 Compute Engine 的资源特性。

网址路径/主机特性

通过网址路径/主机属性，用户可以根据请求的网址路径和主机来管理访问权限。例如，某项条件可以指定 https://example.com 是可供用户的常规网域访问的主应用，而 https://hr.example.com/admin 用于访问应用中只有人力资源管理员才能访问的部分下的某个页面。

您可以在允许政策角色绑定中使用网址路径/主机属性。

request.path 属性

特性变量 request.path
特性类型 string
支持的函数和运算符 , startsWith(), endsWith()
详情 我们不建议将 运算符与此特性搭配使用。检查特性的前缀（如 !request.path.startsWith("/admin")），而不是检查不等于（如 request.path != "/admin"）。通过检查前缀，您还可以保护 /admin 层次结构中的网址路径，例如 /admin/payroll/。
示例

如果请求路径等于指定网址路径，则返回 true：

request.path == "/admin"
 
request.path == "/admin/payroll"

如果请求路径以指定的网址路径开头，则返回 true：

request.path.startsWith("/admin")

如果请求路径以指定的网址路径结尾，则返回 true：

request.path.endsWith("/payroll.js")
支持的资源类型
  • Identity-Aware Proxy 应用服务版本 (App Engine)：适用于使用 Identity-Aware Proxy 访问 App Engine 或 Compute Engine 上运行的 Web 应用的请求
  • Cloud Run 服务

request.host 特性

特性变量 request.host
特性类型 string
支持的函数和运算符 , endsWith()
详情 我们不建议将 .startsWith() 函数或 运算符与此特性搭配使用。这些函数和运算符可能会产生意外结果。
示例

如果主机名等于指定值，则返回 true：

request.host == "www.example.com"
 
request.host == "hr.example.com"

如果主机名以指定的值结尾，则返回 true：

request.host.endsWith("example.com")
支持的资源类型
  • Identity-Aware Proxy 应用服务版本 (App Engine)：适用于使用 Identity-Aware Proxy 访问应用服务版本的请求。
  • Cloud Run 服务

从特性中提取值

您可以使用 extract() 函数从特性中提取值。例如，您可以提取资源名称的任意部分，然后编写引用您所提取的文本的条件表达式。

如需使用 extract() 函数，请提供一个提取模板，用于指定要提取的特性部分。例如，如果您要从 Compute Engine 虚拟机实例的资源名称中提取项目 ID，可以使用模板 projects/{project}/。

提取模板包含以下组成部分：

  • 括号内的标识符，用于标识要提取的子字符串。

    请选择一个有意义的简短标识符，明确指出要提取的值。您可以使用从 A 到 Z 的大写和小写字母、数字和下划线 (_)。

    在模板 projects/{project}/ 中，标识符为 project。

  • 可选：前缀，它必须出现在要提取的子字符串之前。

    在模板 projects/{project}/ 中，前缀为 projects/。

  • 可选：后缀，它必须出现在要提取的子字符串之后。

    在模板 projects/{project}/ 中，后缀为 /。

extract() 函数会根据提取模板具有前缀、后缀还是两者兼有来提取不同属性部分：

有前缀 有后缀 提取的值
— — 整个属性
— 第一处出现的前缀后的字符，如果前缀后面没有字符，则为空字符串
— 第一处出现的后缀前的字符，如果后缀前面没有字符，则为空字符串
第一处出现的前缀与其后第一处出现的后缀之间的字符，如果该前缀与该后缀之间没有字符，则为空字符串

如果您指定的前缀或后缀未出现在属性中，或后缀仅出现在前缀之前，则 extract() 函数会返回空字符串。

以下示例展示了几个不同提取模板的输出结果。这些示例引用了 Cloud Storage 对象的资源名称 projects/_/buckets/acme-orders-aaa/objects/data_lake/orders/order_date=2019-11-03/aef87g87ae0876：

提取模板 输出
/order_date={date}/ 2019-11-03
buckets/{name}/ acme-orders-aaa
/orders/{empty}order_date “string”为空
{start}/objects/data_lake projects/_/buckets/acme-orders-aaa
orders/{end} order_date=2019-11-03/aef87g87ae0876
{all} projects/_/buckets/acme-orders-aaa/objects/data_lake/orders/order_date=2019-11-03/aef87g87ae0876
/orders/{none}/order_date= “string”为空
/orders/order_date=2019-11-03/{id}/data_lake “string”为空

如果您提取表示日期的字符串，则可以使用本页面上的日期/时间函数和运算符将提取的值转换为 Timestamp。如需查看示例，请参阅配置基于资源的访问权限。