Como pesquisar recursos

A API Cloud Asset permite usar uma linguagem de consulta personalizada para consultar metadados de recursos em um projeto, pasta ou organização.

Antes de começar

Pesquisar recursos

Console

Para pesquisar todos os recursos, conclua as etapas a seguir.

  1. Acesse a página Inventário de recursos no Console do Cloud.
    Acessar a página Inventário de recursos

  2. Para definir o escopo da pesquisa, abra a caixa de lista Projetos na barra de menus e selecione a organização, a pasta ou o projeto a ser consultado.

  3. Selecione a guia Recurso.

  4. Para pesquisar recursos, insira o texto da consulta na barra Filtro. Selecione a caixa de texto, e uma lista de campos pesquisáveis será exibida. A pesquisa de recursos aceita vários campos. Saiba mais sobre Sintaxe de consulta.

  5. Os resultados da pesquisa também podem ser filtrados com os filtros predefinidos Tipo de recurso, Projeto e Local no painel Resultados do filtro..

Os recursos correspondentes à consulta são listados na tabela Resultado.

Para visualizar a consulta como um comando da ferramenta de linha de comando gcloud, selecione Visualizar consulta.

Para exportar os resultados, selecione Fazer o download do CSV.

gcloud

É possível chamar SearchAllResources usando o comando gcloud asset search-all-resources. É preciso usar o SDK do Cloud versão 302.0.0 ou mais recente. Para verificar sua versão, use o comando 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

Em que todas as sinalizações a seguir são opcionais:

  • (Opcional) SCOPE: um escopo pode ser um projeto, uma pasta ou uma organização. A pesquisa é limitada aos recursos do Google Cloud nesse escopo. O autor da chamada precisa receber a permissão cloudasset.assets.searchAllResources no escopo pretendido. Se não for especificada, a propriedade do projeto configurada será usada. Para encontrar o projeto configurado, execute: gcloud config get-value project. Para alterar a configuração, execute: gcloud config set project PROJECT_ID.

    Os valores permitidos são:

    • projects/PROJECT_ID (ex., "projects/foo-bar")
    • projects/PROJECT_NUMBER (ex., "projects/12345678")
    • folders/FOLDER_NUMBER (ex., "folders/1234567")
    • organizations/ORGANIZATION_NUMBER (ex., "organizations/123456")

  • (Opcional) QUERY: a instrução de consulta. Veja como criar uma consulta para mais informações. Se não for especificado ou estiver vazio, ele pesquisará todos os recursos na scope especificada.

    Exemplos:

    • name:Important para encontrar recursos do Google Cloud cujo nome contenha a palavra "Importante".
    • name=Important para encontrar o recurso do Google Cloud cujo nome é exatamente "Importante".
    • displayName:Impor* para encontrar recursos do Google Cloud com um nome de exibição que contenha "Impor" como prefixo de qualquer palavra.
    • location:us-west* para encontrar recursos do Google Cloud em que o local tenha duas palavras com "us" e "west" como prefixos.
    • labels:prod para encontrar recursos do Google Cloud que tenham um rótulo em que a chave ou o valor contém a palavra "prod".
    • labels.env:prod para encontrar recursos do Google Cloud que tenham um rótulo em que a chave é "env" e o valor contém a palavra "prod".
    • labels.env:* para encontrar recursos do Google Cloud que tenham um rótulo em que a chave é "env".
    • kmsKey:key para encontrar recursos do Google Cloud criptografados com uma chave de criptografia gerenciada pelo cliente com um nome que contenha "key" como palavra.
    • state:ACTIVE para encontrar recursos do Google Cloud em que o estado contenha "ACTIVE" como palavra.
    • NOT state:ACTIVE para encontrar recursos do Google Cloud em que o estado não contenha "ACTIVE" como palavra.
    • createTime<1609459200, createTime<2021-01-01 ou createTime<"2021-01-01T00:00:00" para encontrar recursos do Google Cloud criados antes de "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC".
    • updateTime>1609459200 ou updateTime>2021-01-01 ou updateTime>"2021-01-01T00:00:00" para encontrar recursos do Google Cloud atualizados após "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC".
    • project:12345 para encontrar recursos do Google Cloud que pertencem a um projeto com o número 12345.
    • folders:(123 or 456) para encontrar recursos do Google Cloud que pertencem a uma pasta do Google Cloud com os números 123 ou 456.
    • organization:123 para encontrar recursos do Google Cloud que pertencem a uma organização do Google Cloud com o número 123.
    • parentFullResourceName:ImportantName para encontrar recursos do Google Cloud com um nome pai que contém ImportantName.
    • parentAssetType:Project para encontrar recursos do Google Cloud com um tipo de recurso pai que contém Project.
    • Important para encontrar recursos do Google Cloud que contenham a palavra "Importante" em qualquer um dos campos pesquisáveis.
    • Impor* para encontrar recursos do Google Cloud que contêm "Impor" como prefixo de qualquer palavra em qualquer um dos campos pesquisáveis.
    • Important location:(us-west1 OR global) para encontrar recursos do Google Cloud que contêm a palavra "Important" em qualquer campo pesquisável e também estão localizados na região "us-west1" ou no local "global".

  • (Opcional) ASSET_TYPES: uma lista de tipos de recursos que essa solicitação está pesquisando. Se estiver vazia, ela vai pesquisar todos os tipos de recursos pesquisáveis. Expressões regulares também são aceitas. Exemplo:

    • "compute.googleapis.com.*" tira snapshots de recursos em que o tipo de recurso começa com "compute.googleapis.com".
    • ".*Instance" tira snapshots de recursos em que o tipo de recurso termina com "Instance".
    • ".*Instance.*" tira snapshots de recursos em que o tipo de recurso contém "Instance".

    Consulte RE2 para ver todas as sintaxes de expressão regular aceitas. Se a expressão regular não corresponder a nenhum tipo de recurso aceito, um erro INVALID_ARGUMENT vai ser retornado.

  • (Opcional) ORDER_BY: uma lista de campos separada por vírgulas que especifica a ordem de classificação dos resultados. A ordem padrão é crescente. Adicione " DESC" depois do nome do campo para indicar a ordem decrescente. Caracteres de espaço redundantes são ignorados. Exemplo: "location DESC, name". Somente os campos primitivos singulares na resposta são classificáveis:

    • name
    • assetType
    • project
    • displayName
    • description
    • location
    • kmsKey
    • createTime
    • updateTime
    • state
    • parentFullResourceName
    • parentAssetType

    Os demais campos, como os repetidos (por exemplo, networkTags), de mapa (por exemplo, labels) e de estrutura (por exemplo, additionalAttributes), não são aceitos.

  • (Opcional) PAGE_SIZE: o tamanho da página para a paginação de resultados da pesquisa. O valor máximo é 500. Se o valor for 0, um padrão apropriado será escolhido;

  • (Opcional) READ_MASK: uma lista separada por vírgulas de campos especificando quais campos devem ser retornados nos resultados. Se não for especificado, todos os campos, exceto versionedResources, vão ser retornados. Se apenas "*" for especificado, todos os campos vão ser retornados. Exemplos: "name,location", "name,versionedResources", "*".

