Compreender a linguagem de consulta do Azure Resource Graph

A linguagem de consulta para o Azure Resource Graph dá suporte a muitos operadores e funções. Cada um funciona e opera com base na Kusto Query Language (KQL). Para saber mais sobre a linguagem de consulta utilizada pelo Resource Graph, comece com o tutorial do KQL.

Este artigo aborda os componentes de linguagem suportados pelo Resource Graph:

• Compreender a linguagem de consulta do Azure Resource Graph
  • Tabelas do Gráfico de Recursos
  • Propriedades estendidas
  • Elementos de linguagem personalizados do Gráfico de Recursos
    • Sintaxe de consulta compartilhada (visualização)
  • Elementos de linguagem KQL suportados
    • Operadores tabulares/de nível superior suportados
  • Escopo da consulta
  • Personagens de fuga
  • Passos seguintes

Tabelas do Gráfico de Recursos

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

As tabelas do Resource Graph suportam os join sabores:

• innerunique
• interior
• Exterior esquerdo
• Exterior completo

Tabela do Gráfico de Recursos	Podem join outras tabelas?	Description
AssessoramentoRecursos	Sim	Inclui recursos relacionados ao Microsoft.Advisor.
AlertasGestãoRecursos	Sim	Inclui recursos relacionados ao Microsoft.AlertsManagement.
AppServiceRecursos	Sim	Inclui recursos relacionados ao Microsoft.Web.
AutorizaçãoRecursos	Sim	Inclui recursos relacionados ao Microsoft.Authorization.
AWSResources	Sim	Inclui recursos relacionados ao Microsoft.AwsConnector.
AzureBusinessContinuityRecursos	Sim	Inclui recursos relacionados ao Microsoft.AzureBusinessContinuity.
CaosRecursos	Sim	Inclui recursos relacionados ao Microsoft.Chaos.
ComunidadeGaleria de Recursos	Sim	Inclui recursos relacionados ao Microsoft.Compute.
Recursos de computação	Sim	Inclui recursos relacionados a Conjuntos de Dimensionamento de Microsoft.Compute Máquinas Virtuais.
DesktopVirtualizaçãoRecursos	Sim	Inclui recursos relacionados ao Microsoft.DesktopVirtualization.
DnsRecursos	Sim	Inclui recursos relacionados ao Microsoft.Network.
EdgeOrderResources	Sim	Inclui recursos relacionados ao Microsoft.EdgeOrder.
ElasticsanResources	Sim	Inclui recursos relacionados ao Microsoft.ElasticSan.
ExtendedLocationRecursos	Sim	Inclui recursos relacionados ao Microsoft.ExtendedLocation.
RecursosRecurso	Sim	Inclui recursos relacionados ao Microsoft.Features.
GuestConfigurationRecursos	Sim	Inclui recursos relacionados ao Microsoft.GuestConfiguration.
HealthResourceChanges	Sim	Inclui recursos relacionados ao Microsoft.Resources.
Recursos para a saúde	Sim	Inclui recursos relacionados ao Microsoft.ResourceHealth.
InsightsRecursos	Sim	Inclui recursos relacionados ao Microsoft.Insights.
IoTSecurityResources	Sim	Inclui recursos relacionados a Microsoft.IoTSecurity e Microsoft.IoTFirmwareDefense.
KubernetesConfiguraçãoRecursos	Sim	Inclui recursos relacionados ao Microsoft.KubernetesConfiguration.
KustoRecursos	Sim	Inclui recursos relacionados ao Microsoft.Kusto.
ManutençãoRecursos	Sim	Inclui recursos relacionados ao Microsoft.Maintenance.
Serviços gerenciadosRecursos	Sim	Inclui recursos relacionados ao Microsoft.ManagedServices.
MigrarRecursos	Sim	Inclui recursos relacionados ao Microsoft.OffAzure.
Recursos de rede	Sim	Inclui recursos relacionados ao Microsoft.Network.
Recursos Orbitais	Sim	Inclui recursos relacionados ao Microsoft.Orbital.
PatchAssessmentRecursos	Sim	Inclui recursos relacionados à avaliação Microsoft.Compute de patches das Máquinas Virtuais do Azure e Microsoft.HybridCompute ao .
PatchInstallationResources	Sim	Inclui recursos relacionados à instalação Microsoft.Compute do patch de Máquinas Virtuais do Azure e Microsoft.HybridComputeao .
PolíticaRecursos	Sim	Inclui recursos relacionados ao Microsoft.PolicyInsights.
RecuperaçãoServiçosRecursos	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	Sim	Inclui tipos de recursos e dados do grupo de gerenciamento (Microsoft.Management/managementGroups), da assinatura (Microsoft.Resources/subscriptions) e do grupo de recursos (Microsoft.Resources/subscriptions/resourcegroups).
Recursos	Sim	A tabela padrão se uma tabela não estiver definida na consulta. A maioria dos tipos de recursos e propriedades do Resource Manager estão aqui.
Recursos de Segurança	Sim	Inclui recursos relacionados ao Microsoft.Security.
ServiceFabricRecursos	Sim	Inclui recursos relacionados ao Microsoft.ServiceFabric.
ServiceHealthRecursos	Sim	Inclui recursos relacionados ao Microsoft.ResourceHealth/events.
SpotResources	Sim	Inclui recursos relacionados ao Microsoft.Compute.
SuporteRecursos	Sim	Inclui recursos relacionados ao Microsoft.Support.
TagsRecursos	Sim	Inclui recursos relacionados ao Microsoft.Resources/tagnamespaces.

