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 primitive roles and predefined roles listed in Roles.

Calling `SearchAllResources`

gcloud

You can call SearchAllResources using the gcloud asset search-all-resources command. You must be running Cloud SDK version 278.0.0 or newer. You can check your version with the gcloud version command.

gcloud beta asset search-all-resources \
  --scope=SCOPE \
  --query=QUERY \
  --asset-types=ASSET_TYPES \
  --page-size=PAGE_SIZE \
  --page-token=PAGE_TOKEN

Where all of the following flags are optional:

(Optional) SCOPE: The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllResources permission granted to the caller for the desired scope. The default value is your configured project property. The allowed values are:
- projects/PROJECT_ID (e.g., "projects/foo")
- projects/PROJECT_NUMBER (e.g., "projects/12345")
- folders/FOLDER_NUMBER (e.g., "folders/1234")
- organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
(Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
- "foo" to find resources whose metadata contains "foo" as a substring.
- "name : foo" to find resources whose names contain "foo" as a word.
(Optional) ASSET_TYPES: The asset type of the returned resources. The default value is all the searchable types An example:
- "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance" to search project and VM instance resources.
(Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 2000. 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.

The following are example gcloud commands:

Find all resources in "organization/123" whose name contains the word mycompany:

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

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.

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.
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 Other as your Application type.
3. Click Create.
Download the client_secret.json file.
1. Go to the Credentials page.
2. To the right of your new Client ID, click Download JSON. file_download
3. 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"
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" \
   --data-urlencode "query=$QUERY" \
   "https://cloudasset.googleapis.com/v1p1beta1/resources:search"

Where all of the following flags are optional:

SCOPE is required. The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllResources permission granted to the caller for the desired scope. The allowed values are:
- projects/PROJECT_ID (e.g., "projects/foo")
- projects/PROJECT_NUMBER (e.g., "projects/12345")
- folders/FOLDER_NUMBER (e.g., "folders/1234")
- organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
(Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
- "foo" to find resources whose metadata contains "foo" as a substring.
- "name : foo" to find resources whose names contain "foo" as a word.
(Optional) ASSET_TYPES: The asset type of the returned resources. The default value is all the searchable types An example:
- "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance" to search project and VM instance resources.
(Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 2000. 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.

Client library and API reference

SearchAllResources

How to construct a query

See query syntax to learn more about the query language.

Query on resource metadata fields

To search resource metadata, a query expression will be in the following format:

FIELD : QUERY

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.
networkTags: Network tags associated with this resource. See Labelling and grouping GCP resources.

Examples: query on specified fields

Find all resources in your scope whose name contains Important as a word:
```
name : "Important"
```
Find all resources in your scope whose displayName starts with prod as a prefix:
```
displayName : "prod*"
```
Find all resources in your scope whose description contains a word containing rtant as a substring:
```
description : "*rtant*"
```
Find all resources in your scope whose location contains us as a word:
```
location : "us"
```
Find all resources in your scope that one of whose labels has key or value contains prod as a word:
```
labels : "prod"
```
Find all resources in your scope that one of whose labels has "env" as key and has value containing prod as a word:
```
labels.env : "prod"
```
Find all resources in your scope that one of whose labels has "env" as key and has any value:
```
labels.env : *
```
Find all resources in your scope that one of whose networkTags contains internal as a word:
```
networkTags : "internal"
```
Find all resources in your scope whose name contains Important as a word and description contains a word containing rtant as a substring:
```
name : "Important" AND description : "*rtant*"
```
Find all resources in your scope whose name contains Important as a word or description contains a word containing rtant as a substring:
```
name : "Important" OR description : "*rtant*"
```
Find all resources in your scope whose name contains Important as a word and doesn't contain *test* as a substring:
```
name : ("Important" AND (NOT "*test*"))
```

Query on any fields

You can also simply use a freetext 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 on any fields

Find all resources in your scope whose metadata fields (name, displayName, description, etc.) contain Important as a word:
```
"Important"
```
Find all resources in your scope whose metadata fields (name, displayName, description, etc.) contain rtant as a substring:
```
"*rtant*"
```
Find all resources in your scope whose metadata fields (name, displayName, description, etc.) contain Important as a word and also contain rtant as a substring:
```
"Important" AND "*rtant*"
```