Veja a seguir exemplos de comandos do gcloud:

  • Encontre todos os recursos em "organizations/123456" em que name contenha a palavra mycompany:

    gcloud asset search-all-resources \
  --scope='organizations/123456' \
  --query='name:mycompany'

  • Encontre todos os recursos em "organizations/123456" em que name contenha a palavra mycompany, com metadados completos incluídos:

    gcloud asset search-all-resources \
  --scope='organizations/123456' \
  --query='name:mycompany' \
  --read-mask='*'

api

Você pode chamar SearchAllResources usando um token OAuth válido para um projeto. Para chamar o método SearchAllResources do Cloud Shell ou qualquer console em que o comando gcloud esteja disponível:

  1. Se você ainda não configurou a tela de consentimento do OAuth do seu projeto, precisará fazê-lo. É necessário informar um endereço de e-mail e o nome do produto para a tela de consentimento do OAuth.

    1. Acesse a tela de consentimento OAuth do seu projeto.
      Configurar tela de consentimento
    2. Digite o Nome do aplicativo que você quer exibir.
    3. Em E-mail de suporte, selecione o endereço de e-mail que você quer exibir como um contato público. Precisa ser o seu endereço de e-mail ou um grupo do Google que pertença a você.
    4. Adicione os detalhes opcionais que você quiser.
    5. Clique em Salvar.

  2. Crie um token OAuth para seu projeto. Para ver mais informações, consulte Como configurar o OAuth 2.0.

    1. Acesse a página Criar ID do cliente OAuth.
      Criar cliente OAuth
    2. Selecione App para computador como o Tipo de aplicativo.
    3. Clique em Criar.

  3. Faça o download do arquivo client_secret.json.

    1. Acesse a página Credenciais.
    2. À direita de seu novo ID do cliente, clique em Fazer o download do JSON.
    3. Armazene com segurança o arquivo em um local que somente o app possa acessar.

  4. Faça login usando o arquivo JSON com o seguinte comando:

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

    Esse comando solicitará que você abra um link. Verifique se o Nome do aplicativo definido na tela de consentimento do OAuth é exibido.

  5. Gere um token de autenticação para sua conta com o seguinte comando:

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

  6. Agora é possível consultar recursos usando os comandos do 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"

