Noções básicas sobre a linguagem de consulta do Azure Resource Graph

  • Artigo

A linguagem de consulta para o Azure Resource Graph é compatível a diversos operadores e funções. Cada um funciona e opera com base na linguagem de consulta do Kusto (KQL). Para saber mais sobre a linguagem de consulta usada pelo Resource Graph, comece pelo tutorial para KQL.

Este artigo aborda os componentes de linguagem com suporte no Resource Graph:

Tabelas do Resource Graph

O Resource Graph oferece várias tabelas para os dados que ele armazena sobre os tipos de recursos do Azure Resource Manager e suas propriedades. As tabelas do Resource Graph podem ser usadas com o operador join para obter propriedades dos tipos de recursos relacionados.

As tabelas do Resource Graph dão suporte aos tipos de join:

Tabela do Resource Graph Pode join outras tabelas? Descrição
AdvisorResources Sim Inclui recursos relacionados ao Microsoft.Advisor.
AlertsManagementResources Sim Inclui recursos relacionados ao Microsoft.AlertsManagement.
AppServiceResources Sim Inclui recursos relacionados ao Microsoft.Web.
AuthorizationResources Sim Inclui recursos relacionados ao Microsoft.Authorization.
AWSResources Sim Inclui recursos relacionados ao Microsoft.AwsConnector.
AzureBusinessContinuityResources Sim Inclui recursos relacionados ao Microsoft.AzureBusinessContinuity.
ChaosResources Sim Inclui recursos relacionados ao Microsoft.Chaos.
CommunityGalleryResources Sim Inclui recursos relacionados ao Microsoft.Compute.
ComputeResources Yes Inclui recursos relacionados aos Conjuntos de Dimensionamento de Máquinas Virtuais Microsoft.Compute.
DesktopVirtualizationResources Yes Inclui recursos relacionados ao Microsoft.DesktopVirtualization.
DnsResources Sim Inclui recursos relacionados ao Microsoft.Network.
EdgeOrderResources Sim Inclui recursos relacionados ao Microsoft.EdgeOrder.
ElasticsanResources Sim Inclui recursos relacionados ao Microsoft.ElasticSan.
ExtendedLocationResources Sim Inclui recursos relacionados ao Microsoft.ExtendedLocation.
FeatureResources Sim Inclui recursos relacionados ao Microsoft.Features.
GuestConfigurationResources Sim Inclui recursos relacionados ao Microsoft.GuestConfiguration.
HealthResourceChanges Sim Inclui recursos relacionados ao Microsoft.Resources.
HealthResources Sim Inclui recursos relacionados ao Microsoft.ResourceHealth.
InsightsResources Sim Inclui recursos relacionados ao Microsoft.Insights.
IoTSecurityResources Sim Inclui recursos relacionados a Microsoft.IoTSecurity e Microsoft.IoTFirmwareDefense.
KubernetesConfigurationResources Sim Inclui recursos relacionados ao Microsoft.KubernetesConfiguration.
KustoResources Sim Inclui recursos relacionados ao Microsoft.Kusto.
MaintenanceResources Sim Inclui recursos relacionados ao Microsoft.Maintenance.
ManagedServicesResources Sim Inclui recursos relacionados ao Microsoft.ManagedServices.
MigrateResources Sim Inclui recursos relacionados ao Microsoft.OffAzure.
NetworkResources Sim Inclui recursos relacionados ao Microsoft.Network.
OrbitalResources Sim Inclui recursos relacionados ao Microsoft.Orbital.
PatchAssessmentResources Sim Inclui recursos relacionados à avaliação de patches Microsoft.Compute e Microsoft.HybridCompute de máquinas virtuais do Azure.
PatchInstallationResources Sim Inclui recursos relacionados à instalação de patches Microsoft.Compute e Microsoft.HybridCompute de máquinas virtuais do Azure.
PolicyResources Yes Inclui recursos relacionados ao Microsoft.PolicyInsights.
RecoveryServicesResources Sim Inclui recursos relacionados a Microsoft.DataProtection e Microsoft.RecoveryServices.
ResourceChanges Sim Inclui recursos relacionados ao Microsoft.Resources.
ResourceContainerChanges Sim Inclui recursos relacionados ao Microsoft.Resources.
ResourceContainers Yes Inclui dados e tipos de recursos do grupo de gerenciamento (Microsoft.Management/managementGroups), assinatura (Microsoft.Resources/subscriptions) e grupo de recursos (Microsoft.Resources/subscriptions/resourcegroups).
Recursos Sim A tabela padrão se nenhuma tabela for definida na consulta. A maioria dos tipos de recursos e propriedades do Resource Manager estão aqui.
SecurityResources Sim Inclui recursos relacionados ao Microsoft.Security.
ServiceFabricResources Sim Inclui recursos relacionados ao Microsoft.ServiceFabric.
ServiceHealthResources Sim Inclui recursos relacionados ao Microsoft.ResourceHealth/events.
SpotResources Sim Inclui recursos relacionados ao Microsoft.Compute.
SupportResources Sim Inclui recursos relacionados ao Microsoft.Support.
TagsResources Sim Inclui recursos relacionados ao Microsoft.Resources/tagnamespaces.

