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

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.

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

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.

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:

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.

Â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.

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.