搜索资源

借助 Cloud Asset API，您可以使用自定义查询语言来查询项目、文件夹或组织的资源元数据。

准备工作

搜索资源

控制台

如需搜索所有资源，请完成以下步骤。

  1. 转到控制台中的 Asset Inventory 页面。
    转到“Asset Inventory”页面

  2. 要设置搜索范围，请打开菜单栏中的“项目”列表框，然后选择要查询的组织、文件夹或项目。

  3. 选择资源标签页。

  4. 如需搜索资源，请在过滤条件栏中输入查询文本。选择文本框，随即会显示可搜索字段的列表。资源搜索支持多个字段。详细了解查询语法。

  5. 搜索结果也可以按过滤结果窗格中预定义的资源类型、项目和位置过滤条件进行过滤。

结果表中会列出与查询匹配的资源。

如需以 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 方法，请执行以下操作：

  1. 如果您尚未配置项目的 OAuth 同意屏幕，则需要进行配置。您将需要在 OAuth 同意屏幕上输入电子邮件地址和产品名称。

    1. 转到项目的 OAuth 同意屏幕。
      配置同意屏幕
    2. 输入您要显示的应用名称。
    3. 在支持电子邮件地址下，选择要显示为公开联系人的电子邮件地址。这必须是您的电子邮件地址或您拥有的 Google 群组。
    4. 根据需要添加任何可选详细信息。
    5. 点击保存。

  2. 为您的项目创建 OAuth 令牌。如需了解详情，请参阅设置 OAuth 2.0。

    1. 转到“创建 OAuth 客户端 ID”页面。
      创建 OAuth 客户端
    2. 选择桌面应用作为应用类型。
    3. 点击创建。

  3. 下载 client_secret.json 文件。

    1. 转到“凭据”页面。
    2. 在新的客户端 ID 的右侧，点击下载 JSON。
    3. 将文件安全地存储在只有您的应用可以访问的位置。

  4. 通过以下命令使用 JSON 文件登录。

    gcloud auth application-default login --client-id-file=YOUR_JSON_FILE

    请注意，此命令将提示您打开链接。确保该页面显示您在 OAuth 同意屏幕中设置的应用名称。

  5. 使用以下命令为您的帐号生成身份验证令牌：

    TOKEN=$(gcloud auth application-default print-access-token)

  6. 您现在可以使用 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*