IAM Conditions 的特性参考文档

本主题介绍了条件表达式中支持的特性。

支持的条件特性

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

资源特性

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

特性 用途摘要 支持的 Google Cloud 服务
资源服务特性 根据正在使用的 Google Cloud 服务管理访问权限。
  • Cloud Key Management Service
  • Cloud Spanner
  • Cloud Storage
  • Compute Engine
  • Identity-Aware Proxy
  • Pub/Sub Lite
  • Resource Manager（仅限资源类型和资源服务）
  • Secret Manager
资源类型特性 根据资源类型管理访问权限。
资源名称特性 根据资源名称管理访问权限。
资源标记 根据关联到资源的标记管理访问权限。 所有 Google Cloud 服务

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

请求特性

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

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

访问权限级别特性

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

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

Identity-Aware Proxy

API 特性

根据特定 Google Cloud API 或服务提供的数据管理访问权限。
  • Cloud Storage
  • Identity and Access Management
  • AI Platform Notebooks
  • API 网关
  • AutoML
  • Certificate Authority Service
  • Cloud Functions
  • Cloud Healthcare API
  • Cloud IoT
  • Cloud Key Management Service
  • Cloud Run
  • Cloud Runtime Configuration API
  • Compute Engine
  • 容器分析
  • 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 协议转发
  • Traffic Director

网址路径/主机特性

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

Identity-Aware Proxy

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

支持继承条件

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

在组织、文件夹或项目级使用特性时，请注意，大多数特性仅适用于特定资源类型。从 2021 年 2 月 26 日开始，如果条件的一部分使用的特性不可用，则系统绝不会将该部分条件解释为授予访问权限。例如，条件 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
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串


如需查看所有支持的资源服务字符串字面量的列表，请参阅 IAM Conditions 的资源特性。

讨论 变量 resource.service（如使用）用于执行相等性或不等性比较。

注意：.startsWith(<prefix string>) 和 .endsWith(<suffix string>) 函数不应与 resource.service 特性一起使用，否则会出现意外计算结果，出于此原因，不建议您将这些函数与该特性一起使用。
示例

示例 1： 


resource.service == "compute.googleapis.com"
支持的服务
  • Cloud Key Management Service
  • Cloud Spanner
  • Cloud Storage
  • Compute Engine
  • Identity-Aware Proxy
  • Pub/Sub Lite
  • Resource Manager（仅限资源类型和资源服务）
  • Secret Manager

resource.type 特性

借助 resource.type 特性，您可以根据资源类型设置条件。例如，您可以设置条件，限制用户访问 storage.googleapis.com/Object 类型的资源。

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

特性变量 resource.type
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串


如需查看所有支持的资源类型字符串字面量的列表，请参阅 IAM Conditions 的资源特性。

讨论 变量 resource.type（如使用）用于执行相等性或不等性比较。

注意：.startsWith(<prefix string>) 和 .endsWith(<suffix string>) 函数不应与 resource.type 特性一起使用，否则会出现意外计算结果，出于此原因，不建议您将这些函数与该特性一起使用。
示例

示例 1： 


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

示例 2： 


(resource.type == "compute.googleapis.com/Image" ||
 resource.type == "compute.googleapis.com/Disk")
支持的资源类型
Cloud Key Management Service
  • 加密密钥版本
  • 加密密钥
  • 密钥环
Cloud Spanner
  • 数据库
  • 实例
Cloud Storage
  • 存储分区
  • 对象
Compute Engine
  • 后端服务（全球和区域）
  • 防火墙
  • 转发规则（全球和区域）
  • 映像
  • 实例模板
  • 实例
  • 永久性磁盘（区域和可用区）
  • 快照
  • 目标 HTTP(S) 代理（全球和区域）
  • 目标 SSL 代理
  • 目标 TCP 代理
Google Cloud 位置1
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 实例以外的所有资源类型。
  • 如果服务将来添加了新的资源类型，它将阻止条件范围更改。

您可以使用 extract() 函数从资源名称中提取值。 例如，您可以从 Compute Engine 虚拟机实例的资源名称中提取项目 ID，然后编写引用该项目 ID 的条件表达式。如需了解详情，请参阅本页面上的从特性中提取值。

特性变量 resource.name
特性类型 字符串
支持的运算符 startsWith()、endsWith()、extract()、==、!=
支持的操作数

字符串

每种资源类型都为资源名称使用一种特定格式。如需查看这些格式的列表，请参阅资源名称格式。
讨论

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

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

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

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

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