Em que todas as sinalizações a seguir são opcionais:

  • SCOPE: é obrigatório. Um escopo pode ser um projeto, uma pasta ou uma organização. A pesquisa é limitada aos recursos do Google Cloud nesse escopo. O autor da chamada precisa receber a permissão cloudasset.assets.searchAllResources no escopo pretendido.

    Os valores permitidos são:

    • projects/PROJECT_ID (ex., "projects/foo-bar")
    • projects/PROJECT_NUMBER (ex., "projects/12345678")
    • folders/FOLDER_NUMBER (ex., "folders/1234567")
    • organizations/ORGANIZATION_NUMBER (ex., "organizations/123456")

  • (Opcional) QUERY: a instrução de consulta. Veja como criar uma consulta para mais informações. Se não for especificado ou estiver vazio, ele pesquisará todos os recursos na scope especificada.

    Exemplos:

    • name:Important para encontrar recursos do Google Cloud cujo nome contenha a palavra "Importante".
    • name=Important para encontrar o recurso do Google Cloud cujo nome é exatamente "Importante".
    • displayName:Impor* para encontrar recursos do Google Cloud com um nome de exibição que contenha "Impor" como prefixo de qualquer palavra.
    • location:us-west* para encontrar recursos do Google Cloud em que o local contenha "us" e "west" como prefixos.
    • labels:prod para encontrar recursos do Google Cloud que tenham um rótulo em que a chave ou o valor contém a palavra "prod".
    • labels.env:prod para encontrar recursos do Google Cloud que tenham um rótulo em que a chave é "env" e o valor contém a palavra "prod".
    • labels.env:* para encontrar recursos do Google Cloud que tenham um rótulo em que a chave é "env".
    • kmsKey:key para encontrar recursos do Google Cloud criptografados com uma chave de criptografia gerenciada pelo cliente com um nome que contenha "key" como palavra.
    • state:ACTIVE para encontrar recursos do Google Cloud em que o estado contenha "ACTIVE" como palavra.
    • NOT state:ACTIVE para encontrar recursos do Google Cloud em que o estado não contenha "ACTIVE" como palavra.
    • createTime<1609459200, createTime<2021-01-01 ou createTime<"2021-01-01T00:00:00" para encontrar recursos do Google Cloud criados antes de "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC".
    • updateTime>1609459200 ou updateTime>2021-01-01 ou updateTime>"2021-01-01T00:00:00" para encontrar recursos do Google Cloud atualizados após "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC".
    • project:12345 para encontrar recursos do Google Cloud que pertencem a um projeto com o número 12345.
    • folders:(123 or 456) para encontrar recursos do Google Cloud que pertencem a uma pasta do Google Cloud com os números 123 ou 456.
    • organization:123 para encontrar recursos do Google Cloud que pertencem a uma organização do Google Cloud com o número 123.
    • parentFullResourceName:ImportantName para encontrar recursos do Google Cloud com um nome pai que contém ImportantName.
    • parentAssetType:Project para encontrar recursos do Google Cloud com um tipo de recurso pai que contém Project.
    • Important para encontrar recursos do Google Cloud que contenham a palavra "Importante" em qualquer um dos campos pesquisáveis.
    • Impor* para encontrar recursos do Google Cloud que contêm "Impor" como prefixo de qualquer palavra em qualquer um dos campos pesquisáveis.
    • Important location:(us-west1 OR global) para encontrar recursos do Google Cloud que contêm a palavra "Important" em qualquer campo pesquisável e também estão localizados na região "us-west1" ou no local "global".

  • (Opcional) ASSET_TYPES: uma lista de tipos de recursos que essa solicitação está pesquisando. Se estiver vazia, ela vai pesquisar todos os tipos de recursos pesquisáveis. Expressões regulares também são aceitas. Exemplo:

    • "compute.googleapis.com.*" tira snapshots de recursos em que o tipo de recurso começa com "compute.googleapis.com".
    • ".*Instance" tira snapshots de recursos em que o tipo de recurso termina com "Instance".
    • ".*Instance.*" tira snapshots de recursos em que o tipo de recurso contém "Instance".

    Consulte RE2 para ver todas as sintaxes de expressão regular aceitas. Se a expressão regular não corresponder a nenhum tipo de recurso aceito, um erro INVALID_ARGUMENT vai ser retornado.

  • (Opcional) ORDER_BY: uma lista de campos separada por vírgulas que especifica a ordem de classificação dos resultados. A ordem padrão é crescente. Adicione " DESC" depois do nome do campo para indicar a ordem decrescente. Caracteres de espaço redundantes são ignorados. Exemplo: "location DESC, name". Somente os campos primitivos singulares na resposta são classificáveis:

    • name
    • assetType
    • project
    • displayName
    • description
    • location
    • kmsKey
    • createTime
    • updateTime
    • state
    • parentFullResourceName
    • parentAssetType

    Os demais campos, como os repetidos (por exemplo, networkTags), de mapa (por exemplo, labels) e de estrutura (por exemplo, additionalAttributes), não são aceitos.

  • (Opcional) PAGE_SIZE: o tamanho da página para a paginação de resultados da pesquisa. O valor máximo é 500. Se o valor for 0, um padrão apropriado será escolhido;

  • (Opcional) PAGE_TOKEN: o token que representa o próximo lote de resultados da chamada anterior para esse método. O page_token precisa ser igual ao valor de next_page_token da resposta da chamada anterior.

  • (Opcional) READ_MASK: uma lista separada por vírgulas de campos especificando quais campos devem ser retornados nos resultados. Se não for especificado, todos os campos, exceto versionedResources, vão ser retornados. Se apenas "*" for especificado, todos os campos vão ser retornados. Exemplos: "name,location", "name,versionedResources", "*".