Para obter uma lista de tabelas que incluem tipos de recursos, vá para Tabela e referência de tipo de recurso do Azure Resource Graph.

Observação

Resources é a tabela padrão. Durante a consulta da tabela Resources, não é necessário fornecer o nome da tabela, salvo se join ou union forem usados. No entanto, a prática recomendada é incluir sempre a tabela inicial na consulta.

Para descobrir quais tipos de recursos estão disponíveis em cada tabelam use o Resource Graph Explorer no portal. Como alternativa, use uma consulta como <tableName> | distinct type para obter uma lista dos tipos de recursos que a tabela do Resource Graph fornecida dá suporte e que existem em seu ambiente.

A consulta a seguir mostra uma consulta join simples. O resultado da consulta combina as colunas e quaisquer nomes de coluna duplicados da tabela unida, ResourceContainers neste exemplo, são seguidos do número 1. Como a tabela ResourceContainers contém tipos para grupos de recursos e assinaturas, qualquer tipo pode ser usado para a junção com o recurso a partir da tabela Resources.

Resources
| join ResourceContainers on subscriptionId
| limit 1

A consulta a seguir mostra um uso mais complexo da consulta join. Primeiro, a consulta usa project para obter os campos de Resources para o tipo de recurso de cofres do Azure Key Vault. A próxima etapa usa join para mesclar os resultados com ResourceContainers, em que o tipo é uma assinatura em uma propriedade que está tanto em project da primeira tabela quanto em project da tabela unida. Renomear o campo evita que join o adicione como name1, já que a propriedade é projetada a partir de Resources. O resultado da consulta é um cofre de chaves único que exibe o tipo, o nome, o local e o grupo de recursos do cofre de chaves, com o nome da assinatura em que ele está.

Resources
| where type == 'microsoft.keyvault/vaults'
| project name, type, location, subscriptionId, resourceGroup
| join (ResourceContainers | where type=='microsoft.resources/subscriptions' | project SubName=name, subscriptionId) on subscriptionId
| project type, name, location, resourceGroup, SubName
| limit 1

Observação

Quando os resultados de join são limitados com project, a propriedade usada por join para relacionar as duas tabelas, subscriptionId no exemplo acima, deve ser incluída em project.

Propriedades estendidas

Como um recurso em versão prévia, alguns tipos de recursos no Resource Graph têm propriedades adicionais relacionadas ao tipo que são disponíveis para consulta, além das propriedades fornecidas pelo Azure Resource Manager. Esse conjunto de valores, conhecido como Propriedades estendidas, existe em um tipo de recurso com suporte no properties.extended. Para ver tipos de recursos com propriedades estendidas, use a seguinte consulta:

Resources
| where isnotnull(properties.extended)
| distinct type
| order by type asc

Exemplo: obter a contagem de máquinas virtuais por instanceView.powerState.code:

Resources
| where type == 'microsoft.compute/virtualmachines'
| summarize count() by tostring(properties.extended.instanceView.powerState.code)

Elementos de linguagem personalizados do Resource Graph

Sintaxe de consulta compartilhada (versão prévia)