示例 1（对于 Compute Engine 虚拟机实例）： 


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

示例 2（对于 Cloud Storage 存储分区）： 


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

示例 3（对于 Cloud Storage 对象）： 


resource.name.endsWith(".jpg")

示例 4（对于多种资源类型）： 


resource.name.extract("projects/{project}/")

示例 5（对于 Cloud Storage 存储分区）： 


resource.name != "projects/_/buckets/secret-bucket-123"
支持的资源类型
Cloud Key Management Service
  • 加密密钥
  • 加密密钥版本
  • 密钥环
Cloud Spanner
  • 数据库
  • 实例
Cloud Storage
  • 存储分区
  • 对象
Compute Engine
  • 后端服务（全球和区域）
  • 防火墙
  • 转发规则（全球和区域）
  • 映像
  • 实例模板
  • 实例
  • 永久性磁盘（区域和可用区）
  • 快照
  • 目标 HTTP(S) 代理（全球和区域）
  • 目标 SSL 代理
  • 目标 TCP 代理
Pub/Sub Lite
  • 位置
  • 订阅
  • 主题
Secret Manager
  • 密文版本
  • Secret

资源标记

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

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

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

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

您可以使用以下函数处理标记：

函数 类型 说明
resource.hasTagKey String --> bool

函数：

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

参数：String：标记键的命名空间名称，并将组织的数字 ID 和正斜杠作为前缀。例如 123456789012/env。

示例：

resource.hasTagKey('123456789012/env')
如果请求的资源带有键为 env 的标记，则返回 true。
resource.hasTagKeyId String --> bool

函数：

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

参数：字符串：标记键的永久 ID。 例如 tagKeys/123456789012。

示例：

resource.hasTagKeyId('tagKeys/123456789012')
如果请求的资源带有键为 tagKeys/123456789012 的标记，则返回 true。
resource.matchTag (String, String) --> 布尔值

函数：

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

参数：

第一个 String 参数是标记键的命名空间名称，带有组织的数字 ID 和正斜杠作为前缀。例如：123456789012/env。

第二个 String 参数是标记值的短名称。例如：prod。

示例：

resource.matchTag('123456789012/env', 'prod')
如果请求的资源具有键为 123456789012/env 且值为 prod 的标记，则返回 true。
resource.matchTagId (String, String) --> 布尔值

函数：

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

参数：

第一个 String 参数是标记键的永久 ID。例如：tagKeys/123456789012。

第二个 String 参数是标记值的永久性 ID。例如：tagValues/567890123456。

示例：

resource.matchTagId('tagKeys/123456789012', 'tagValues/567890123456')
如果请求的资源具有键为 tagKeys/123456789012 且值为 tagValues/567890123456 的标记，则返回 true。

请求特性

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

访问权限级别特性

借助访问权限级别特性，用户可以设置条件，规定只有在请求满足特定访问权限级别时才能为其授权。

访问权限级别特性派生自请求的特性（例如源 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
特性类型 字符串列表
支持的运算符 in
支持的操作数 字符串
讨论

变量 request.auth.access_levels 显示在 in 运算符右侧，其左侧显示代表已定义访问权限级别全名的字符串。

访问权限级别的全名采用以下名称格式：
"accessPolicies/<policyNumber>/accessLevels/<shortName>"

注意：访问权限级别字符串区分大小写，且必须与 Access Context Manager 中的配置完全匹配才能产生预期作用。例如，“accessPolicies/199923665455/accessLevels/CorpNet”是要在表达式中使用的有效字符串文本，而“accessPolicies/199923665455/accesslevels/CorpNet”无法产生预期作用。
示例 

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

API 特性

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

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

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

请参阅以下部分，了解哪些服务可识别 API 特性。

适用于 API 特性的函数

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

函数 类型 说明
api.getAttribute (String, T) --> T

函数：获取请求的 API 特性。

参数：

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

T：当没有 API 特性时要使用的默认值。请使用与 API 特性值相同的类型。例如，如果 API 特性的值是字符串，则您可以使用空字符串或占位符字符串，例如 undefined。

示例：

api.getAttribute("storage.googleapis.com/objectListPrefix", "")
用于列出 Cloud Storage 存储分区中的对象的 prefix 参数的值。对于省略 prefix 参数的请求以及其他请求类型，返回空字符串。
hasOnly List<T>.(List<T>) --> bool

函数：检查列表是仅包含允许的项，还是其中部分项。

参数：

List<T>：类型为 T 的项列表。您对 api.getAttribute() 返回的列表调用该函数。此参数是 API 特性可以包含的项列表。

