Início Rápido: Execute sua primeira consulta ao Resource Graph usando a API REST

Artigo
06/01/2023

A primeira etapa para usar o Azure Resource Graph com a API REST é verificar se você tem uma ferramenta para chamar as APIs REST disponíveis. Este início rápido orienta você pelo processo de execução de uma consulta e recuperação dos resultados chamando o ponto de extremidade da API REST do Azure Resource Graph.

No final desse processo, você terá as ferramentas para chamar os pontos de extremidade da API REST e executar sua primeira consulta do Resource Graph.

Pré-requisitos

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou o comando.

Introdução à API REST

Se você não estiver familiarizado com a API REST, comece examinando a Referência de API REST do Azure para obter um entendimento geral sobre a API REST, especificamente o corpo da solicitação e o URI de solicitação. Este artigo usa esses conceitos para fornecer instruções para trabalhar com o Azure Resource Graph e pressupõe um conhecimento prático deles. Ferramentas como ARMClient e outras pessoas podem lidar com autorização automaticamente e são recomendadas para iniciantes.

Para obter as especificações do Azure Resource Graph, confira API REST do Azure Resource Graph.

API REST e PowerShell

Se você ainda não tiver uma ferramenta para fazer chamadas à API REST, considere usar o PowerShell para essas instruções. O exemplo de código a seguir obtém um cabeçalho para autenticação com o Azure. Gere um cabeçalho de autenticação, às vezes chamado de um token de portador, e forneça o URI da API REST para se conectar com quaisquer parâmetros ou um corpo da solicitação:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = "https://management.azure.com/subscriptions/$($azContext.Subscription.Id)?api-version=2020-01-01"
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

A variável $response armazena o resultado do cmdlet Invoke-RestMethod, que pode ser analisado com os cmdlets, como ConvertFrom-Json. Se o ponto de extremidade de serviço da API REST espera um Corpo da Solicitação, forneça uma variável formatada do JSON para o parâmetro -Body de Invoke-RestMethod.

Executar a primeira consulta ao Resource Graph

Com as ferramentas de API REST adicionadas ao ambiente de sua escolha, é hora de experimentar uma consulta simples ao Resource Graph baseada em assinatura. A consulta retorna os cinco primeiros recursos do Azure com o Nome e o Tipo de Recurso de cada um. Para consultar por grupo de gerenciamento, use managementgroups em vez de subscriptions. Para consultar o locatário inteiro, omita as propriedades managementgroups e subscriptions do corpo da solicitação.

No corpo da solicitação de cada chamada à API REST, há uma variável usada que você precisa substituir pelo seu valor:

{subscriptionID}: substitua por sua ID da assinatura

Execute sua primeira consulta do Azure Resource Graph usando a API REST e o ponto de extremidade resources:
- URI da API REST
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- Corpo da solicitação
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5"
}
```
Observação

Por essa consulta de exemplo não fornecer um modificador de classificação, como order by, executar essa consulta várias vezes provavelmente produzirá um conjunto diferente de recursos por solicitação.
Atualize a chamada ao ponto de extremidade resouces e altere a consulta para order by a propriedade Name:
- URI da API REST
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- Corpo da solicitação
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5 | order by name asc"
}
```
Observação

Assim como ocorre com a primeira consulta, executar esta consulta várias vezes provavelmente produzirá um conjunto diferente de recursos por solicitação. A ordem dos comandos de consulta é importante. Neste exemplo, o order by vem após o limit. Essa ordem de comando limita primeiro os resultados da consulta e os ordena.

Atualize a chamada ao ponto de extremidade resources e altere a consulta para primeiro order by a propriedade Name e então limit os cinco principais resultados:

URI da API REST

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01

Corpo da solicitação

{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | order by name asc | limit 5"
}

Quando a consulta final for executada várias vezes, supondo que nada em seu ambiente esteja sendo alterado, os resultados retornados serão consistentes e ordenados segundo a propriedade Name, mas ainda limitados aos cinco primeiros resultados.

Para obter mais exemplos de chamadas à API REST para o Azure Resource Graph, confira os Exemplos de REST do Azure Resource Graph.

Limpar os recursos

A API REST não tem bibliotecas nem módulos para desinstalar. Se você tiver instalado uma ferramenta como ARMClient para fazer as chamadas e não precisar mais dela, você poderá desinstalar a ferramenta agora.

Próximas etapas

Neste guia de início rápido, você chamou o ponto de extremidade da API REST do Resource Graph e executou sua primeira consulta. Para saber mais sobre a linguagem do Resource Graph, prossiga para a página de detalhes da linguagem de consulta.

Obter mais informações sobre a linguagem de consulta

Share via