Como uma versão prévia do recurso, uma consulta compartilhada pode ser acessada diretamente em uma consulta do Resource Graph. Esse cenário possibilita criar consultas padrão como consultas compartilhadas e reutilizá-las. Para chamar uma consulta compartilhada dentro de uma consulta do Resource Graph, use a sintaxe {{shared-query-uri}}. O URI da consulta compartilhada é a ID de recurso da consulta compartilhada na página de Configurações dessa consulta. Neste exemplo, nosso URI de consulta compartilhada é /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS. Esse URI aponta para a assinatura, o grupo de recursos e o nome completo da consulta compartilhada que queremos referenciar em outra consulta. Essa consulta é a mesma criada no tutorial: criar e compartilhar uma consulta.

Observação

Você não pode salvar como consulta compartilhada uma consulta que faça referência a uma consulta compartilhada.

Exemplo 1: usar somente a consulta compartilhada:

Os resultados dessa consulta do Resource Graph são os mesmos que a consulta armazenada na consulta compartilhada.

{{/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS}}

Exemplo 2: incluir a consulta compartilhada como parte de uma consulta mais ampla:

Essa consulta usa primeiro a consulta compartilhada e, em seguida, usa limit para restringir ainda mais os resultados.

{{/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/SharedQueries/providers/Microsoft.ResourceGraph/queries/Count VMs by OS}}
| where properties_storageProfile_osDisk_osType =~ 'Windows'

Elementos da linguagem KQL com suporte

O Resource Graph aceita todos os tipos de dados, funções escalares, operadores escalares e funções de agregação da linguagem KQL. O Resource Graph dá suporte a operadores de tabela específicos e alguns destes operadores apresentam comportamentos diferentes.

Operadores de tabela/nível superior com suporte

A seguir está a lista de operadores de tabela da linguagem KQL compatível com o Resource Graph com exemplos específicos:

KQL Consulta de exemplo do Resource Graph Observações
contagem Contar cofres de chaves
distinct Mostrar recursos que contêm o armazenamento
extend Contagem de máquinas virtuais por tipo de sistema operacional
join Cofre de chaves com o nome da assinatura Tipos de união com suporte: innerunique, inner, leftouter e fullouter. Limite de três join em apenas uma consulta, sendo que um pode ser um join de tabela cruzada. Se toda a utilização de tabela cruzada join estiver entre Resource e ResourceContainers, três join de tabela cruzada serão permitidos. Estratégias de união personalizadas, como união difundida, não são permitidas. Para as tabelas que podem usar join, consulte Tabelas do Resource Graph.
limite Listar todos os endereços de IP Sinônimo de take. Não funciona com Skip.
mvexpand Operador herdado, use mv-expand como substituto. RowLimit com limite máximo de 400. O padrão é 128.
mv-expand Listar o Azure Cosmos DB com localizações de gravação específicas RowLimit com limite máximo de 400. O padrão é 128. Limite de 2 mv-expand em uma única consulta.
order Listar recursos classificados por nome Sinônimo de sort
parse Obter redes virtuais e sub-redes de interfaces de rede O ideal é acessar as propriedades diretamente se elas existirem em vez de usar parse.
project Listar recursos classificados por nome
project-away Remover colunas dos resultados
sort Listar recursos classificados por nome Sinônimo de order
summarize Recursos do Count Azure Somente a primeira página simplificada
take Listar todos os endereços de IP Sinônimo de limit. Não funciona com Skip.
início Mostrar as primeiras cinco máquinas virtuais por nome e tipo do sistema operacional
union Combinar resultados de duas consultas em um único resultado Tabela individual permitida: | union [kind= inner|outer] [withsource=ColumnName] Table. Há um limite de três expressões de union para cada consulta. A resolução difusa de tabelas da expressão de union não é permitida. Elas podem ser usadas para apenas uma tabela ou entre as tabelas Resources e ResourceContainers.
where Mostrar recursos que contêm o armazenamento

Há um limite padrão de três operadores join e três mv-expand em cada consulta do SDK do Resource Graph. Você pode solicitar um aumento desses limites para seu locatário por meio de Ajuda + Suporte.

Para auxiliar na experiência de Consulta em aberto do portal, o Azure Resource Graph Explorer tem um limite global mais alto do que o SDK do Resource Graph.

Observação