Biblioteca de cliente e referência de API

Como criar uma consulta

Veja a sintaxe de consulta para saber mais sobre a linguagem de consulta.

Consulte como pesquisar amostras de recursos para saber mais sobre as consultas de amostra para vários casos de uso reais.

Consultar recursos do Cloud por campos de metadados do recurso

Para pesquisar metadados de recursos, uma expressão de consulta tem os seguintes formatos:

  • Correspondência exata de texto: FIELD=QUERY
  • Correspondência parcial de texto: FIELD:QUERY
  • Correspondência numérica: operadores de comparação (=, >, >=, <, <=) FIELDcomparison operatorQUERY

Os metadados de recursos pesquisáveis FIELD podem ser:

  • name: o nome completo do recurso. Observação: nem todos os tipos de recurso são pesquisáveis. Consulte a lista de tipos pesquisáveis.
  • displayName: o nome de exibição na IU
  • description: a descrição de texto do recurso em um ou mais parágrafos
  • location: o local do recurso. O local pode ser "global", regional (por exemplo, "us-east1") ou zonal (por exemplo, "us-west1-b").

  • labels: rótulos associados a este recurso. Os rótulos podem corresponder a chaves de chave, valores de rótulo ou ambos. Consulte Como rotular e agrupar recursos do GCP.

  • labels.[key]: valor do rótulo identificado pela chave do rótulo associado a esse recurso. Por exemplo: "labels.env:prod". Somente hifens (-), sublinhados (_), caracteres minúsculos e números são permitidos nas chaves de rótulos. As chaves precisam começar com uma letra minúscula. Caracteres internacionais são permitidos. Consulte Requisitos de rótulos.

  • networkTags: tags de rede associadas a esse recurso. Consulte Como rotular e agrupar recursos do GCP.

  • kmsKey: a chave de criptografia gerenciada pelo cliente usada para criptografar esse recurso. Consulte CryptoKey e CryptoKeyVersion.

  • state: o valor de texto do estado desse recurso. Os diversos tipos de recursos têm diferentes definições de estado mapeadas de vários campos de tipos de recursos distintos. Exemplo: se o recurso for uma instância fornecida pelo Compute Engine, o estado incluirá PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING e TERMINATED. Veja a definição de status na Referência da API. Se o recurso for um projeto fornecido pelo Cloud Resource Manager, o estado dele vai incluir LIFECYCLE_STATE_UNSPECIFIED, ACTIVE, DELETE_REQUESTED e DELETE_IN_PROGRESS. Veja a definição de lifecycleState na Referência da API.

  • createTime: o carimbo de data/hora da criação desse recurso, em que o recurso foi criado. A granularidade está em segundos.

  • updateTime: o carimbo de data/hora da última atualização desse recurso, a vez mais recente em que o recurso foi alterado ou excluído. A granularidade está em segundos.

  • project: o número do projeto ao que esse recurso pertence.

  • folders: os números das pastas às quais esse recurso pertence.

  • organization: o número da organização a que esse recurso pertence.

  • parentFullResourceName: o nome do pai desse recurso.

  • parentAssetType: o tipo de pai desse recurso.

