The Cloud Asset API allows you to use a custom query language to query resource metadata on a project, folder, or organization.
Before you begin
- Enable the Cloud Asset API for your project.
- Grant the
cloudasset.assets.searchAllResources
permission to the user account or service account that is making the request. This permission is included in basic roles and predefined roles listed inRoles
.
Search resources
Console
To search all resources, complete the following steps.
Go to the Asset Inventory page in the Cloud console.
Go to the Asset Inventory pageTo set the scope of your search, open the Projects list box in the menu bar, and then select the organization, folder, or project to query.
Select the Resource tab.
To search resources, enter the query text in the Filter bar. Select the text box, and then a list of searchable fields display. Resource search supports multiple fields. Learn more about Query Syntax.
Search results can also be filtered by the pre-defined Asset type, Project, and Location filters in the Filter results pane.
The resources matching the query are listed in the Result table.
To view the query as a Google Cloud CLI command, select View query.
To export the results, select Download CSV.
gcloud
You can call SearchAllResources
using the
gcloud asset search-all-resources
command. You must be running Google Cloud CLI version 302.0.0 or newer. You can
check your version with the gcloud version
command.
gcloud asset search-all-resources \ --scope=SCOPE \ --query=QUERY \ --asset-types=ASSET_TYPES,… \ --order-by=ORDER_BY \ --page-size=PAGE_SIZE \ --read-mask=READ_MASK
Where all of the following flags are optional:
(Optional) SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the Google Cloud resources within this scope. The caller must be granted the
cloudasset.assets.searchAllResources
permission on the desired scope. If not specified, the configured project property will be used. To find the configured project, run:gcloud config get-value project
. To change the setting, run:gcloud config set project PROJECT_ID
.The allowed values are:
projects/PROJECT_ID
(e.g., "projects/foo-bar
")projects/PROJECT_NUMBER
(e.g., "projects/12345678
")folders/FOLDER_NUMBER
(e.g., "folders/1234567
")organizations/ORGANIZATION_NUMBER
(e.g., "organizations/123456
")
(Optional) QUERY: The query statement. See how to construct a query for more information. If not specified or empty, it will search all the resources within the specified
scope
.Examples:
name:Important
to find Google Cloud resources whose name contains the word "Important".name=Important
to find the Google Cloud resource whose name is exactly "Important".displayName:Impor*
to find Google Cloud resources whose display name contains "Impor" as a prefix of any word.location:us-west*
to find Google Cloud resources whose location has two words with "us" and "west" as prefixes.labels:prod
to find Google Cloud resources that have a label where either the key or the value contains the word "prod".labels.env:prod
to find Google Cloud resources that have a label where the key is "env" and the value contains the word "prod".labels.env:*
to find Google Cloud resources that have a label where the key is "env".tagKeys:env
to find Google Cloud resources that are directly attached to Tags where theTagKey
.namespacedName
contains "env".tagValues:prod*
to find Google Cloud resources that are directly attached to Tags where theTagValue
.namespacedName
contains a word prefixed by "prod".tagValueIds=tagValues/123
to find Google Cloud resources that are directly attached to Tags where theTagValue
.name
is exactly "tagValues/123".kmsKey:key
to find Google Cloud resources encrypted with a customer-managed encryption key whose name contains "key" as a word.state:ACTIVE
to find Google Cloud resources whose state contains "ACTIVE" as a word.NOT state:ACTIVE
to find Google Cloud resources whose state doesn't contain "ACTIVE" as a word.createTime<1609459200
orcreateTime<2021-01-01
orcreateTime<"2021-01-01T00:00:00"
to find Google Cloud resources that were created before "2021-01-01 00:00:00 UTC". 1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC".updateTime>1609459200
orupdateTime>2021-01-01
orupdateTime>"2021-01-01T00:00:00"
to find Google Cloud resources that were updated after "2021-01-01 00:00:00 UTC". 1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC".project:12345
to find Google Cloud resources that belong to a Google Cloud project with number 12345.folders:(123 or 456)
to find Google Cloud resources that belong to a Google Cloud folder with numbers 123 or 456.organization:123
to find Google Cloud resources that belong to a Google Cloud organization with number 123.parentFullResourceName:ImportantName
to find Google Cloud resources whose parent's name containsImportantName
.parentAssetType:Project
to find Google Cloud resources whose parent's asset type containsProject
.Important
to find Google Cloud resources that contain the word "Important" in any of the searchable fields.Impor*
to find Google Cloud resources that contain "Impor" as a prefix of any word in any of the searchable fields.Important location:(us-west1 OR global)
to find Google Cloud resources that contain the word "Important" in any of the searchable fields and are also located in the "us-west1" region or the "global" location.
(Optional) ASSET_TYPES: A list of asset types that this request searches for. If empty, it will search all the searchable asset types. Regular expressions are also supported. For example:
"compute.googleapis.com.*"
snapshots resources whose asset type starts with"compute.googleapis.com"
.".*Instance"
snapshots resources whose asset type ends with"Instance"
.".*Instance.*"
snapshots resources whose asset type contains"Instance"
.
See RE2 for all supported regular expression syntax. If the regular expression does not match any supported asset type, an
INVALID_ARGUMENT
error will be returned.(Optional) ORDER_BY: A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add
" DESC"
after the field name to indicate descending order. Redundant space characters are ignored. Example:"location DESC, name"
. Only singular primitive fields in the response are sortable:name
assetType
project
displayName
description
location
kmsKey
createTime
updateTime
state
parentFullResourceName
parentAssetType
All the other fields such as repeated fields (e.g.,
networkTags
), map fields (e.g.,labels
) and struct fields (e.g.,additionalAttributes
) are not supported.(Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 500. If the value is set to
0
, an appropriate default will be selected.(Optional) READ_MASK: A comma-separated list of fields specifying which fields to be returned in the results. If not specified, all fields except
versionedResources
will be returned. If only"*"
is specified, all fields will be returned. Examples:"name,location"
,"name,versionedResources"
,"*"
.
The following are examples gcloud
commands:
Find all resources in "
organizations/123456
" whosename
contains the wordmycompany
:gcloud asset search-all-resources \ --scope='organizations/123456' \ --query='name:mycompany'
Find all resources in "
organizations/123456
" whosename
contains the wordmycompany
, with full metadata included:gcloud asset search-all-resources \ --scope='organizations/123456' \ --query='name:mycompany' \ --read-mask='*'
api
You can call SearchAllResources
using a valid OAuth token for a project.
To call the SearchAllResources
method from Cloud Shell or any
console where the gcloud
command is available:
If you haven't configured your project's OAuth consent screen, you'll need to do so. An email address and product name are required for the OAuth consent screen.
- Go to the OAuth consent screen
for your project.
Configure consent screen - Enter the Application name you want to display.
- Under Support email, select the email address you want to display as a public contact. This must be your email address, or a Google Group you own.
- Add any optional details you'd like.
- Click Save.
- Go to the OAuth consent screen
for your project.
Create an OAuth token for your project. See Setting up OAuth 2.0 for more information.
- Go to the Create OAuth client ID page.
Create OAuth client - Select Desktop app as your Application type.
- Click Create.
- Go to the Create OAuth client ID page.
Download the
client_secret.json
file.- Go to the Credentials page.
- To the right of your new Client ID, click Download JSON.
- Securely store the file in a location that only your app can access.
Log in using the JSON file with the following command.
gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
Note that this command will prompot you to open a link. Make sure the page shows the Application name you set in your OAuth consent screen.
Generate an auth token for your account with the following command:
TOKEN=$(gcloud auth application-default print-access-token)
You can now query resources using
curl
commands.PAGE_SIZE=PAGE_SIZE PAGE_TOKEN="PAGE_TOKEN" SCOPE="SCOPE" QUERY="QUERY" ASSET_TYPES="ASSET_TYPES,…" ORDER_BY="ORDER_BY" READ_MASK="READ_MASK" curl -s -G \ -H "Authorization: Bearer $TOKEN" \ -d "page_size=$PAGE_SIZE" \ -d "page_token=$PAGE_TOKEN" \ -d "scope=$SCOPE" \ -d "asset_types=$ASSET_TYPES" \ -d "order_by=$ORDER_BY" \ -d "read_mask=$READ_MASK" \ --data-urlencode "query=$QUERY" \ "https://cloudasset.googleapis.com/v1/$SCOPE:searchAllResources"
Where all of the following flags are optional:
SCOPE: is required. A scope can be a project, a folder, or an organization. The search is limited to the Google Cloud resources within this scope. The caller must be granted the
cloudasset.assets.searchAllResources
permission on the desired scope.The allowed values are:
projects/PROJECT_ID
(e.g., "projects/foo-bar
")projects/PROJECT_NUMBER
(e.g., "projects/12345678
")folders/FOLDER_NUMBER
(e.g., "folders/1234567
")organizations/ORGANIZATION_NUMBER
(e.g., "organizations/123456
")
(Optional) QUERY: The query statement. See how to construct a query for more information. If not specified or empty, it will search all the resources within the specified
scope
.Examples:
name:Important
to find Google Cloud resources whose name contains the word "Important".name=Important
to find the Google Cloud resource whose name is exactly "Important".displayName:Impor*
to find Google Cloud resources whose display name contains "Impor" as a prefix of any word.location:us-west*
to find Google Cloud resources whose location contains both "us" and "west" as prefixes.labels:prod
to find Google Cloud resources that have a label where either the key or the value contains the word "prod".labels.env:prod
to find Google Cloud resources that have a label where the key is "env" and the value contains the word "prod".labels.env:*
to find Google Cloud resources that have a label where the key is "env".tagKeys:env
to find Google Cloud resources that are directly attached to Tags where theTagKey
.namespacedName
contains "env".tagValues:prod*
to find Google Cloud resources that are directly attached to Tags where theTagValue
.namespacedName
contains a word prefixed by "prod".tagValueIds=tagValues/123
to find Google Cloud resources that are directly attached to Tags where theTagValue
.name
is exactly "tagValues/123".kmsKey:key
to find Google Cloud resources encrypted with a customer-managed encryption key whose name contains "key" as a word.state:ACTIVE
to find Google Cloud resources whose state contains "ACTIVE" as a word.NOT state:ACTIVE
to find Google Cloud resources whose state doesn't contain "ACTIVE" as a word.createTime<1609459200
orcreateTime<2021-01-01
orcreateTime<"2021-01-01T00:00:00"
to find Google Cloud resources that were created before "2021-01-01 00:00:00 UTC". 1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC".updateTime>1609459200
orupdateTime>2021-01-01
orupdateTime>"2021-01-01T00:00:00"
to find Google Cloud resources that were updated after "2021-01-01 00:00:00 UTC". 1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC".project:12345
to find Google Cloud resources that belong to a Google Cloud project with number 12345.folders:(123 or 456)
to find Google Cloud resources that belong to a Google Cloud folder with numbers 123 or 456.organization:123
to find Google Cloud resources that belong to a Google Cloud organization with number 123.parentFullResourceName:ImportantName
to find Google Cloud resources whose parent's name containsImportantName
.parentAssetType:Project
to find Google Cloud resources whose parent's asset type containsProject
.Important
to find Google Cloud resources that contain the word "Important" in any of the searchable fields.Impor*
to find Google Cloud resources that contain "Impor" as a prefix of any word in any of the searchable fields.Important location:(us-west1 OR global)
to find Google Cloud resources that contain the word "Important" in any of the searchable fields and are also located in the "us-west1" region or the "global" location.
(Optional) ASSET_TYPES: A list of asset types that this request searches for. If empty, it will search all the searchable asset types. Regular expressions are also supported. For example:
"compute.googleapis.com.*"
snapshots resources whose asset type starts with"compute.googleapis.com"
.".*Instance"
snapshots resources whose asset type ends with"Instance"
.".*Instance.*"
snapshots resources whose asset type contains"Instance"
.
See RE2 for all supported regular expression syntax. If the regular expression does not match any supported asset type, an
INVALID_ARGUMENT
error will be returned.(Optional) ORDER_BY: A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add
" DESC"
after the field name to indicate descending order. Redundant space characters are ignored. Example:"location DESC, name"
. Only singular primitive fields in the response are sortable:name
assetType
project
displayName
description
location
kmsKey
createTime
updateTime
state
parentFullResourceName
parentAssetType
All the other fields such as repeated fields (e.g.,
networkTags
), map fields (e.g.,labels
) and struct fields (e.g.,additionalAttributes
) are not supported.(Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 500. If the value is set to
0
, an appropriate default will be selected.(Optional) PAGE_TOKEN: The token representing the next batch of results from the preceding call to this method. The
page_token
must be the same as the value ofnext_page_token
from the preceding call's response.(Optional) READ_MASK: A comma-separated list of fields specifying which fields to be returned in the results. If not specified, all fields except
versionedResources
will be returned. If only"*"
is specified, all fields will be returned. Examples:"name,location"
,"name,versionedResources"
,"*"
.
Client library and API reference
- SearchAllResources
How to construct a query
See query syntax to learn more about the query language.
See searching resources samples to learn more about the sample queries for various real use cases.
Query Google Cloud resources by resource metadata fields
To search resource metadata, a query expression is in the following formats:
- Text Exact Match:
FIELD=QUERY
- Text Partial Match:
FIELD:QUERY
- Numerical Match: comparison operators (
=
,>
,>=
,<
,<=
)FIELDcomparison operatorQUERY
A searchable resource metadata FIELD can be:
- name: The full resource name of the resource. Note: Not all the asset types are searchable. See the list of searchable types.
- displayName: The display name on the UI
- description: The text description of the resource in one or more paragraphs
- location: The location of the resource. Location can be "global", regional (e.g. "us-east1"), or zonal (e.g. "us-west1-b").
labels: Labels associated with this resource. Labels can match label keys, label values, or both. See Labelling and grouping GCP resources.
labels.[key]: Label value identified by the label key associated with this resource. For example: "
labels.env:prod
". Only hyphens (-
), underscores (_
), lowercase characters, and numbers are allowed in labels keys. Keys must start with a lowercase character. International characters are allowed. See Labels Requirements.tagKeys:
TagKey
.namespacedName
of the Tags directly attached to this resource.tagValues:
TagValue
.namespacedName
of the Tags directly attached to this resource.tagValueIds:
TagValue
.name
of the Tags directly attached to this resource.networkTags: Network tags associated with this resource. See Labelling and grouping GCP resources.
kmsKey: The customer-managed encryption key used to encrypt this resource. See CryptoKey and CryptoKeyVersion.
state: The text value of the state of this resource. Different resource types have different state definitions that are mapped from various fields of different resource types. Example: If the resource is an instance provided by Compute Engine, its state will include PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING, and TERMINATED. See
status
definition in API Reference. If the resource is a project provided by Cloud Resource Manager, its state will include LIFECYCLE_STATE_UNSPECIFIED, ACTIVE, DELETE_REQUESTED and DELETE_IN_PROGRESS. SeelifecycleState
definition in API Reference.createTime: The create timestamp of this resource, at which the resource was created. The granularity is in seconds.
updateTime: The last update timestamp of this resource, at which the resource was last modified or deleted. The granularity is in seconds.
project: The number of the project that this resource belongs to.
folders: The numbers of the folders that this resource belongs to.
organization: The number of the organization that this resource belongs to.
parentFullResourceName: The name of the parent of this resource.
parentAssetType: The type of the parent of this resource.
Examples: query by specific field
Find all resources in your
scope
whosename
contains the wordImportant
:name:Important
Find all resources in your
scope
whosedisplayName
contains a word with prefixprod
:displayName:prod*
Find all resources in your
scope
whoselocation
contains the wordus
:location:us
Find all resources in your
scope
whoselocation
exactly equalsus
:location=us
Find all resources in your
scope
that have directly attached Tags withTagKey
namespacedName
containing the wordenv
:tagKeys:env
Find all resources in your
scope
that have directly attached Tags withTagValue
.namespacedName
containing a word prefixed byprod
:tagValues:prod*
Find all resources in your
scope
that have a directly attached Tags withTagValue
.name
exactly equal totagValues/123
:tagValueIds=tagValues/123
Find all resources in your
scope
that have a directly attached Tags withTagValue
.namespacedName
, i.e. all resources that have directly attached Tags:tagValues:*
Find all resources in your
scope
that have alabel
where either the key or the value contains the wordprod
:labels:prod
Find all resources in your
scope
that have alabel
where the key isenv
and the value contains the wordprod
:labels.env:prod
Find all resources in your
scope
that have alabel
where the key isenv
and the value exactly equalsprod
:labels.env=prod
Find all resources in your
scope
that have alabel
where the key isenv
:labels.env:*
Find all resources in your
scope
that one of whosenetworkTags
contains the wordinternal
:networkTags:internal
Find all resources in your
scope
that one of whosenetworkTags
exactly equalsinternal
:networkTags=internal
Find all resources in your
scope
encrypted with a customer-managed encryption key whose name contains the wordkey
:kmsKey:key
Find all resources in your
scope
whosestate
contains the wordACTIVE
:state:ACTIVE
Find all resources in your
scope
whosestate
doesn't contain the wordACTIVE
:NOT state:ACTIVE
Find all resources in your
scope
that were created before "2021-01-01 00:00:00 UTC" (1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC"):createTime<1609459200 createTime<2021-01-01 createTime<"2021-01-01T00:00:00"
Find all resources in your
scope
that were updated after "2021-01-01 00:00:00 UTC" (1609459200 is the epoch timestamp in seconds of "2021-01-01 00:00:00 UTC"):updateTime>1609459200 updateTime>2021-01-01 updateTime>"2021-01-01T00:00:00"
Find all resources in your
scope
whoseproject
has number123
:project:123
Find all resources in your
scope
contained infolder
with number123
:folders:123
Find all resources in your
scope
whoseorganization
has number123
:organization:123
Find all resources in your
scope
whoseparentFullResourceName
containsImportantName
:parentFullResourceName:ImportantName
Find all resources in your
scope
whoseparentAssetType
containsProject
:parentAssetType:Project
Find all resources in your
scope
whosename
contains the wordImportant
anddescription
contains a word with the prefiximport
:name:Important description:import*
Find all resources in your
scope
whosename
contains the wordImportant
ordescription
contains a word with the prefiximport
:name:Important OR description:import*
Query Google Cloud resources by free text
You can also simply use a free text query without specifing a field. Then it will return resources, as long as there is a field in the resource metadata matching the query.
Examples: query by free text
Find all resources in your
scope
whose metadata fields (e.g.,name
,displayName
,description
) contain the wordImportant
:Important
Find all resources in your
scope
whose metadata fields (e.g.,name
,displayName
,description
) contain a word with the prefiximport
:import*
Find all resources in your
scope
whose metadata fields (e.g.,name
,displayName
,description
) contain the wordImportant
and also contain a word with the prefixprod
:Important prod*