Você não pode referenciar uma tabela como tabela correta várias vezes, o que excede o limite de 1. Se você fizer isso, receberá um erro com o código DisallowedMaxNumberOfRemoteTables.

Escopo da consulta

O escopo das assinaturas ou grupos de gerenciamento dos quais os recursos são retornados por uma consulta assume como padrão uma lista de assinaturas com base no contexto do usuário autorizado. Se um grupo de gerenciamento ou uma lista de assinaturas não estiver definida, o escopo da consulta serão todos os recursos e incluem recursos delegados do Azure Lighthouse.

A lista de assinaturas ou grupos de gerenciamento a serem consultados pode ser definida manualmente para alterar o escopo dos resultados. Por exemplo, a propriedade managementGroups da API REST usa a ID do grupo de gerenciamento, que é diferente do nome do grupo de gerenciamento. Quando managementGroups é especificado, são incluídos os recursos das primeiras 10.000 assinaturas na ou sob a hierarquia do grupo de gerenciamento especificado. managementGroups não pode ser usado ao mesmo tempo que subscriptions.

Exemplo: consultar todos os recursos na hierarquia do grupo de gerenciamento chamado My Management Group com a ID myMG.

  • URI da API REST

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

  • Corpo da solicitação

    {
  "query": "Resources | summarize count()",
  "managementGroups": ["myMG"]
}

O parâmetro AuthorizationScopeFilter permite listar atribuições do Azure Policy e atribuições de função do RBAC do Azure (Controle de acesso baseado em função) na tabela AuthorizationResources herdadas de escopos superiores. O parâmetro AuthorizationScopeFilter aceita os seguintes valores para as tabelas PolicyResources e AuthorizationResources :

  • AtScopeAndBelow (padrão, se não especificado): retorna atribuições de política para o escopo fornecido e todos os escopos filho.
  • AtScopeAndAbove: retorna atribuições de política para o escopo especificado e todos os escopos pai, mas não para escopos filho.
  • AtScopeAboveAndBelow: retorna atribuições para o escopo determinado, todos os escopos pai e todos os escopos filho.
  • AtScopeExact: retorna atribuições de política somente para o escopo determinado. Nenhum escopo pai ou filho está incluído.

Observação

Para usar o parâmetro AuthorizationScopeFilter, faça referência à versão 2021-06-01-preview ou posterior da API em suas solicitações.

Exemplo: obtenha todas as atribuições de política nos escopos do grupo de gerenciamento myMG e na raiz de locatário (pai).

  • URI da API REST

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

  • Exemplo de corpo da solicitação

    {
  "options": {
    "authorizationScopeFilter": "AtScopeAndAbove"
  },
  "query": "PolicyResources | where type =~ 'Microsoft.Authorization/PolicyAssignments'",
  "managementGroups": ["myMG"]
}

Exemplo: obtenha todas as atribuições de política na assinatura mySubscriptionId, no grupo de gerenciamento e nos escopos raiz do locatário.

  • URI da API REST

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

  • Exemplo de corpo da solicitação

    {
  "options": {
    "authorizationScopeFilter": "AtScopeAndAbove"
  },
  "query": "PolicyResources | where type =~ 'Microsoft.Authorization/PolicyAssignments'",
  "subscriptions": ["mySubscriptionId"]
}

Caracteres de escape

Alguns nomes de propriedade, como aqueles que incluem . ou $, devem ser encapsulados ou precedidos por um caractere de escape na consulta ou o nome da propriedade é interpretado incorretamente e não fornece os resultados esperados.

  • Ponto (.): encapsula o nome da propriedade ['propertyname.withaperiod'] usando colchetes.

    Exemplo de consulta que encapsula a propriedade odata.type:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.['odata.type']

  • Símbolo do dólar ($): usa o caractere de escape no nome da propriedade. O caractere de escape usado depende do shell onde o Resource Graph é executado.

    • Bash: usa uma barra invertida (\) como o caractere de escape.

      Exemplo de consulta que usa o caractere de escape na propriedade $type no Bash:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.\$type

    • cmd: não usa o caractere de escape no caractere de símbolo do dólar ($).

    • PowerShell: usa um acento grave (`) como o caractere de escape.

      Exemplo de consulta que usa o caractere de escape na propriedade $type no PowerShell:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.`$type

Próximas etapas