Exemplos: consulta por campo específico

  • Localize todos os recursos no scope em que name contém a palavra Important:

    name:Important

  • Encontre todos os recursos no scope em que displayName contém uma palavra com o prefixo prod:

    displayName:prod*

  • Localize todos os recursos no scope em que location contém a palavra us:

    location:us

  • Encontre todos os recursos em scope em que location seja exatamente igual a us:

    location=us

  • Encontre todos os recursos no scope que tenham um label em que a chave ou o valor contenha a palavra prod:

    labels:prod

  • Encontre todos os recursos no scope que tenham um label em que a chave seja env e o valor contenha a palavra prod:

    labels.env:prod

  • Encontre todos os recursos no scope que tenham um label em que a chave é env e o valor seja exatamente igual a prod:

    labels.env=prod

  • Encontre todos os recursos no scope que tenham um label em que a chave é env:

    labels.env:*

  • Encontre todos os recursos no scope que aqueles com networkTags contêm a palavra internal:

    networkTags:internal

  • Localize todos os recursos na scope que têm um networkTags igual exatamente internal:

    networkTags=internal

  • Encontre todos os recursos no scope criptografados com uma chave de criptografia gerenciada pelo cliente em que o nome contém a palavra key:

    kmsKey:key

  • Encontre todos os recursos no scope em que state contém a palavra ACTIVE:

    state:ACTIVE

  • Encontre todos os recursos no scope em que state não contém a palavra ACTIVE:

    NOT state:ACTIVE

  • Encontre todos os recursos no scope que foram criados antes de "2021-01-01 00:00:00 UTC" (1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC"):

    createTime<1609459200
createTime<2021-01-01
createTime<"2021-01-01T00:00:00"

  • Encontre todos os recursos no scope que foram atualizados depois de "2021-01-01 00:00:00 UTC" (1609459200 é o carimbo de data/hora da época em segundos de "2021-01-01 00:00:00 UTC"):

    updateTime>1609459200
updateTime>2021-01-01
updateTime>"2021-01-01T00:00:00"

  • Encontre todos os recursos no scope em que project tem o número 123:

    project:123

  • Encontre todos os recursos no scope contidos em folder com o número 123:

    folders:123

  • Encontre todos os recursos no scope em que organization tem o número 123:

    organization:123

  • Encontre todos os recursos no scope em que parentFullResourceName contém ImportantName:

    parentFullResourceName:ImportantName

  • Encontre todos os recursos no scope em que parentAssetType contém Project:

    parentAssetType:Project

  • Encontre todos os recursos no scope em que name contém a palavra Important e description contenha uma palavra com o prefixo import:

    name:Important description:import*

  • Encontre todos os recursos no scope em que name contém a palavra Important ou description contenha uma palavra com o prefixo import:

    name:Important OR description:import*

Consultar recursos do Cloud por texto livre

Você também pode simplesmente usar uma consulta de texto livre sem especificar um campo. Em seguida, ele retornará recursos, desde que haja um campo nos metadados do recurso que correspondam à consulta.

Exemplos: consulta por texto livre

  • Encontre todos os recursos no scope que tenha campos de metadados (por exemplo, name, displayName, description) contêm a palavra Important:

    Important

  • Encontre todos os recursos no scope que tenha campos de metadados (por exemplo, name, displayName, description) contêm uma palavra com o prefixo import:

    import*

  • Encontre todos os recursos no scope que tenha campos de metadados (por exemplo, name, displayName, description) contêm a palavra Important e também contêm uma palavra com o prefixo prod:

    Important prod*