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
    

Funções de avaliação de permissões RBAC no Azure Resource Graph

Azure Resource Graph (ARG) fornece duas funções que permitem avaliar se a identidade de consulta atual tem permissões específicas sobre recursos individuais:

• hasPermission()
• hasDataPermission()

Estas funções retornam um valor booleano (1 ou 0) por recurso e permitem cenários como filtrar ou resumir recursos com base no acesso.

hasPermission()

A hasPermission() função avalia se a identidade da consulta tem uma permissão específica no plano de controlo sobre um recurso.

Use o seguinte formato para hasPermission():

hasPermission('<permission-string>')

A hasPermission() função utiliza atribuições RBAC eficazes para a identidade de consulta e avalia por linha de recursos. A função devolve 1 se a identidade tiver a permissão especificada sobre o recurso, e 0 se a identidade não tiver.

Exemplo Verificar o acesso de escrita aos registos de contentores do Azure

resources
| where type =~ 'Microsoft.ContainerRegistry/registries'
| extend canPush = hasPermission('Microsoft.ContainerRegistry/registries/push/write')

Neste exemplo, cada recurso do registo de contentores é avaliado individualmente e canPush indica se a identidade da consulta pode realizar a ação de escrita especificada nesse recurso. Os resultados podem ser usados para filtragem, agregação ou resumo com base no valor devolvido.

hasDataPermission()

Avalia hasDataPermission() se a identidade da consulta tem uma permissão específica no plano de dados sobre um recurso.

Use o seguinte formato para hasDataPermission():

hasDataPermission('<permission-string>')

A hasDataPermission() função utiliza uma avaliação eficaz de acesso ao plano de dados para a identidade da consulta e é avaliada por linha de recursos. A função devolve 1 se a identidade tiver a permissão especificada no plano de dados sobre o recurso, e 0 se a identidade não tiver.

Exemplo: Verifique o acesso de leitura do plano de dados ao Armazenamento de Blobs do Azure

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| extend canReadBlobs = hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read')

Neste exemplo, cada recurso de armazenamento é avaliado individualmente. A hasDataPermissions() função verifica se a identidade da consulta tem as permissões data-plne especificadas. O valor devolvido pode ser usado para filtragem, resumo ou relatório.

Exemplo: Verifique o acesso de leitura do plano de dados ao Armazenamento de Blobs do Azure com filtragem

resources
| where type =~ 'Microsoft.Storage/storageAccounts'
| where hasDataPermission('Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read') == 1

Este exemplo devolve apenas as contas de armazenamento onde a identidade de consulta tem acesso à leitura de blob.

Limitações importantes

Estas funções são frequentemente confundidas com cenários de descoberta de funções ou permissões. As seguintes limitações são importantes de compreender:

• As hasPermission() funções e hasDataPermission() não determinam que permissões uma definição de função concede.
• Não podem ser usados para consultar ou filtrar recursos microsoft.authorization/roledefinitions .
• Não se destinam a responder a perguntas como:
  • "Que papéis concedem esta permissão?"
  • "Que ações inclui esta definição de função?"

Próximos passos

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