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
- Enable the Cloud Asset API before you can use the Google Cloud CLI 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 Google Cloud CLI on your local client.
- 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 corresponding permission on the root (parent) resource, which is a project or organization that contains assets you want to list. Below is the required permission for each ContentType in the request:
- CONTENT_TYPE_UNSPECIFIED: cloudasset.assets.listResource
- RESOURCE: cloudasset.assets.listResource
- IAM_POLICY: cloudasset.assets.listIamPolicy
- ORG_POLICY: cloudasset.assets.listOrgPolicy
- ACCESS_POLICY: cloudasset.assets.listAccessPolicy
- OS_INVENTORY: cloudasset.assets.listOSInventories
- RELATIONSHIP: cloudasset.assets.listResource
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 earliest possible snapshot-time
is the current time minus
35 days.
- 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 content type you want to list. This is the
content-type
variable in the examples below. - Determine the time you want to list the assets at. This is the
snapshot-time
in thegcloud
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, or specify the target organization
with flag --organization
, or specify the target folder with flag
--folder
.
To see a full list of flags and options, run gcloud asset list
--help
.
List the assets in a project, including all resource metadata:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud 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 asset list --project='PROJECT_ID' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW
List the assets in an organization, including all resource metadata:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --organization='ORGANIZATION_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW \ --content-type='resource'
List the assets in an organization, without resource metadata:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --organization='ORGANIZATION_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW
List the assets in a folder, including all resource metadata:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --folder='FOLDER_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW \ --content-type='resource'
List the assets in a folder, without resource metadata:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --folder='FOLDER_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW
List all relationships in a project:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --folder='FOLDER_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --asset-types='compute.googleapis.com/Instance' \ --snapshot-time=$NOW \ --content-type='relationship'
List specified relationships in a project:
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset list --folder='FOLDER_NUMBER' \ --billing-project='BILLING_PROJECT_ID' \ --content-type='relationship'\ --relationship-types='INSTANCE_TO_INSTANCEGROUP'\ --snapshot-time=$NOW
API
The commands shown in this section list assets of a project, organization, or folder.
- 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
. - Determine the content type you want to list. This is the
contentType
variable in the examples below.
These examples use Application Default Credentials to authenticate to the Cloud Asset API.
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.
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-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/v1/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 $(gcloud auth print-access-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/v1/projects/PROJECT_NUMBER/assets
List assets in an organization, 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.
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-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/v1/organizations/ORGANIZATION_NUMBER/assets
List assets in an organization, 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 $(gcloud auth print-access-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/v1/ogranizations/ORGANIZATION_NUMBER/assets
List assets in a folder, 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.
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-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/v1/folders/FOLDER_NUMBER/assets
List assets in a folder, 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 $(gcloud auth print-access-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/v1/folders/FOLDER_NUMBER/assets
List all relationships in a project
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 $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"RELATIONSHIP", \ "assetTypes": "compute.googleapis.com/Instance", \ "readTime": "'$NOW'", \ "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets
List specified relationships in a project
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 $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"RELATIONSHIP", \ "relationshipTypes":"INSTANCE_TO_INSTANCEGROUP", \ "readTime": "'$NOW'", \ "pageToken": "PAGE_TOKEN_FROM_PREVIOUS_PAGE_RESPONSE"}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/assets