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 Google 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 thecloudasset.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 specifiedscope
.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. This field is deprecated. Please use thekmsKeys
field to retrieve KMS key information.kmsKeys:key
to find Google Cloud resources encrypted with customer-managed encryption keys whose name contains the word "key".relationships:instance-group-1
to find Google Cloud resources that have relationships with "instance-group-1" in the related resource name.relationships:INSTANCE_TO_INSTANCEGROUP
to find Compute Engine instances that have relationships of type "INSTANCE_TO_INSTANCEGROUP".relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
to find Compute Engine instances that have relationships with "instance-group-1" in the Compute Engine instance group resource name, for relationship type "INSTANCE_TO_INSTANCEGROUP".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
createTime
updateTime
state
parentFullResourceName
parentAssetType
All the other fields such as repeated fields (e.g.,
networkTags
,kmsKeys
), 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 to0
, an appropriate default will be selected.(Optional)
READ_MASK
: A comma-separated list of fields that you want returned in the results. The following fields are returned by default if--read-mask
isn't specified:name
assetType
project
folders
organization
displayName
description
location
labels
networkTags
kmsKeys
createTime
updateTime
state
additionalAttributes
parentFullResourceName
parentAssetType
Some fields of large size, such as
versionedResources
andattachedResources
, are not returned by default, but you can specify them in the--read-mask
parameter if you want to include them. If"*"
is specified, all available fields are 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 JSON representation included:gcloud asset search-all-resources \ --scope='organizations/123456' \ --query='name:mycompany' \ --read-mask='name,versionedResources'
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 prompt 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 thecloudasset.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 specifiedscope
.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. This field is deprecated. Please use thekmsKeys
field to retrieve KMS key information.kmsKeys:key
to find Google Cloud resources encrypted with customer-managed encryption keys whose name contains the word "key".relationships:instance-group-1
to find Google Cloud resources that have relationships with "instance-group-1" in the related resource name.relationships:INSTANCE_TO_INSTANCEGROUP
to find Compute Engine instances that have relationships of type "INSTANCE_TO_INSTANCEGROUP".relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
to find Compute Engine instances that have relationships with "instance-group-1" in the Compute Engine instance group resource name, for relationship type "INSTANCE_TO_INSTANCEGROUP".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
createTime
updateTime
state
parentFullResourceName
parentAssetType
All the other fields such as repeated fields (e.g.,
networkTags
,kmsKeys
), 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 to0
, an appropriate default will be selected.(Optional)
PAGE_TOKEN
: The token representing the next batch of results from the preceding call to this method. Thepage_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 that you want returned in the results. The following fields are returned by default ifread_mask
isn't specified:name
assetType
project
folders
organization
displayName
description
location
labels
networkTags
kmsKeys
createTime
updateTime
state
additionalAttributes
parentFullResourceName
parentAssetType
Some fields of large size, such as
versionedResources
andattachedResources
, are not returned by default, but you can specify them in theread_mask
parameter if you want to include them. If"*"
is specified, all available fields are 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 Google Cloud Platform 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 Google Cloud Platform resources.
kmsKey: The customer-managed encryption key used to encrypt this resource. This field is deprecated. Please use the
kmsKeys
field to retrieve KMS key information. See CryptoKey and CryptoKeyVersion.kmsKeys: The customer-managed encryption keys used to encrypt this resource. See CryptoKey and CryptoKeyVersion.
relationships: The relationships associated with this resource. Relationships can match relationship type, related resource name, or both. See Supported relationship types.
relationships.[relationship_type]: The related resource name for a particular resource type associated with this resource. For example: "
relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
". See Supported relationship types.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
that have relationships withinstance-group-1
in the related resource name:relationships:instance-group-1
Find compute instances in your
scope
that have relationships of typeINSTANCE_TO_INSTANCEGROUP
:relationships:INSTANCE_TO_INSTANCEGROUP
Find compute instances in your
scope
that have relationships withinstance-group-1
in the compute instance group resource name, for relationship typeINSTANCE_TO_INSTANCEGROUP
:relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
Find all resources in your
scope
whosekmsKeys
contains the wordkey
:kmsKeys:key
Find all resources in your
scope
whosekmsKeys
exactly equalskey
:kmsKeys=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
:folder: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 specifying 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*