Noções básicas sobre a linguagem de consulta do Azure Resource Graph
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 máximo de 2.000. O padrão é 128. |
|
| mv-expand | Listar o Azure Cosmos DB com localizações de gravação específicas | RowLimit máximo de 2.000. O padrão é 128. Há um limite de 3 mv-expand em uma única consulta. |
| ordem | 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-01Corpo 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-previewExemplo 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-previewExemplo 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.\$typecmd: 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
- Consultas iniciais e Consultas avançadas de linguagem de consulta do Azure Resource Graph.
- Saiba mais sobre como explorar recursos do Azure.