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

Ative a API Cloud Asset no projeto.
Conceda a permissão cloudasset.assets.searchAllResources à conta de usuário ou de serviço que faz a solicitação. Essa permissão está incluída em papéis básicos e predefinidos listados em Roles.

Chamando `SearchAllResources`

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.
- createTime<1609459200 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 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".
- 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:

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.

Não insira nenhuma informação confidencial na tela de consentimento do OAuth. Qualquer informação que você salvar nessa tela poderá ficar visível publicamente para quem acessa seu URL. Os detalhes do produto e do e-mail são exibidos na tela de login e quando alguém tenta acessar um recurso sem ter permissão para isso.
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.
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.
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.
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.
Gere um token de autenticação para sua conta com o seguinte comando:
```
TOKEN=$(gcloud auth application-default print-access-token)
```

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.
- createTime<1609459200 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 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".
- 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

SearchAllResources

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.

Observação: rótulos como um objeto aninhado não são compatíveis com o operador equals (=).
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 em que o recurso foi criado. 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.

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 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
```
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
```
Encontre todos os recursos no scope em 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 no scope em que name contém 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*
```