Attribute reference for IAM Conditions
This document describes supported attributes in acondition expression.
Note: This page shows common uses of each function and operator. For moredetails about the allowed syntax for functions and operators, see theCEL language definition.Supported condition attributes
The following sections summarize the supported attributes and indicate whichGoogle Cloud services recognize each attribute.
Resource attributes
The following attributes relate to the resource that is the subject of therequest.
| Attribute | Usage summary | Supported Google Cloud services |
|---|---|---|
| Resource service attribute | Manage access based on the Google Cloud service being used. You can use this attribute in allow policy role bindings. |
|
| Resource type attribute | Manage access based on the resource type. You can use this attribute in allow policy role bindings. |
|
| Resource name attribute | Manage access based on the name of the resource. You can use this attribute in allow policy role bindings. |
|
| Resource tags | Manage access based on the tags attached to the resource. You can use this attribute in the following places:
| All Google Cloud services (seeSupport for inherited conditions) Note: Certainareas of the Google Cloud console don't recognize allow policy role bindingswith tag-based conditions. As a result, if you have a role with a tag-basedcondition, then the Google Cloud console might incorrectly prevent you fromperforming certain actions. If you encounter this issue, then use an alternatemethod, such as the gcloud CLI, to perform the action. |
For more details about resource attributes, seeResource attributeson this page.
Principal attributes
The following attributes relate to the principal making the request.
| Attribute | Usage summary | Supported principal types |
|---|---|---|
Apply policies based on the type of principal in the request. You can use this attribute in policy bindings for principal access boundary policies. |
| |
Apply policies based on the identity of the principal in the request. You can use this attribute in policy bindings for principal access boundary policies. |
|
For more details about principal attributes, seePrincipalattributes on this page.
Request attributes
The following attributes relate to the details of the request.
| Attribute | Usage summary | Supported Google Cloud services |
|---|---|---|
Manage access based on specific access level(s). An access level is a calculated attribute based on raw attributes about the request and requester, such as the origin IP address, device attributes, and time of day. For example, an You can use this attribute in allow policy role bindings. | Identity-Aware Proxy | |
Manage access based on data provided by a specific Google Cloud API or service. You can use this attribute in allow policy role bindings. |
| |
Set expirable, scheduled, or limited-duration access to Google Cloud resources. You can use these attributes in allow policy role bindings. | All Google Cloud services (seeSupport for inherited conditions) | |
Manage access based on the destination IP address and/or port of a request. For example, a Compute Engine virtual machine (VM) instance might expose an external IP, such as Used forIdentity-Aware Proxy TCP forwarding. You can use these attributes in allow policy role bindings. | Identity-Aware Proxy | |
Specify the types offorwarding rules that a principal can create. For example, you could allow a principal to create forwarding rules forinternal Google Cloud load balancers, which handle traffic that originates inside a Google Cloud network, but not for external Google Cloud load balancers, which handle traffic that originates from the internet. You can use these attributes in allow policy role bindings. |
| |
Manage access based on the URL path and/or host of a request. For example, a condition could specify that You can use these attributes in allow policy role bindings. |
|
For more details about request attributes, seeRequest attributes onthis page.
Support for inherited conditions
Some types of Google Cloud resources don't allow conditions in theirallow policies. However, you can add conditional role bindings at theorganization, folder, or project level, and other resources will inherit thoserole bindings through theresource hierarchy. For details,seeResource types that accept conditional role bindings.
When you use attributes at the organization, folder, or project level, keep inmind that most attributes are available only for specific resource types. Ifpart of a condition uses an attribute that is not available, then that part ofthe condition is never interpreted as granting access. For example, theconditionresource.name.endsWith == devResource will never grant access to anyIAM resource, because IAM resources don'tprovide the resource name.
To prevent this issue, use theresource type andresource service attributes described on this page to limitthe scope of the condition. For example, the following condition evaluates totrue for all resource types other than Compute Engine instances; incontrast, for Compute Engine instances, the condition checks resource name:
resource.type != 'compute.googleapis.com/Disk' || resource.name.endsWith('devResource')You don't need to limit the scope of conditions that check thetags attached to a resource. When a condition checks tag keysand values, it cannot check any other attributes, including the resource typeand resource service.
Important: If your condition uses theresource.name attribute, we stronglyrecommend that you use theresource.type attribute, not theresource.serviceattribute, to explicitly limit which resource types theresource.namecondition applies to. For details, seeresource.name attribute on this page.Resource attributes
The resource service, resource type, and resource name attributes are typicallyused to change the scope of an access grant provided by the role binding. When arole contains permissions that apply to different resource-specific attributes,resource-based conditions can be used to grant a subset of the role'spermissions for specific type(s) or for specific service(s).
resource.service attribute
Theresource.service attribute lets you set a condition based on theGoogle Cloud service being used. For example, you could set a conditionlimiting a user's access to resources that use thecloudresourcemanager.googleapis.com service. For a list of supported values,seeResource service values.
You can use theresource.service attribute in allow policy role bindings.
| Attribute variable | resource.service |
|---|---|
| Attribute type |
For a list of supported values, seeResource service values. |
| Supported operators | , |
| Details | When you use theresource.type attribute in conditions, check for exact equality ( |
| Example | Returns resource.service == "compute.googleapis.com" |
| Supported services |
|
resource.type attribute
Theresource.type attribute lets you set a condition based on the resource'stype. For example, you could set a condition limiting a user's access toresources of the typestorage.googleapis.com/Object. For a list of supportedvalues, seeResource type values.
If your condition uses theresource.name attribute, we strongly recommend thatyou use theresource.type attribute to control which resource types thecondition applies to. For details, seeresource.name attribute on this page.
You can use theresource.type attribute in allow policy role bindings.
| Attribute variable | resource.type | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Attribute type |
For a list of supported values, seeResource type values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| Supported operators | , | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| Details | When you use theresource.type attribute in conditions, check for exact equality ( | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| Examples | Returns resource.type != "compute.googleapis.com/Image" Returns (resource.type == "compute.googleapis.com/Image" || resource.type == "compute.googleapis.com/Disk") | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| Supported resource types |
1 Cloud Key Management Service uses this resource type as the parent of key ring resources. |
resource.name attribute
Theresource.name attribute lets you set a condition based on all or part of aresource name. For a list of resource name formats, seeResource nameformat.
Theresource.name attribute is available only for specific resource types,which are listed in the table in this section. We strongly recommend that youlimit the applicability of the condition to the intended resource type. If arole contains permissions for a resource type that does not provide theresource.name attribute, you should ensure that those permissions are notrestricted by the part of the condition that checksresource.name.
The following example shows how to ensure this behavior. In this example, thecondition allows access to all resource types except Cloud Storage buckets andobjects. In contrast, for buckets and objects, the condition only allows accessto the bucketexample-bucket and the objects it contains:
(resource.type != 'storage.googleapis.com/Bucket' && resource.type != 'storage.googleapis.com/Object') ||resource.name.startsWith('projects/_/buckets/example-bucket')Note that the first part of the condition checks whether the resource is neithera bucket nor an object. If the resource has a different type, then the entirecondition evaluates totrue, regardless of the resource name.
Also, note that the condition checks theresource.type attribute, not theresource.service attribute. There are a few benefits of checking theresource.type attribute:
- It limits the
resource.namecheck to the appropriate set of resources. Forexample, if you want to grant access to Compute Engine instances with aspecific name, it makes sense to exclude all resource types other thanCompute Engine instances. - It prevents the scope of the condition from changing if a service adds newresource types in the future.
Finally, note that the condition uses thestartsWith() function to evaluatethe resource name, rather than checking for equality with theoperator. Because the condition looks at the start of the resource name, itmatches a bucket as well as the objects in that bucket. If it checked forequality, it would only match the bucket.
You cannot use wildcard characters such as* to match multiple resourcenames. Consider these alternatives:
Use the
extract()function to extract a value from a resource name. Forexample, you can extract a project ID from the resource name of aCompute Engine VM instance, then write a condition expression thatrefers to the project ID.For details, seeExtracting values from attributes on this page.
Use the
startsWith()orendsWith()function to write a condition thatevaluates the start or end of the resource name.
You can use theresource.name attribute in allow policy role bindings.
| Attribute variable | resource.name | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Attribute type |
Each resource type uses a specific format for the resource name. For a list of formats, seeResource name format. | ||||||||||||||||||||||||||||||||||||||||||||||||
| Supported functions and operators | startsWith(), endsWith(), extract(),, | ||||||||||||||||||||||||||||||||||||||||||||||||
| Details | The The The The The | ||||||||||||||||||||||||||||||||||||||||||||||||
| Examples | Returns resource.name != "projects/_/buckets/secret-bucket-123" Returns resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod-") Returns resource.name.startsWith("projects/_/buckets/my_bucket/objects/test-object-") Returns resource.name.endsWith(".jpg")Returns the project name or number if it's present: resource.name.extract("projects/{project}/") | ||||||||||||||||||||||||||||||||||||||||||||||||
| Supported resource types |
|
Resource tags
The resource tag functions let you set a condition based on the tags that areattached tosupported resources or inherited by thoseresources' descendants. For example, you can set a condition that grants arole only for resources that have the tagenv: prod attached. To learn moreabout controlling access with tags, seeTags and access control.
Note: Conditions that check the tags for a resourceand other attributes, such as the resource name or the timestamp of the request, are in preview. Such conditions are subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. For more information, see thelaunch stage descriptions. Conditions that check the tags for a resource anddon't check any other attributes are generally available.
Each tag consists of a key and a value. There are a few different types ofidentifiers for each key and value:
- Apermanent ID, which is globally unique and can never be reused. For example, a tag key could have the permanent ID
tagKeys/123456789012, and a tag value could have the permanent IDtagValues/567890123456. - Ashort name. The short name for each key must be unique within the project or organization under which the key is defined, and the short name for each value must be unique for its associated key. For example, a tag key could have the short name
env, and a tag value could have the short nameprod. - Anamespaced name, which adds your organization's numeric ID or project's ID to the short name of a tag key. For example, a tag key created for an organization could have the namespaced name
123456789012/env. To learn how to get your organization ID, seeGetting your organization resource ID. A tag key created for a project could have the namespaced namemyproject/env. To learn how to get your project ID, seeIdentifying projects.
For guidance on choosing which type of identifier to use in your conditions, seeTag definitions and identifiers.
You can use tag-based conditions to conditionalize access to any resource. Thisincludes resources with their own tags, as well as resources that inherit tagsfrom other resources. To learn more about how tags are inherited throughthe resource hierarchy, seeTag inheritance.
However, certainareas of the Google Cloud console don't recognize allow policy role bindingswith tag-based conditions. As a result, if you have a role with a tag-basedcondition, then the Google Cloud console might incorrectly prevent you fromperforming certain actions. If you encounter this issue, then use an alternatemethod, such as the gcloud CLI, to perform the action.
You can use tag-based conditions in the following:
- Allow policy role bindings
- Deny policy deny rules
You can use the following functions to set conditions based on tags:
| Function | Description |
|---|---|
resource.hasTagKey( bool | Checks whether the resource for the request has a tag with the specified key. The tag key is looked up by itsnamespaced name. To check for a tag key using itspermanent ID, use the function
|
resource.hasTagKeyId( bool | Checks whether the resource for the request has a tag with the specified key. The tag key is looked up by itspermanent ID. To check for a tag key using itsnamespaced name, use the function
|
resource.matchTag( bool | Checks whether the resource for the request has a tag with the specified key and value. The key is looked up by itsnamespaced name, and the value is looked up by itsshort name. To check for a tag key and value using theirpermanent IDs, use the function
|
resource.matchTagId( bool | Checks whether the resource for the request has a tag with the specified key and value. The key and value are looked up by theirpermanent IDs. To check for a tag key using itsnamespaced name and a value using itsshort name, use the function
|
Principal attributes
The principal attributes let you write conditions based on the principal thatissued the request. With these attributes, you can refine the principals that apolicy is enforced for.
You can use principal attributes in policy bindings for principal access boundarypolicies.
principal.type attribute
Theprincipal.type attribute lets you set a condition based on the type ofprincipal issuing the request. For example, you could add a condition to apolicy binding for a principal access boundary policy to ensure that the policy is onlyenforced for service accounts.
You can use principal attributes in policy bindings for principal access boundarypolicies.
| Attribute variable | principal.type |
|---|---|
| Attribute type |
|
| Supported operators | ,, in |
| Supported principal types |
|
| Examples | Evaluates to principal.type == "iam.googleapis.com/ServiceAccount" Evaluates to principal.type in ["iam.googleapis.com/WorkspaceIdentity", "iam.googleapis.com/WorkforcePoolIdentity"] |
principal.subject attribute
Theprincipal.subject attribute lets you set a condition based on theprincipal issuing the request. For example, you could add a condition to apolicy binding for a principal access boundary policy to ensure that the policy is onlyenforced for principals whose email addresses end with@example.com.
If you use theprincipal.subject attribute in a condition, we recommend alsousing theprincipal.type attribute to control which typesof principals the condition applies to. This is because principal identifiersaren't necessarily unique across principal types. For example, the identifierexample-user@example.com could identify a Google Account or a user in aworkforce identity pool.
By using theprincipal.type attribute in addition to theprincipal.subjectattribute, you can ensure that the condition only matches principals with theintended type. For example, the following expression matches Google Accountswhose email addresses end with@example.com:
principal.type == 'iam.googleapis.com/WorkspaceIdentity' &&principal.subject.endsWith('@example.com')You can use principal attributes in policy bindings for principal access boundarypolicies.
| Attribute variable | principal.subject |
|---|---|
| Attribute type |
|
| Supported operators |
startsWith() andendsWith() functions matchall principals that start with or end with the specified value. For example, the expressionstartsWith('security-admin') matchessecurity-admin@example.com andsecurity-admin@example-project.iam.gserviceaccount.com, but also matchessecurity-admin-fake@example.com. |
| Supported principal subjects |
|
| Example | Evaluates to principal.subject.endsWith("@example.com") Evaluates to principal.subject == "example-service-account@example-project.iam.gserviceaccount.com" |
Request attributes
Request attributes enable you to create conditions that evaluate details aboutthe request, such as its access level, its date and time, the destination IPaddress and port (for IAP TCP tunneling), or the expected URLpath/host (for IAP and Cloud Run).
Access levels attribute
The access levels attribute enables users to set a condition requiring that arequest meets one or more access levels in order to be authorized. You can usethe access levels attribute in allow policy role bindings.
The access levels attribute is derived from attributes of the request, such asthe origin IP address, device attributes, and the time of day. For example, anaccess level namedfullyTrusted might require that the device making therequest is owned by the company and has a screen lock. AnonNetwork accesslevel might require that the device making the request originates from aparticular IP address range. See theAccess Context Managerdocumentation for more information about access levels.
The access levels attribute is available only when you use Identity-Aware Proxy toaccess a tunnel instance, or to access a web application running on App Engineor Compute Engine backend services. More specifically, the access levelsattribute is available only for requests that check one of these permissions:
iap.tunnelInstances.accessViaIAPiap.webServiceVersions.accessViaIAP
iap.tunnelInstances.accessViaIAP andiap.webServiceVersions.accessViaIAPpermissions. If the binding grants a role that contains other permissions, thenthese additional, unsupported permissions won't work correctly.You can use the access levels attribute when you conditionally grant thefollowing predefined roles:
IAP-secured Tunnel User (
roles/iap.tunnelResourceAccessor)Contains a single permission,
iap.tunnelInstances.accessViaIAP.IAP-secured Web App User (
roles/iap.httpsResourceAccessor)Contains a single permission,
iap.webServiceVersions.accessViaIAP.
You can also use the access levels attribute to conditionally grant a customrole that contains these permissions. The custom role must not contain any otherpermissions.
request.auth.access_levels attribute
| Attribute variable | request.auth.access_levels |
|---|---|
| Attribute type | list<string> |
| Supported operators | in |
| Details | To check whether a request meets a specific access level, use the ACCESS_LEVEL_FULL_NAME in request.auth.access_levels The full name of an access level uses the following format: accessPolicies/POLICY_NUMBER/accessLevels/ACCESS_LEVEL accesslevels, in all lowercase, rather thanaccessLevels, withLevels capitalized, then the access level in the request will never match the access level in the condition. |
| Example | Returns "accessPolicies/199923665455/accessLevels/CorpNet" in request.auth.access_levels |
| Supported resource types | Available for requests that use Identity-Aware Proxy to access a tunnel instance, tunnel destination group, web application running on Google Cloud load balancing, or web application running on App Engine. |
API attributes
API attributes help you manage access based on data provided by a specificGoogle Cloud API or service. You can use API attributes in allow policyrole bindings.
For example, when you use Cloud Storage tolist the objects in a bucket, you can use theprefix parameterin the request to include only objects whose names begin with a specific prefix.If you useCredential Access Boundaries to downscope short-livedcredentials, you can create a Credential Access Boundary that limits permissionsto list objects by checking the API attributestorage.googleapis.com/objectListPrefix. This API attribute contains the valueof theprefix parameter from the request.
For examples of when you might need to use API attributes in a condition, seethe following pages:
Not all services recognize API attributes. The following sections indicate whichservices recognize each API attribute.
Functions for API attributes
You can use the following function to work with API attributes:
| Function | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
api.getAttribute( V<T> | Gets the requested API attribute.
| ||||||||||||
hasOnly( bool | Checks that a list contains only the allowed items, or a subset of those items. You can call the function on a list returned by
|
Cloud Storage API attributes
Cloud Storage provides the following API attribute.
Warning: API attributes for Cloud Storage are supported only inCredential Access Boundaries. If you useCloud Storage API attributes in a conditional role binding, then Cloud Storage methodswill work incorrectly and fail unexpectedly. In addition, it might take longer to checkIAM permissions when you access Cloud Storage.| Attribute variable | storage.googleapis.com/objectListPrefix |
|---|---|
| Attribute type | string |
| Details | For a request tolist objects in a bucket, contains the value of the For other types of requests, the attribute is not defined. |
| Services that recognize this attribute | Cloud Storage |
IAM API attributes
IAM provides the following API attribute:
Date/time attribute
The date/time attribute is used to set expirable, scheduled, or limited-durationaccess to Google Cloud resources. You can use date/time attributes inallow policy role bindings.
This attribute is supported for all Google Cloud services and resourcetypes. To learn how to apply date/time conditions to resources that don'tdirectly support them, seeSupport for inherited conditions on this page.
Therequest.time attribute contains the timestamp for the request. You cancompare this timestamp to another timestamp, or to a duration of time.
The following sections list the functions that you can use to set conditionsbased on timestamps and durations.
Create, compare, and modify timestamps and durations
| Function or operator | Description |
|---|---|
date( Timestamp | Converts a date from a
|
duration( Duration | Converts an amount of time from a
|
timestamp( Timestamp | Converts a
|
,,, | Compares two
|
| Add or subtract a
|
Extract information from a timestamp
The functions in this section let you extract information from a timestamp, suchas the day of the week that the timestamp falls on.
In IAM Conditions, all timestamps are in UTC. However, you mightwant to extract information based on a different time zone. For example, youmight want to know whether a UTC timestamp falls on a Monday in the time zonefor Berlin, Germany.
To specify a different time zone, pass the time zone into the function. Use aname or UTC offset from theIETFTime Zone Database. For example, you could useEurope/Berlin or+01:00for Central European Time (CET).
| Supported functions and operators | Description |
|---|---|
Timestamp.getDate( int | Gets the day of the month from the
|
Timestamp.getDayOfMonth( int | Gets the day of the month from the
|
Timestamp.getDayOfWeek( int | Gets the day of the week from the
|
Timestamp.getDayOfYear( int | Gets the day of the year from the
|
Timestamp.getFullYear( int | Gets the year from the
|
Timestamp.getHours( int | Gets the hour of the day from the You can combine this function with
|
Timestamp.getMilliseconds( int | Gets the number of milliseconds from the
|
Timestamp.getMinutes( int | Gets the number of minutes after the hour from the
|
Timestamp.getMonth( int | Gets the month of the year from the
|
Timestamp.getSeconds( int | Gets the number of seconds from the
|
,,, | Compares the output of two functions in this table. |
Destination IP/port attributes
The destination IP/port attribute enables users to manage access based on theinternal destination IP address and port for a request. You can usedestination IP/port attributes in allow policy role bindings.
For example, a Compute Engine VM instance might map the external IPaddress and port132.168.42.21:3001 to the internal IP address and port10.0.0.1:2300 for general usage. In contrast, the internal IP address and port10.0.0.1:22 might only be available internally for administrative usage. Youcan use the destination IP/port attributes to grant different amounts of accessbased on the internal IP address and port.
For more information about TCP forwarding, see theIdentity-Aware Proxy documentation.
destination.ip attribute
| Attribute variable | destination.ip |
|---|---|
| Attribute type | string |
| Supported operators | , |
| Details | The variable startsWith() andendsWith() functions with thedestination.ip attribute. These functions might give you unexpected results. In particular, we don't recommend matching a prefix indestination.ip to check a CIDR address range. |
| Examples | Returns destination.ip == "10.0.0.1" Returns destination.ip != "10.0.0.1" |
| Supported resource types | Available for requests that use Identity-Aware Proxy to access a tunnel instance |
destination.port attribute
| Attribute variable | destination.port |
|---|---|
| Attribute type | int |
| Supported operators | ,,,,, |
| Details | The variable |
| Examples | Returns destination.port == 21 Returns destination.port < 3001 |
| Supported resource types | Available for requests that use Identity-Aware Proxy to access a tunnel instance |
Forwarding rule attributes
The forwarding rule attributes enable you to specify the types offorwardingrules that a principal can create. For example, youcould allow a principal to create forwarding rules forinternal Google Cloudload balancers, which handle traffic that originatesinside a Google Cloud network, but not for external Google Cloudload balancers, which handle traffic that originates from the internet. You canuse forwarding rule attributes in allow policy role bindings.
For Cloud Load Balancing, the forwarding rule attributes don't affect theability to create other components of a Google Cloud load balancer, suchas backend services, target proxies, health checks, and URL maps.
Note: In the Google Cloud console, if you want to include the forwarding ruleattributes in a condition expression, you must use the Condition editor. Theforwarding rule attributes are not available in the Condition builder.Supported functions
Supported resource types
This attribute is available for requests to create the following resource types:
| Service | Resource types |
|---|---|
| Cloud Load Balancing | Forwarding rules |
| Cloud VPN | Forwarding rules (global and regional) |
| Compute Engine | Forwarding rules (forprotocol forwarding) |
| Cloud Service Mesh1 | Forwarding rules |
1 Uses theresource attributes forCompute Engine.
URL path/host attribute
The URL path/host attribute enables users to manage access based on the URL pathand host of a request. For example, a condition could specify thathttps://example.com is the main application accessible by a general domain ofusers, whilehttps://hr.example.com/admin is used to access a page in theapplication where only Human Resources admins can access this portion.
You can use the URL path/host attribute in allow policy role bindings.
request.path attribute
| Attribute variable | request.path |
|---|---|
| Attribute type | string |
| Supported functions and operators | , startsWith(), endsWith() |
| Details | We don't recommend using therequest.path != "/admin", check the attribute's prefix, as in!request.path.startsWith("/admin"). By checking the prefix, you also protect URL paths within the/admin hierarchy, such as/admin/payroll/. |
| Examples | Returns request.path == "/admin" request.path == "/admin/payroll" Returns request.path.startsWith("/admin") Returns request.path.endsWith("/payroll.js") |
| Supported resource types |
|
request.host attribute
| Attribute variable | request.host |
|---|---|
| Attribute type | string |
| Supported functions and operators | , endsWith() |
| Details | We don't recommend using the.startsWith() function or the |
| Examples | Returns request.host == "www.example.com" request.host == "hr.example.com" Returns request.host.endsWith("example.com") |
| Supported resource types |
|
Extract values from attributes
You can use theextract() function to extract a value from an attribute. Forexample, you can extract an arbitrary part of a resource name, then write acondition expression that refers to the text you extracted.
To use theextract() function, you provide anextraction template, whichspecifies the part of the attribute to extract. For example, if you want toextract a project ID from the resource name of a Compute Engine VMinstance, you might use the templateprojects/{project}/.
An extraction template contains the following parts:
Anidentifier, enclosed in curly braces, that identifies the substring toextract.
Choose a short, meaningful identifier that makes it clear what value youwant to extract. You can use uppercase and lowercase letters from
AtoZ; numeric digits; and underscores (_).In the template
projects/{project}/, the identifier isproject.Optional: Aprefix, which must appear before the substring to extract.
In the template
projects/{project}/, the prefix isprojects/.Optional: Asuffix, which must appear after the substring to extract.
In the template
projects/{project}/, the suffix is/.
Theextract() function extracts different parts of the attribute based onwhether the extraction template has a prefix, a suffix, or both:
| Has prefix | Has suffix | Extracted value |
|---|---|---|
| — | — | The entire attribute |
| — | The characters after the first occurrence of the prefix, or an empty string if there are no characters after the prefix | |
| — | The characters before the first occurrence of the suffix, or an empty string if there are no characters before the suffix | |
| The characters between the first occurrence of the prefix and the first subsequent occurrence of the suffix, or an empty string if there are no characters between the prefix and the suffix |
If you specify a prefix or suffix that don't appear in the attribute, or if thesuffix appears only before the prefix, theextract() function returns an emptystring.
The following examples show the output from several different extractiontemplates. These examples refer to a resource name for a Cloud Storageobject,projects/_/buckets/acme-orders-aaa/objects/data_lake/orders/:
| Extraction template | Output |
|---|---|
/order_date={date}/ | 2019-11-03 |
buckets/{name}/ | acme-orders-aaa |
/orders/{empty}order_date | Emptystring |
{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/ |
/orders/{none}/order_date= | Emptystring |
/orders/order_date=2019-11-03/ | Emptystring |
If you extract a string that represents a date, you can use thedate/time functions and operators on this page to convert theextracted value to aTimestamp. For examples, seeConfiguring resource-based access.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.