Searching Resources

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 in Roles.

Calling SearchAllResources

Console

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

1. In the Cloud Console, go to the Asset Inventory page.

   Go to the Asset Inventory page

2. At the top of the Cloud Console window, open Project navigator to change the scope by selecting an organization, folder, or project.

3. On the left panel, check Asset type, Project, or Location to filter the results.

4. The Filter bar on the top of the result table allows specifying a query. Click the input box, a list of searchable fields will be prompted. Multiple fields are supported. Refer to the Query Syntax page for complete details.

5. The search results will be shown in the result table below.

6. Users can see the actual query by clicking VIEW QUERY button, which will show the corresponding gcloud command.

7. The search results can be exported by clicking the DOWNLOAD CSV button.

8. Users can also share the search configuration by click the share button to copy the URL of the current page to clipboard.

gcloud

You can call SearchAllResources using the gcloud asset search-all-resources command. You must be running Cloud SDK 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".
  • 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 or createTime<2021-01-01 or createTime<"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 or updateTime>2021-01-01 or updateTime>"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 contains ImportantName.
  • parentAssetType:Project to find Google Cloud resources whose parent's asset type contains Project.
  • 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" whose name contains the word mycompany:

  gcloud asset search-all-resources \
    --scope='organizations/123456' \
    --query='name:mycompany'
  

• Find all resources in "organizations/123456" whose name contains the word mycompany, 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:

1. 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.

   Don't enter any confidential information on the OAuth consent screen. Any information you save to the OAuth consent screen may be publicly visible for anyone who accesses your URL. Email and product details are displayed on the login screen and when someone tries to access a resource for which they don't have permission.
   1. Go to the OAuth consent screen for your project.
      Configure consent screen
   2. Enter the Application name you want to display.
   3. 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.
   4. Add any optional details you'd like.
   5. Click Save.

2. Create an OAuth token for your project. See Setting up OAuth 2.0 for more information.

   1. Go to the Create OAuth client ID page.
      Create OAuth client
   2. Select Desktop app as your Application type.
   3. Click Create.

3. Download the client_secret.json file.

   1. Go to the Credentials page.
   2. To the right of your new Client ID, click Download JSON.
   3. Securely store the file in a location that only your app can access.

4. 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.

5. Generate an auth token for your account with the following command:

   TOKEN=$(gcloud auth application-default print-access-token)
   

6. 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".
  • 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 or createTime<2021-01-01 or createTime<"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 or updateTime>2021-01-01 or updateTime>"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 contains ImportantName.
  • parentAssetType:Project to find Google Cloud resources whose parent's asset type contains Project.
  • 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 of next_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
  • Client library
  • REST reference
  • RPC reference

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.

  Note: labels as a nested object does not support equals (=) operator.

• 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.

• 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. See lifecycleState 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.

Note: In the search response, there is an additionalAttributes field. To search against this field, you have to use the free text search.

Examples: query by specific field

• Find all resources in your scope whose name contains the word Important:

  name:Important
  

• Find all resources in your scope whose displayName contains a word with prefix prod:

  displayName:prod*
  

• Find all resources in your scope whose location contains the word us:

  location:us
  

• Find all resources in your scope whose location exactly equals us:

  location=us
  

• Find all resources in your scope that have a label where either the key or the value contains the word prod:

  labels:prod
  

• Find all resources in your scope that have a label where the key is env and the value contains the word prod:

  labels.env:prod
  

• Find all resources in your scope that have a label where the key is env and the value exactly equals prod:

  labels.env=prod
  

• Find all resources in your scope that have a label where the key is env:

  labels.env:*
  

• Find all resources in your scope that one of whose networkTags contains the word internal:

  networkTags:internal
  

• Find all resources in your scope that one of whose networkTags exactly equals internal:

  networkTags=internal
  

• Find all resources in your scope encrypted with a customer-managed encryption key whose name contains the word key:

  kmsKey:key
  

• Find all resources in your scope whose state contains the word ACTIVE:

  state:ACTIVE
  

• Find all resources in your scope whose state doesn't contain the word ACTIVE:

  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 whose project has number 123:

  project:123
  

• Find all resources in your scope contained in folder with number 123:

  folders:123
  

• Find all resources in your scope whose organization has number 123:

  organization:123
  

• Find all resources in your scope whose parentFullResourceName contains ImportantName:

  parentFullResourceName:ImportantName
  

• Find all resources in your scope whose parentAssetType contains Project:

  parentAssetType:Project
  

• Find all resources in your scope whose name contains the word Important and description contains a word with the prefix import:

  name:Important description:import*
  

• Find all resources in your scope whose name contains the word Important or description contains a word with the prefix import:

  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 word Important:

  Important
  

• Find all resources in your scope whose metadata fields (e.g., name, displayName, description) contain a word with the prefix import:

  import*
  

• Find all resources in your scope whose metadata fields (e.g., name, displayName, description) contain the word Important and also contain a word with the prefix prod:

  Important prod*