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.
Before you begin
gcloud
- 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 - Install the Cloud SDK on your local client.
API
- Install oauth2l on your local machine for interacting with the Google OAuth system.
- Confirm that you have access to the Unix
curl
command. - 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).
- Ensure that you can call the Cloud Asset API by going through the Configure an account step.
- Determine the resource types of the assets you want to list. This is the asset-types variable in the examples below.
- 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.
- Ensure that you can call the Cloud Asset API by going through the Configure an account step.
- Determine the time you want to list the assets at. This is the readTime parameter in the following command, in RFC 3339 UTC format.
- 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