Para obter uma lista de tabelas que inclui tipos de recursos, vá para Tabela do Gráfico de Recursos do Azure e referência de tipo de recurso.

Nota

Resources é a tabela padrão. Ao consultar a Resources tabela, não é necessário fornecer o nome da tabela, a menos que join ou union sejam usados. Mas a prática recomendada é sempre incluir a tabela inicial na consulta.

Para descobrir quais tipos de recursos estão disponíveis em cada tabela, use o Resource Graph Explorer no portal. Como alternativa, use uma consulta como <tableName> | distinct type para obter uma lista de tipos de recursos suportados pela tabela do Gráfico de Recursos que existem em seu ambiente.

A consulta a seguir mostra um arquivo join. O resultado da consulta combina as colunas e todos os nomes de colunas duplicados da tabela associada, ResourceContainers neste exemplo, são acrescentados com 1. Como a tabela ResourceContainers tem tipos para assinaturas e grupos de recursos, qualquer tipo pode ser usado para ingressar no recurso da Resources tabela.

Resources
| join ResourceContainers on subscriptionId
| limit 1

A consulta a seguir mostra um uso mais complexo do join. Primeiro, a consulta usa project para obter os campos do tipo de recurso Cofre da Resources Chave do Azure. A próxima etapa usa join para mesclar os resultados com ResourceContainers onde o tipo é uma assinatura em uma propriedade que está tanto na primeira tabela project quanto na tabela projectassociada. A renomeação de join campo evita adicioná-lo como nome1 , uma vez que a propriedade já está projetada a partir de Resources. O resultado da consulta é um cofre de chave única exibindo o tipo, o nome, o local e o grupo de recursos do cofre de chaves, juntamente 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

Nota

Ao limitar os join resultados 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 de visualização , alguns dos tipos de recursos no Gráfico de Recursos têm mais propriedades relacionadas ao tipo disponíveis para consulta além das propriedades fornecidas pelo Gerenciador de Recursos do Azure. Esse conjunto de valores, conhecido como propriedades estendidas, existe em um tipo de recurso suportado no properties.extended. Para mostrar tipos de recursos com propriedades estendidas, use a seguinte consulta:

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

Exemplo: Obter 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 Gráfico de Recursos

Sintaxe de consulta compartilhada (visualização)

Como um recurso de visualização, uma consulta compartilhada pode ser acessada diretamente em uma consulta do Gráfico de Recursos. Esse cenário torna possível criar consultas padrão como consultas compartilhadas e reutilizá-las. Para chamar uma consulta compartilhada dentro de uma consulta do Gráfico de Recursos, use a {{shared-query-uri}} sintaxe. O URI da consulta compartilhada é a ID do recurso da consulta compartilhada na página 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. Esta consulta é a mesma criada em Tutorial: Criar e partilhar uma consulta.

Nota

Não é possível salvar uma consulta que faça referência a uma consulta compartilhada como uma consulta compartilhada.

Exemplo 1: Use apenas a consulta compartilhada:

Os resultados desta consulta do Gráfico de Recursos 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: Inclua a consulta compartilhada como parte de uma consulta maior:

Essa consulta primeiro usa 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 de linguagem KQL suportados

O Resource Graph suporta um subconjunto de tipos de dados KQL, funções escalares, operadores escalares e funções de agregação. Operadores tabulares específicos são suportados pelo Resource Graph, alguns dos quais têm comportamentos diferentes.

Operadores tabulares/de nível superior suportados

Aqui está a lista de operadores tabulares KQL suportados pelo Resource Graph com exemplos específicos:

KQL	Consulta de exemplo do Gráfico de Recursos	Notas
count	Contar cofres de chaves
distinto	Mostrar recursos que contêm armazenamento
estender	Contar máquinas virtuais por tipo de SO
aderir	Cofre de chaves com nome de subscrição	Junte-se aos sabores suportados: innerunique, inner, leftouter e fullouter. Limite de três join em uma única consulta, uma das quais pode ser uma tabela joincruzada. Se todo o uso de tabelas join cruzadas estiver entre Resource e ResourceContainers, três tabelas join cruzadas serão permitidas. Estratégias de associação personalizadas, como associação de transmissão, não são permitidas. Para quais tabelas podem usar join, vá para Tabelas do Gráfico de Recursos.
limit	Listar todos os endereços IP públicos	Sinónimo de take. Não funciona com Skip.
MVEXPAND		Operador legado, use mv-expand em vez disso. RowLimit máximo de 2.000. O padrão é 128.
mv-expandir	Listar o Azure Cosmos DB com locais de gravação específicos	RowLimit máximo de 2.000. O padrão é 128. Limite de 3 mv-expand em uma única consulta.
order	Listar recursos ordenados por nome	Sinónimo de sort
analisar	Obter redes virtuais e sub-redes de interfaces de rede	É ideal acessar as propriedades diretamente se elas existirem, em vez de usar parseo .
projeto	Listar recursos ordenados por nome
projeto-fora	Remover colunas dos resultados
sort	Listar recursos ordenados por nome	Sinónimo de order
resumir	Contar recursos do Azure	Apenas primeira página simplificada
tomar	Listar todos os endereços IP públicos	Sinónimo de limit. Não funciona com Skip.
Início	Mostrar as primeiras cinco máquinas virtuais por nome e por tipo de SO
União	Combinar resultados de duas consultas em um único resultado	Mesa única permitida: | union [kind= inner|outer] [withsource=ColumnName] Table. Limite de três union pernas em uma única consulta. Não é permitida a resolução difusa de mesas de union perna. Pode ser usado dentro de uma única tabela ou entre as tabelas Resources e ResourceContainers .
em que	Mostrar recursos que contêm armazenamento

Há um limite padrão de três join e três mv-expand operadores em uma única consulta do SDK do Resource Graph. Pode solicitar um aumento destes limites para o seu inquilino através da Ajuda + suporte.

Para dar suporte à experiência do portal Open Query, o Azure Resource Graph Explorer tem um limite global mais alto do que o SDK do Resource Graph.

Nota

Não é possível fazer referência a uma tabela como tabela correta várias vezes, o que excede o limite de 1. Se você fizer isso, você receberá um erro com o código DisallowedMaxNumberOfRemoteTables.

Âmbito de 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 definido, o escopo da consulta será todos os recursos e incluirá 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 REST API managementGroups usa a ID do grupo de gerenciamento, que é diferente do nome do grupo de gerenciamento. Quando managementGroups especificado, os recursos das primeiras 10.000 assinaturas na hierarquia de grupo de gerenciamento especificada ou sob ela são incluídos. managementGroups não pode ser usado ao mesmo tempo que subscriptionso .

Exemplo: Consultar todos os recursos dentro da hierarquia do grupo de gerenciamento nomeado My Management Group com ID myMG.

• URI da API REST

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

• Corpo do Pedido

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

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

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

Nota

Para usar o AuthorizationScopeFilter parâmetro, certifique-se de usar a versão 2021-06-01-preview ou posterior da API em suas solicitações.

Exemplo: Obtenha todas as atribuições de política no grupo de gerenciamento myMG e nos escopos Raiz do Locatário (pai).

• URI da API REST

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

• Solicitar amostra do corpo

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

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

• URI da API REST

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

• Solicitar amostra do corpo

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

Carateres de escape

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

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

  Exemplo de consulta que encapsula a propriedade odata.type:

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

• Cifrão ($): Fuja do caractere no nome da propriedade. O caractere de escape usado depende do shell que executa o Resource Graph.

  • Bash: Use uma barra invertida (\) como o caractere de fuga.

    Exemplo de consulta que escapa da propriedade $type em Bash:

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

  • cmd: Não escape do caractere cifrão ($).

  • PowerShell: Use um backtick (`) como o caractere de escape.

    Exemplo de consulta que escapa da propriedade $type no PowerShell:

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

Próximos passos

• Linguagem de consulta do Azure Resource Graph: Consultas iniciais e consultas avançadas.
• Saiba mais sobre como explorar os recursos do Azure.