示例：

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

检查请求将授予还是撤消除 Pub/Sub Editor (roles/pubsub.editor) 或 Pub/Sub Publisher (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 字符串

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

对于其他类型的请求，该特性未定义。

可识别此特性的服务：

只有 Cloud Storage 能够识别此特性。

IAM API 特性

IAM 提供以下 API 特性：

属性 类型 说明
iam.googleapis.com/modifiedGrantsByRole 数组

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

对于其他类型的请求，该特性未定义。

接受此特性的资源：

以下资源接受其 IAM 政策中具有 modifiedGrantsByRole 特性的条件：

  • 项目
  • 文件夹
  • 单位

可识别此特性的服务：

以下服务可识别 modifiedGrantsByRole 特性：

  • AI Platform Notebooks
  • API 网关
  • AutoML
  • Certificate Authority Service
  • Cloud Functions
  • Cloud Healthcare API
  • Cloud IoT
  • Cloud Key Management Service
  • Cloud Run
  • Cloud Runtime Configuration API
  • Compute Engine
  • 容器分析
  • 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 String --> Timestamp

函数：将字符串转换为时间戳。
参数：格式为 YYYY-MM-DD 的字符串，其中 YYYY 为年份，MM 为两位数的月份，DD 为两位数的日期。生成的时间戳包含指定日期和时间 00:00:00.000 UTC。

示例：

date("2020-02-01")
表示日期 2020-02-01 和时间 00:00:00.000 UTC 的时间戳。

duration String --> Duration

函数：将字符串转换为时长。
参数：包含秒数的字符串，后跟 s

示例：

duration("90s")
表示 1.5 分钟的时长。

duration("2592000s")
表示 30 天的时长。

timestamp

String --> Timestamp

函数：将字符串转换为时间戳。
参数：遵循世界协调时间 (UTC) 格式 (RFC 3339) 的字符串。

示例：

timestamp("1985-04-12T23:20:50.52Z")
这表示对 1985 年 4 月 12 日 23 时 20 分 50.52 秒（采用世界协调时间 (UTC)）的时间戳转换。

timestamp("1996-12-19T16:39:57-08:00")
这表示对 1996 年 12 月 19 日 16 时 39 分 57 秒（与世界协调时间 (UTC) 的偏移量为 -08:00）的时间戳转换。请注意，此时间相当于采用世界协调时间 (UTC) 的 1996-12-20T00:39:57Z。此偏移量不能反映时区，例如，太平洋标准时间相对于世界协调时间 (UTC) 的偏移量在冬季为 -08:00，而在夏季由于采用夏令时，其偏移量变为 -07:00。

重要提示：
字符串必须遵循世界协调时间 (UTC) 字符串的格式要求。任何不符合世界协调时间 (UTC) 格式的字符串都会导致 timestamp() 函数无法将字符串转换为时间戳值。因此，使用 timestamp() 对表达式进行条件评估会导致授权失败。

<, <=, >, >=

(Timestamp, Timestamp) --> bool

函数：与时间戳类型的常规比较。

示例：

request.time < timestamp("2018-04-12T00:00:00.00Z")
request.time <= timestamp("2018-04-12T00:00:00.00Z")
request.time > timestamp("2018-04-12T00:00:00.00Z")
request.time >= timestamp("2018-04-12T00:00:00.00Z")
这些表达式会将请求时间与指定时间戳（示例中为世界协调时间 (UTC) 的 2018 年 4 月 12 日）进行比较。通常用于设置角色授予的“开始时间”或“到期时间”条件。

注意：由于时间精确到毫秒，包含等于和不等于比较（==、!=）的意义不大。
+、- (Timestamp, Duration) --> Timestamp

函数：在时间戳的基础上加上或减去时长。

示例：

timestamp("2018-04-12T14:30:00.00Z") + duration("1800s")
查找格林尼治标准时间 2018 年 4 月 12 日 14:30:00 之后 30 分钟内的时间戳。

timestamp("2018-04-12T14:30:00.00Z") - duration("5184000s")
查找格林尼治标准时间 2018 年 4 月 12 日 14:30:00 之前 60 天内的时间戳。

支持的高级函数和运算符

用于日期/时间特性的特性变量为 request.time，类型为时间戳。

支持的高级函数 类型 说明

<, <=, >, >=, ==, !=

(int, int) --> bool

函数：对 int 类型的值执行常规比较。

讨论：
这组整数比较运算符主要供带有时间戳函数的其余“高级函数”使用。所有这些函数（请参见此表其余部分的定义）将时间戳值的特定部分转换为 int 类型。我们还提供了各种高级函数的示例，展示了常见用法建议。

getDate, getDayOfMonth, getDayOfWeek, getDayOfYear

Timestamp.() --> int

Timestamp.(string) --> int

函数：
getDate：根据时间戳值获取一个月中的某天（从 1 开始编制索引）。这种索引编制方式的含义是，一个月的第一天是 1。

getDayOfMonth：根据时间戳值获取一个月中的某天（从 0 开始编制索引）。这种索引编制方式的含义是，一个月的第一天是 0。

getDayOfWeek：根据时间戳值（星期日索引为 0）获取一周中的某天。这种索引编制方式的含义是，星期天(0)、星期一(1)、...、星期六(6)。

getDayOfYear：根据时间戳值获取一年中的某天（从 0 开始编制索引）。这种索引编制方式的含义是，一年的第一天是 0。

参数：
字符串表示时区：根据该时区的日期进行转换。注意：如果未指定时区，将根据世界协调时间 (UTC) 日期进行转换。

如需详细了解有效的时区字符串，请参阅支持的时区值。

示例：

request.time.getDayOfWeek() > 0 && request.time.getDayOfWeek() < 6
如果传入请求是在星期一到星期五之间（采用世界协调时间 (UTC) 时间）发送的，则此表达式的计算结果为 true。

示例：

request.time.getDayOfWeek("Europe/Berlin") > 0 && request.time.getDayOfWeek(Europe/Berlin") < 6
如果收到的请求是在星期一到星期五（采用柏林时区）之间发送的，则此表达式的计算结果为 true。

示例：

request.time.getDayOfYear("America/Los_Angeles") >= 0 && request.time.getDayOfYear("America/Los_Angeles") < 5
如果传入请求在一年的前 5 天（采用洛杉矶时区）内发送的，则此表达式的计算结果为 true。

getFullYear

Timestamp.() --> int

Timestamp.(string) --> int

函数：获取日期的年份。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

示例：

request.time.getFullYear("America/Los_Angeles") == 2018
如果传入请求是在 2018 年（采用洛杉矶时区）发送的，则此表达式的计算结果为 true。

示例：

request.time.getFullYear() < 2020
如果传入请求是在 2019 年年底（采用世界协调时间 (UTC)）之前发送的，则此表达式的计算结果为 true。

getHours

Timestamp.() --> int

Timestamp.(string) --> int

函数：获取日期的小时数；值介于 0 到 23 之间。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

示例：

request.time.getHours("Europe/Berlin") >= 9 && request.time.getHours("Europe/Berlin") <= 17
此表达式指定了工作时间条件。如果相应请求在上午 9 点至下午 5 点（采用柏林时区）之间发送，则此表达式的计算结果为 true。

注意：

将 getHours() 与 getDayofWeek() 结合使用可用于设置法定工作时间条件，例如出于符合司法管辖区要求的目的。

getMilliseconds

Timestamp.() --> int

Timestamp.(string) --> int

函数：根据时间戳获取一秒中的毫秒数；值介于 0 到 999 之间。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

注意：

鉴于语义上的有限用法，此函数用处不大。

getMinutes

Timestamp.() --> int

Timestamp.(string) --> int

函数：根据时间戳获取一小时中的分钟数；值介于 0 到 59 之间。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

注意：

鉴于语义上的有限用法，此函数用处不大。

getMonth

Timestamp.() --> int

Timestamp.(string) --> int

函数：根据时间戳获取一年中的月数；值介于 0 到 11 之间。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

示例：

request.time.getMonth("America/Los_Angeles") == 3
如果传入请求是在 4 月份（采用洛杉矶时区）发送的，则此表达式的计算结果为 true。

getSeconds

Timestamp.() --> int

Timestamp.(string) --> int

函数：根据时间戳获取一分钟中的秒数；值介于 0 到 59 之间。

参数：
版本 1：无参数；以世界协调时间 (UTC) 日期为依据。
版本 2：时区字符串；以相应时区的日期为依据。

如需详细了解有效的时区字符串，请参阅支持的时区值。

注意：

鉴于语义上的有限用法，此函数用处不大。

目标 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
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串
讨论

变量 destination.ip 应是一个字符串，表示 IPv4 格式的内部 IP 地址。

注意：startsWith(<prefix string of IP>) 函数和 endsWith(<suffix string of IP>) 函数不应与 destination.ip 特性一起使用。虽然设置 destination.ip.startsWith(<prefix string of IP>) 之类的条件不会在执行 setIamPolicy 操作时造成语法错误，但由于会出现意外结果，我们不建议如此设置。对 CIDR 执行 IP 地址范围检查时，不建议在 IP 字符串上进行前缀匹配。

示例 

destination.ip == "10.0.0.1"

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

destination.port 特性

特性变量 destination.port
特性类型 整数
支持的运算符 ==, !=, <, <=, >, >=
支持的操作数 整数
讨论

变量 destination.port 应是表示内部 TCP 端口号的整数。
示例 

destination.port == 21

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

转发规则特性

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

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

支持的函数

支持的函数 类型 说明
compute.isForwardingRuleCreationOperation() () --> bool

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

示例：查看 compute.matchLoadBalancingSchemes() 的示例。
compute.matchLoadBalancingSchemes() Array.(string)--> bool

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

参数：字符串数组

示例： 


!compute.isForwardingRuleCreationOperation() || (
  compute.isForwardingRuleCreationOperation() &&
  compute.matchLoadBalancingSchemes([
    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
  ]))
)
  • 如果请求不是创建转发规则，则将该角色授予该成员。
  • 如果请求是创建转发规则，则仅在转发规则影响 INTERNAL、INTERNAL_MANAGED 或 INTERNAL_SELF_MANAGED 负载平衡方案时授予角色。

支持的资源类型

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

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

1 使用 Compute Engine 的资源特性。

网址路径/主机特性

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

request.path 特性

特性变量 request.path
特性类型 字符串
支持的运算符 ==, startsWith(), endsWith()
支持的操作数/参数
  • 字符串：==
  • 常量前缀字符串：startsWith()
  • 常量后缀字符串：endsWith()
讨论 注意：我们不建议使用 != 运算符。 建议您不要使用下面这样的否定比较：

request.path != "/admin"
而是使用前缀匹配，例如：

! request.path.startsWith("/admin")
这样，以“/admin”为父级路径的网址路径（例如“/admin/payroll/”）就会受到保护，不会出现意外访问。
示例

示例 1： 


request.path == "/admin"

request.path == "/admin/payroll"

在上述两个示例中的相等性 (==) 比较中使用的字符串应根据网址路径标准进行格式设置。

示例 2： 


request.path.startsWith("/admin")

此函数中使用表示网址路径前缀的字符串。

示例 3： 


request.path.endsWith("/payroll.js")

此函数中使用表示网址路径后缀的字符串。
支持的资源类型

Identity-Aware Proxy 应用服务版本 (App Engine)

适用于使用 Identity-Aware Proxy 访问 App Engine 或 Compute Engine 上运行的 Web 应用的请求

request.host 特性

特性变量 request.host
特性类型 字符串
支持的运算符 ==, endsWith()
支持的操作数/参数
  • 字符串：==
  • 常量后缀字符串：endsWith()
讨论 .startsWith(<prefix string>) 函数不应与 request.host 特性一起使用。虽然设置 request.host.startsWith(<prefix string>) 之类的条件不会在执行 setIamPolicy 操作时造成语法错误，但由于会出现意外结果，我们不建议如此设置。出于同样的原因，也不建议您使用 !=。
示例

示例 1： 


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

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

在上述两个示例中的相等性 (==) 比较中使用的字符串应根据网站主机名的网址字符串标准进行格式设置。

示例 2： 


request.host.endsWith("example.com")

表示网站主机名后缀的字符串。

支持的资源类型

Identity-Aware Proxy 应用服务版本 (App Engine)

适用于使用 Identity-Aware Proxy 访问应用服务版本的请求。

从特性中提取值

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

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

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

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

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

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

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

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

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

根据提取模板是否带有前缀、后缀或者两者兼有，extract() 函数会返回不同的值：

有前缀 有后缀 提取的值
— — 资源的完整名称
— 第一处出现的前缀后的字符，如果前缀后面没有字符，则为空字符串
— 第一处出现的后缀前的字符，如果后缀前面没有字符，则为空字符串
第一处出现的前缀与其后第一处出现的后缀之间的字符，如果该前缀与该后缀之间没有字符，则为空字符串

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

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

提取模板 输出
/order_date={date}/ 2019-11-03
buckets/{name}/ acme-orders-aaa
/orders/{empty}order_date 空字符串
{start}/data_lake projects/_/buckets/acme-orders-aaa
orders/{end} order_date=2019-11-03/aef87g87ae0876
{all} projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876
/orders/{none}/order_date= null
/orders/order_date=2019-11-03/{id}/data_lake null

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