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

Chamando SearchAllResources

Console

  1. No Console do Cloud, acesse a página Inventário de recursos.

    Acessar a página "Inventário de recursos"

  2. Na parte superior da janela do Console do Cloud, abra o Projeto do projeto para alterar o escopo selecionando uma organização, pasta ou projeto.

  3. No painel à esquerda, marque Tipo de recurso, Projeto ou Local para filtrar os resultados.

  4. A barra Filtro na parte superior da tabela de resultados permite especificar uma consulta. Clique na caixa de entrada para abrir uma lista de campos pesquisáveis. Vários campos são aceitos. Consulte a página Sintaxe de consulta para ver todos os detalhes.

  5. Os resultados da pesquisa serão mostrados na tabela de resultados abaixo.

  6. Os usuários podem ver a consulta real clicando no botão VER CONSULTA, que mostra o comando gcloud correspondente.

  7. Para exportar os resultados da pesquisa, clique no botão FAZER O DOWNLOAD de CSV.

  8. Os usuários também podem compartilhar a configuração de pesquisa clicando no botão "Compartilhar" para copiar o URL da página atual para a área de transferência.

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 \

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 cujo nome de exibição contém "Impor" como prefixo de qualquer palavra.
    • location:us-west* para encontrar recursos do Google Cloud cujo local tem 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 cujo nome contém "key" como palavra.
    • state:ACTIVE para encontrar recursos do Google Cloud cujo estado contém "ACTIVE" como uma palavra.
    • NOT state:ACTIVE para encontrar recursos do Google Cloud cujo estado não contenha "ACTIVE" como uma palavra.
    • createTime<1609459200 ou 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 do período 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 que foram atualizados após "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora do período em segundos de "2021-01-01 00:00:00 UTC".
    • project:12345 para encontrar recursos do Google Cloud que pertencem a um projeto do Google Cloud com número número 12345.
    • folders:(123 or 456) para encontrar recursos do Google Cloud que pertencem a uma pasta do Google Cloud com 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 os recursos do Google Cloud com o nome do pai que contém ImportantName.
    • parentAssetType:Project para encontrar recursos do Google Cloud cujo tipo de recurso pai 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 "Importante" em qualquer um dos campos pesquisáveis e também estão localizados na região "us-west1" ou no local "global".
  • (Opcional) ASSET_TYPES: uma lista de tipos de recurso para pesquisar. Se não for especificado ou estiver vazio, ele pesquisará todos os tipos de recursos pesquisáveis. Exemplo: "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance" para pesquisar recursos de projeto e de instância de VM. Expressões regulares também são compatíveis. Por exemplo: "compute.googleapis.com.*" cria um snapshot de recurso cujo tipo de recurso começa com "compute.googleapis.com". Consulte RE2 para ver todas as sintaxes de expressão regular compatíveis. Se a expressão regular não corresponder a nenhum tipo de recurso compatível, um erro INVALID_ARGUMENT 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 de string na resposta são classificáveis, incluindo name, displayName, description e location.

  • (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;

Veja a seguir exemplos de comandos gcloud:

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

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

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"
    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" \
       --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 cujo nome de exibição contém "Impor" como prefixo de qualquer palavra.
    • location:us-west* para encontrar recursos do Google Cloud com local contendo "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 cujo nome contém "key" como palavra.
    • state:ACTIVE para encontrar recursos do Google Cloud cujo estado contém "ACTIVE" como uma palavra.
    • NOT state:ACTIVE para encontrar recursos do Google Cloud cujo estado não contenha "ACTIVE" como uma palavra.
    • createTime<1609459200 ou 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 do período 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 que foram atualizados após "2021-01-01 00:00:00 UTC". 1609459200 é o carimbo de data/hora do período em segundos de "2021-01-01 00:00:00 UTC".
    • project:12345 para encontrar recursos do Google Cloud que pertencem a um projeto do Google Cloud com número número 12345.
    • folders:(123 or 456) para encontrar recursos do Google Cloud que pertencem a uma pasta do Google Cloud com 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 o nome do pai que contém ImportantName.
    • parentAssetType:Project para encontrar recursos do Google Cloud cujo tipo de recurso pai 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 "Importante" em qualquer um dos campos pesquisáveis e também estão localizados na região "us-west1" ou no local "global".
  • (Opcional) ASSET_TYPES: uma lista de tipos de recurso para pesquisar. Se não for especificado ou estiver vazio, ele pesquisará todos os tipos de recursos pesquisáveis. Exemplo: "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance" para pesquisar recursos de projeto e de instância de VM.

  • (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 de string na resposta são classificáveis, incluindo name, displayName, description e location.

  • (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.

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 este recurso. Consulte CryptoKey e CryptoKeyVersion.

  • state: o valor do texto do estado desse recurso. Diferentes 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. Consulte a definição status na Referência da API. Se o recurso for um projeto fornecido pelo Cloud Resource Manager, o estado incluirá LIFEYCLE_STATE_UNSPECIFIED, ACTIVE, DELETE_REQUESTED e DELETE_IN_PROGRESS. Consulte a definição lifecycleState na Referência da API.

  • createTime: o carimbo de data/hora da criação do recurso. A granularidade é feita em segundos.

  • updateTime: o carimbo de data/hora da última atualização desse recurso, em que o recurso foi modificado ou excluído pela última vez. A granularidade é feita em segundos.

  • project: o número do projeto a que este recurso pertence.

  • folders: os números das pastas a que este recurso pertence.

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

  • parentFullResourceName: o nome do pai do recurso.

  • parentAssetType: o tipo do 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 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 cujo 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 em scope com state que não contenha 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 em época 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 após "2021-01-01 00:00:00 UTC" (1609459200 é o carimbo de data/hora do período em época 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 tenha o número 123:

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

    folders:123
    
  • Encontre todos os recursos no scope em que organization tenha 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 que name contém a palavra Important e description contém uma palavra com o prefixo import:

    name:Important description:import*
    
  • Encontre todos os recursos na scope que name contenha a palavra Important ou description contém 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*