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
• inner
• leftouter
• fullouter

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 mistura as colunas e quaisquer nomes duplicados das colunas da tabela unida, ResourceContainers neste exemplo, são acrescentados a 1. Como a tabela ResourceContainers tem tipos tanto para subscrições como para grupos de recursos, qualquer um dos tipos pode ser usado para se juntar ao recurso a partir 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. O passo seguinte utiliza join a fusão dos resultados com os ResourceContainers , onde o tipo é uma subscrição numa propriedade que está tanto na primeira tabela project como na tabela projectunida. A renomeação do campo evita join adicioná-lo como name1 , pois a propriedade já é 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 funcionalidade de pré-visualização , alguns dos tipos de recursos no Resource Graph têm mais propriedades relacionadas com tipos disponíveis para consultar para além das propriedades fornecidas pelo Azure Resource Manager. Este conjunto de valores, conhecido como propriedades estendidas, existe num tipo de recurso suportado em 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 funcionalidade de pré-visualização, uma consulta partilhada pode ser acedida diretamente numa consulta de Grafo 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 partilhada é o ID de Recurso da consulta partilhada na página de Definiçõ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 apresentam 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 suportar a experiência do portal Open Consult , o Azure Resource Graph Explorer tem um limite global mais elevado do que o Resource Graph SDK.

Escopo da consulta

O âmbito das subscrições ou grupos de gestão dos quais os recursos são devolvidos por uma consulta passa por defeito a uma lista de subscrições com base no contexto do utilizador autorizado. Se não estiver definido um grupo de gestão ou uma lista de subscrições, o âmbito da consulta inclui todos os recursos e inclui recursos delegados pelo 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
  

• Órgão 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): Devolve as atribuições para o âmbito dado e para todos os escopos filhos.
• AtScopeAndAbove: Devolve atribuições para o âmbito dado e para todos os escopos pais, mas não para os filhos.
• AtScopeAboveAndBelow: Devolve atribuições para o âmbito dado, todos os escopos pais e todos os escopos filhos.
• AtScopeExact: Retorna atribuições apenas para o âmbito dado; Não estão incluídos os endoscopos parentais ou filhos.

Exemplo: Obtenha todas as atribuições de políticas no grupo de gestão myMG e nos escopos Tenant Root (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íticas na subscrição mySubscriptionId , grupo de gestão e escopos Tenant Root.

• 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"]
  }
  

Personagens de fuga

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 envolve 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 inversa (\) como personagem de fuga.

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

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

  • cmd: Não escapes à personagem do cifrão ().$

  • PowerShell: Use um backtick (`) como personagem 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

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