借助 Cloud Asset API,您可以使用自定义查询语言来查询项目、文件夹或组织的资源元数据。
准备工作
- 为您的项目启用 Cloud Asset API。
- 向发出请求的用户帐号或服务帐号授予
cloudasset.assets.searchAllResources
权限。Roles
中列出的基本角色和预定义角色中包含此权限。
搜索资源
控制台
如需搜索所有资源,请完成以下步骤。
转到控制台中的 Asset Inventory 页面。
转到“Asset Inventory”页面要设置搜索范围,请打开菜单栏中的“项目”列表框,然后选择要查询的组织、文件夹或项目。
选择资源标签页。
如需搜索资源,请在过滤条件栏中输入查询文本。选择文本框,随即会显示可搜索字段的列表。资源搜索支持多个字段。详细了解查询语法。
搜索结果也可以按过滤结果窗格中预定义的资源类型、项目和位置过滤条件进行过滤。
结果表中会列出与查询匹配的资源。
如需以 Google Cloud CLI 命令的形式来查看查询,请选择查看查询。
如需导出结果,请选择下载 CSV。
gcloud
您可以使用 gcloud asset search-all-resources
命令调用 SearchAllResources
。您必须运行 Google Cloud CLI 302.0.0 或更新版本。您可以使用 gcloud version
命令检查您的版本。
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
以下所有标志都是可选的:
(可选)SCOPE:范围可以是项目、文件夹或组织。只搜索此范围内的 Google Cloud 资源。调用者必须被授予所需范围的
cloudasset.assets.searchAllResources
权限。如果未指定,将使用已配置的项目属性。如需查找已配置的项目,请运行gcloud config get-value project
。如需更改此设置,请运行gcloud config set project PROJECT_ID
。允许使用的值包括:
projects/PROJECT_ID
(例如,“projects/foo-bar
”)projects/PROJECT_NUMBER
(例如,“projects/12345678
”)folders/FOLDER_NUMBER
(例如,“folders/1234567
”)organizations/ORGANIZATION_NUMBER
(例如,“organizations/123456
”)
(可选)QUERY:查询语句。如需了解详情,请参阅如何构建查询。如果未指定或为空,它将搜索指定
scope
中的所有资源。示例:
name:Important
,查找名称包含“Important”一词的 Google Cloud 资源。name=Important
,查找名称正好为“Important”的 Google Cloud 资源。displayName:Impor*
,以查找显示名包含“Impor”作为任何词前缀的 Google Cloud 资源。location:us-west*
,用于查找位置包含两个字词且以“us”和“west”作为前缀的 Google Cloud 资源。labels:prod
,查找所含标签的键或值包含“prod”一词的 Google Cloud 资源。labels.env:prod
,查找所含标签的键为“env”且值包含“prod”的 Google Cloud 资源。labels.env:*
,查找所含标签的键为“env”的 Google Cloud 资源。tagKeys:env
:用于查找与TagKey
中的标记直接关联的 Google Cloud 资源。namespacedName
包含“env”。tagValues:prod*
:用于查找与TagValue
中的标记直接关联的 Google Cloud 资源。namespacedName
包含一个以 "prod" 为前缀的字词。tagValueIds=tagValues/123
:用于查找与TagValue
中的标记直接关联的 Google Cloud 资源。name
正好是“tagValues/123”。kmsKey:key
,查找使用名称包含“key”这个词、由客户管理的加密密钥加密的 Google Cloud 资源。relationships:instance-group-1
,用于在相关资源名称中查找与“instance-group-1”存在关系的 Google Cloud 资源。relationships:INSTANCE_TO_INSTANCEGROUP
:用于查找类型为“INSTANCE_TO_INSTANCEGROUP”的 Compute Engine 实例。relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
。state:ACTIVE
,查找状态包含“ACTIVE”这个词的 Google Cloud 资源。NOT state:ACTIVE
,查找状态包含“ACTIVE”这个词的 Google Cloud 资源。createTime<1609459200
或createTime<2021-01-01
或createTime<"2021-01-01T00:00:00"
,查找在“2021-01-01 00:00:00 UTC”之前创建的 Google Cloud 资源。1609459200 是“2021-01-01 00:00:00 UTC”的纪元时间戳。updateTime>1609459200
或updateTime>2021-01-01
或updateTime>"2021-01-01T00:00:00"
,查找在“2021-01-01 00:00:00 UTC”后更新的 Google Cloud 资源。1609459200 是“2021-01-01 00:00:00 UTC”的纪元时间戳。project:12345
,查找属于编号为 12345 的 Google Cloud 项目的 Google Cloud 资源。folders:(123 or 456)
,查找属于编号为 123 或 456 的 Google Cloud 文件夹的 Google Cloud 资源。organization:123
,查找属于编号为 123 的 Google Cloud 组织的 Google Cloud 资源。parentFullResourceName:ImportantName
,查找其父级名称中包含ImportantName
的 Google Cloud 资源。parentAssetType:Project
,查找其父级资产类型包含Project
的 Google Cloud 资源。Important
,查找任何可搜索字段中包含一词“Important”的 Google Cloud 资源。Impor*
,以查找包含以“Impr”作为任何可搜索字段中任何词前缀的 Google Cloud 资源。Important location:(us-west1 OR global)
,查找任何可搜索字段中包含一词“Important”且还位于“us-west1”区域或“全局”位置的 Google Cloud 资源。
(可选)ASSET_TYPES:此请求搜索的资产类型列表。如果为空,它将搜索所有可搜索的资产类型。此外,还支持正则表达式。例如:
"compute.googleapis.com.*"
是资产类型以"compute.googleapis.com"
开头的资源的快照。".*Instance"
快照,其资产类型以"Instance"
结尾的资源。- 其资产类型包含
"Instance"
的".*Instance.*"
快照资源。
如需查看所有支持的正则表达式语法,请参阅 RE2。如果正则表达式与任何支持的资产类型均不匹配,则将返回
INVALID_ARGUMENT
错误。(可选)ORDER_BY:指定结果排序顺序的以逗号分隔的字段列表。默认顺序是升序。在字段名称后添加
" DESC"
可指示降序顺序。多余空格会被忽略。示例:"location DESC, name"
。响应中只有单一原始字段是可排序的:name
assetType
project
displayName
description
location
kmsKey
createTime
updateTime
state
parentFullResourceName
parentAssetType
其他所有字段,例如重复字段(例如,
networkTags
),映射字段(例如labels
)和结构体字段(例如,additionalAttributes
)。(可选)PAGE_SIZE:搜索结果分页的页面大小。最大值是 500。如果该值设为
0
,将选择相应默认值。(可选)READ_MASK:用于指定要在结果中返回的字段的英文逗号分隔列表。如果未指定此参数,则系统将返回
versionedResources
以外的所有字段。如果仅指定了"*"
,则返回所有字段。示例:"name,location"
、"name,versionedResources"
、"*"
。
以下是一些示例 gcloud
命令:
查找“
organizations/123456
”中name
包含mycompany
一词的所有资源:gcloud asset search-all-resources \ --scope='organizations/123456' \ --query='name:mycompany'
查找“
organizations/123456
”中name
包含mycompany
一词的所有资源(包含完整元数据):gcloud asset search-all-resources \ --scope='organizations/123456' \ --query='name:mycompany' \ --read-mask='*'
api
您可以使用项目的有效 OAuth 令牌调用 SearchAllResources
。要从 Cloud Shell 或可使用 gcloud
命令的任何控制台调用 SearchAllResources
方法,请执行以下操作:
如果您尚未配置项目的 OAuth 同意屏幕,则需要进行配置。您将需要在 OAuth 同意屏幕上输入电子邮件地址和产品名称。
- 转到项目的 OAuth 同意屏幕。
配置同意屏幕 - 输入您要显示的应用名称。
- 在支持电子邮件地址下,选择要显示为公开联系人的电子邮件地址。这必须是您的电子邮件地址或您拥有的 Google 群组。
- 根据需要添加任何可选详细信息。
- 点击保存。
- 转到项目的 OAuth 同意屏幕。
为您的项目创建 OAuth 令牌。如需了解详情,请参阅设置 OAuth 2.0。
- 转到“创建 OAuth 客户端 ID”页面。
创建 OAuth 客户端 - 选择桌面应用作为应用类型。
- 点击创建。
- 转到“创建 OAuth 客户端 ID”页面。
下载
client_secret.json
文件。- 转到“凭据”页面。
- 在新的客户端 ID 的右侧,点击下载 JSON。
- 将文件安全地存储在只有您的应用可以访问的位置。
通过以下命令使用 JSON 文件登录。
gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
请注意,此命令将提示您打开链接。确保该页面显示您在 OAuth 同意屏幕中设置的应用名称。
使用以下命令为您的帐号生成身份验证令牌:
TOKEN=$(gcloud auth application-default print-access-token)
您现在可以使用
curl
命令查询资源。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"
以下所有标志都是可选的:
SCOPE 为必填项。范围可以是项目、文件夹或组织。只搜索此范围内的 Google Cloud 资源。调用者必须被授予所需范围的
cloudasset.assets.searchAllResources
权限。允许使用的值包括:
projects/PROJECT_ID
(例如,“projects/foo-bar
”)projects/PROJECT_NUMBER
(例如,“projects/12345678
”)folders/FOLDER_NUMBER
(例如,“folders/1234567
”)organizations/ORGANIZATION_NUMBER
(例如,“organizations/123456
”)
(可选)QUERY:查询语句。如需了解详情,请参阅如何构建查询。如果未指定或为空,它将搜索指定
scope
中的所有资源。示例:
name:Important
,查找名称包含“Important”一词的 Google Cloud 资源。name=Important
,查找名称正好为“Important”的 Google Cloud 资源。displayName:Impor*
,以查找显示名包含“Impor”作为任何词前缀的 Google Cloud 资源。location:us-west*
,用于查找位置同时包含“us”和“west”为前缀的 Google Cloud 资源。labels:prod
,查找所含标签的键或值包含“prod”一词的 Google Cloud 资源。labels.env:prod
,查找所含标签的键为“env”且值包含“prod”的 Google Cloud 资源。labels.env:*
,查找所含标签的键为“env”的 Google Cloud 资源。tagKeys:env
:用于查找与TagKey
中的标记直接关联的 Google Cloud 资源。namespacedName
包含“env”。tagValues:prod*
:用于查找与TagValue
中的标记直接关联的 Google Cloud 资源。namespacedName
包含一个以 "prod" 为前缀的字词。tagValueIds=tagValues/123
:用于查找与TagValue
中的标记直接关联的 Google Cloud 资源。name
正好是“tagValues/123”。kmsKey:key
,查找使用名称包含“key”这个词、由客户管理的加密密钥加密的 Google Cloud 资源。relationships:instance-group-1
:用于查找在相关资源名称中与“instance-group-1”有关联的 Google Cloud 资源。relationships:INSTANCE_TO_INSTANCEGROUP
,用于查找类型为“INSTANCE_TO_INSTANCEGROUP”类型的 Compute Engine 实例。relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
。state:ACTIVE
,查找状态包含“ACTIVE”这个词的 Google Cloud 资源。NOT state:ACTIVE
,查找状态包含“ACTIVE”这个词的 Google Cloud 资源。createTime<1609459200
或createTime<2021-01-01
或createTime<"2021-01-01T00:00:00"
,查找在“2021-01-01 00:00:00 UTC”之前创建的 Google Cloud 资源。1609459200 是“2021-01-01 00:00:00 UTC”的纪元时间戳。updateTime>1609459200
或updateTime>2021-01-01
或updateTime>"2021-01-01T00:00:00"
,查找在“2021-01-01 00:00:00 UTC”后更新的 Google Cloud 资源。1609459200 是“2021-01-01 00:00:00 UTC”的纪元时间戳。project:12345
,查找属于编号为 12345 的 Google Cloud 项目的 Google Cloud 资源。folders:(123 or 456)
,查找属于编号为 123 或 456 的 Google Cloud 文件夹的 Google Cloud 资源。organization:123
,查找属于编号为 123 的 Google Cloud 组织的 Google Cloud 资源。parentFullResourceName:ImportantName
,查找其父级名称中包含ImportantName
的 Google Cloud 资源。parentAssetType:Project
,查找其父级资产类型包含Project
的 Google Cloud 资源。Important
,查找任何可搜索字段中包含一词“Important”的 Google Cloud 资源。Impor*
,以查找包含以“Impr”作为任何可搜索字段中任何词前缀的 Google Cloud 资源。Important location:(us-west1 OR global)
,查找任何可搜索字段中包含一词“Important”且还位于“us-west1”区域或“全局”位置的 Google Cloud 资源。
(可选)ASSET_TYPES:此请求搜索的资产类型列表。如果为空,它将搜索所有可搜索的资产类型。此外,还支持正则表达式。例如:
"compute.googleapis.com.*"
是资产类型以"compute.googleapis.com"
开头的资源的快照。".*Instance"
快照,其资产类型以"Instance"
结尾的资源。- 其资产类型包含
"Instance"
的".*Instance.*"
快照资源。
如需查看所有支持的正则表达式语法,请参阅 RE2。如果正则表达式与任何支持的资产类型均不匹配,则将返回
INVALID_ARGUMENT
错误。(可选)ORDER_BY:指定结果排序顺序的以逗号分隔的字段列表。默认顺序是升序。在字段名称后添加
" DESC"
可指示降序顺序。多余空格会被忽略。示例:"location DESC, name"
。响应中只有单一原始字段是可排序的:name
assetType
project
displayName
description
location
kmsKey
createTime
updateTime
state
parentFullResourceName
parentAssetType
其他所有字段,例如重复字段(例如,
networkTags
),映射字段(例如labels
)和结构体字段(例如,additionalAttributes
)。(可选)PAGE_SIZE:搜索结果分页的页面大小。最大值是 500。如果该值设为
0
,将选择相应默认值。(可选)PAGE_TOKEN:表示对此方法的上一次调用的下一批结果的令牌。
page_token
必须与上一次调用的响应中next_page_token
的值相同。(可选)READ_MASK:用于指定要在结果中返回的字段的英文逗号分隔列表。如果未指定此参数,则系统将返回
versionedResources
以外的所有字段。如果仅指定了"*"
,则返回所有字段。示例:"name,location"
、"name,versionedResources"
、"*"
。
客户端库和 API 参考文档
如何构建查询
如需详细了解查询语言,请参阅查询语法。
如需详细了解各种实际用例的查询示例,请参阅搜索资源示例。
按资源元数据字段查询 Google Cloud 资源
如需搜索资源元数据,查询表达式需采用以下格式:
- 文本完全匹配:
FIELD=QUERY
- 文本部分匹配:
FIELD:QUERY
- 数值匹配:比较运算符(
=
、>
、>=
、<
、<=
)FIELDcomparison operatorQUERY
可搜索的资源元数据 FIELD 可以是:
- name:资源的完整资源名称。注意:并非所有资产类型都可搜索。请参阅可搜索类型列表。
- displayName:界面中的显示名
- description:一个或多个段落的资源文本说明
- location:资源的位置。位置可以是“global”、地区级(例如“us-east1”)或区域级(例如“us-west1-b”)。
labels:与此资源关联的标签。标签可以匹配标签键和/或标签值。请参阅为 GCP 资源添加标签和分组。
labels.[key]:由与此资源关联的标签键标识的标签值。例如:“
labels.env:prod
”。标签键中只能使用连字符 (-
)、下划线 (_
)、小写字符和数字。键必须以小写字符开头。允许使用国际字符。请参阅标签要求。tagKeys:
TagKey
。直接附加到此资源的namespacedName
标记。tagValues:
TagValue
。直接附加到此资源的namespacedName
标记。tagValueIds:
TagValue
。直接附加到此资源的name
标记。networkTags:与此资源关联的网络标记。请参阅为 GCP 资源添加标签和分组。
kmsKey:用于加密此资源的客户管理的加密密钥。请参阅 CryptoKey 和 CryptoKeyVersion。
只使用关系:与此资源相关联的关系。 关系可以匹配关系类型和/或相关资源名称。 请参阅支持的关系类型。
只使用关系 [.shipship_type]:与此资源相关联的特定资源类型的相关资源名称。例如:"
relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
"。请参阅支持的关系类型。state:此资源的状态文本值。不同的资源类型具有不同的状态定义,映射自不同资源类型的不同字段。示例:如果资源是 Compute Engine 提供的实例,则其状态将包含 PROVISIONING、STAGING、RUNNING、STOPPING、SUSPENDING、SUSPENDED、REPAIRING 和 TERMINATED。请参阅 API 参考文档中的
status
定义。 如果资源是 Cloud Resource Manager 提供的项目,则其状态将包含 LIFECYCLE_STATE_UNSPECIFIED、ACTIVE、DELETE_REQUESTED 和 DELETE_IN_PROGRESS。请参阅 API 参考文档中的lifecycleState
定义。createTime:此资源的创建时间戳,表示此资源的创建时间。粒度是秒。
updateTime:此资源的上次更新时间戳,即上次修改或删除此资源的时间。粒度是秒。
project:此资源所属项目的编号。
folders:此资源所属的文件夹的编号。
organization:此资源所属的组织的编号。
parentCompleteResourceName:此资源的父级资源的名称。
parentAssetType:此资源的父级资源的类型。
示例:按特定字段查询
在
scope
中查找name
包含Important
一词的所有资源:name:Important
在
scope
中查找displayName
包含前缀为prod
的字词的所有资源:displayName:prod*
在
scope
中查找location
包含us
一词的所有资源:location:us
在
scope
中查找location
恰好等于us
的所有资源:location=us
查找
scope
中直接附加了带有TagKey
namespacedName
并包含env
标记的所有资源:tagKeys:env
在
scope
中找到所有已经使用TagValue
直接附加标记的资源。namespacedName
包含前缀为prod
的字词:tagValues:prod*
查找
scope
中具有直接附加了TagValue
的标记的所有资源。name
正好等于tagValues/123
:tagValueIds=tagValues/123
查找您的
scope
具有直接附加的标记与TagValue
的所有资源。namespacedName
也就是具有直接附加的标记的所有资源:tagValues:*
在
scope
中查找label
的键或值包含prod
一词的所有资源:labels:prod
在
scope
中查找label
的键为env
且值包含prod
一词的所有资源:labels.env:prod
在
scope
中查找label
的键为env
且值恰好等于prod
的所有资源:labels.env=prod
在
scope
中查找label
的键为env
的所有资源:labels.env:*
在
scope
中查找其中一个networkTags
包含internal
一词的所有资源:networkTags:internal
在
scope
中查找其中一个networkTags
恰好等于internal
的所有资源:networkTags=internal
在
scope
中查找与相关资源名称中的instance-group-1
存在关系的所有资源:relationships:instance-group-1
在
scope
中查找类型为INSTANCE_TO_INSTANCEGROUP
的计算实例:relationships:INSTANCE_TO_INSTANCEGROUP
在
scope
中查找关系实例组类型INSTANCE_TO_INSTANCEGROUP
的计算实例组资源名称中与instance-group-1
有关系的计算实例:relationships.INSTANCE_TO_INSTANCEGROUP:instance-group-1
在使用客户管理的加密密钥加密并且此客户的名称中包含
key
一词的scope
中,查找所有资源kmsKey:key
在
scope
中查找state
包含ACTIVE
一词的所有资源:state:ACTIVE
在
scope
中查找state
不包含ACTIVE
一词的所有资源:NOT state:ACTIVE
查找
scope
中在“2021-01-01 00:00:00 UTC”(1609459200 是“2021-01-01 00:00:00 UTC”以秒为单位的纪元时间戳)之前创建的所有资源:createTime<1609459200 createTime<2021-01-01 createTime<"2021-01-01T00:00:00"
查找
scope
中在“2021-01-01 00:00:00 UTC”(1609459200 是“2021-01-01 00:00:00 UTC”以秒为单位的纪元时间戳)后更新的所有资源:updateTime>1609459200 updateTime>2021-01-01 updateTime>"2021-01-01T00:00:00"
在
scope
中查找project
的编号为123
的所有资源:project:123
在编号为
123
的folder
所包含的scope
中查找所有资源:folders:123
在
scope
中查找organization
的编号为123
的所有资源:organization:123
在
scope
中查找parentFullResourceName
包含ImportantName
的所有资源:parentFullResourceName:ImportantName
在
scope
中查找parentAssetType
包含Project
的所有资源:parentAssetType:Project
在
scope
中找到name
包含字词Important
且description
包含前缀import
的所有资源:name:Important description:import*
在
scope
中找到name
包含字词Important
或description
包含前缀import
的所有资源:name:Important OR description:import*
通过自由文本查询 Google Cloud 资源
您也可以直接使用自由文本查询,而无需指定字段。然后,只要资源元数据中的某个字段与查询匹配,它就会返回资源。
示例:按自由文本查询
查找您的
scope
中元数据字段(例如name
、displayName
、description
)包含Important
一词:Important
查找您的
scope
中元数据字段(例如name
、displayName
、description
)包含前缀为import
的字词:import*
查找您的
scope
中元数据字段(例如name
、displayName
、description
)包含Important
一词,并且还包含前缀为prod
的字词:Important prod*