Listing assets

Beta

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.

This page shows you how to use the Cloud Asset Inventory asset list service. You can use the Cloud Asset Inventory API to view a paginated list of the assets at a given timestamp.

Note: Listing assets might not meet the performance requirements for large scale customers. If this is the case for you and calling list API encounters timeout, it's recommended to use export API instead.

Before you begin

gcloud

1. Enable the Cloud Asset API before you can use the gcloud command-line tool to access Cloud Asset Inventory. Note that the API only needs to be enabled on the project you'll be running Cloud Asset API commands from.
   Enable the Cloud Asset Inventory API
2. Install the Cloud SDK on your local client.

API

1. Install oauth2l on your local machine for interacting with the Google OAuth system.
2. Confirm that you have access to the Unix curl command.
3. Ensure that your account has one of the following roles on your project or organization of which you are going to list assets.
   • roles/cloudasset.viewer
   • roles/cloudasset.owner

Configure an account

To call the Cloud Asset API, your account must be granted the cloudasset.assets.listResource permission to list resources or cloudasset.assets.listIamPolicy to list IAM policies on the root (parent) resource, which is a project or organization that contains assets you want to list.

If your account has been granted the Cloud Asset Viewer (roles/cloudasset.viewer) role, or the Cloud Asset Owner (roles/cloudasset.owner) role, or the Owner (roles/owner) basic role on the resource root, it already has sufficient permissions to call Cloud Asset API. Otherwise, follow the steps on the Configuring Permissions page.

List assets

To list the assets in a project within a given timeframe using the Cloud Asset API, follow the steps below.

gcloud

The commands shown in this section list assets in a project. To list assets in an organization, use the --organization=ORGANIZATION_ID flag in your command.

The following example lists assets within a project.

Note that the latest possible start-time of a timeframe is current time minus 35 days (inclusive).

1. Ensure that you can call the Cloud Asset API by going through the Configure an account step.
2. Determine the resource types of the assets you want to list. This is the asset-types variable in the examples below.
3. Determine the time you want to list the assets at. This is the snapshot-time in the gcloud command, in RFC 3339 UTC format.

Note that you can specify the billing project with the flag --billing-project, which is the project you use to send the request. You can specify the target project you want to list with flag --project when you are listing assets from a project.

To see a full list of flags and options, run gcloud alpha asset list --help.

List the assets in a project, including all resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud beta asset list --project='PROJECT_ID' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW \
  --content-type='resource'

List the assets in a project, without resource metadata:

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud beta asset list --project='PROJECT_ID' \
  --billing-project='BILLING_PROJECT_ID' \
  --asset-types='compute.googleapis.com/Instance' \
  --snapshot-time=$NOW

API

The commands shown in this section lists assets of a project. To list assets of an organization, use the https://cloudasset.googleapis.com/v1p5beta1/organizations/ORGANIZATION_NUMBER/assets REST method in the gcurl command.

1. Ensure that you can call the Cloud Asset API by going through the Configure an account step.
2. Determine the time you want to list the assets at. This is the readTime parameter in the following command, in RFC 3339 UTC format.
3. Determine the resource types of the asset you want to list. The following example uses compute.googleapis.com/Instance.

Set Token Var

To get the access token, run the following command with the ~/credentials.json file.

oauth2l header --json ~/credentials.json cloud-platform

You should see an output similar to the following, with y29.xxxxxx as the access token:

Authorization: Bearer y29.xxxxxxx

Set the Token var to the access token:

Token=y29.xxxxxxx

List assets in a project, including all resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request. Note that pageToken is different from Token mentioned above.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $Token" -H "Content-Type: application/json" \
     -d '{"contentType":"RESOURCE", \
          "assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1p5beta1/projects/PROJECT_NUMBER/assets

List assets in a project, without resource metadata

The pageToken parameter must not be set for the first page, and must be set to the page token value in response of previous page request.

NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $Token" -H "Content-Type: application/json" \
     -d '{"assetTypes": "compute.googleapis.com/Instance", \
          "readTime": "'$NOW'", \
          "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \
     https://cloudasset.googleapis.com/v1p5beta1/projects/PROJECT_NUMBER/assets

API reference

• REST reference
• RPC reference