Noções básicas sobre a linguagem de consulta do Azure Resource Graph

A linguagem de consulta do Azure Resource Graph dá suporte a muitos 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:

• Entender a linguagem de consulta do Azure Resource Graph
  • Tabelas do Resource Graph
  • Propriedades estendidas
  • Elementos de linguagem personalizados do Resource Graph
    • Sintaxe de consulta compartilhada (versão prévia)
  • Elementos da linguagem KQL com suporte
    • Operadores tabulares/de nível superior com suporte
  • Escopo da consulta
  • Personagens de fuga
  • Próximas Etapas 

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:

• innerunique
• inner
• leftouter
• fullouter

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.

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 mistura as colunas e quaisquer nomes duplicados de colunas da tabela unida, ResourceContainers neste exemplo, são adicionados a 1. Como a tabela ResourceContainers possui tipos tanto para assinaturas quanto para grupos de recursos, qualquer um dos tipos pode ser usado para se unir ao recurso a partir da Resources tabela.

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. O próximo passo é para join mesclar os resultados com ResourceContainers , onde o tipo é uma assinatura em uma propriedade que está tanto na primeira tabela project quanto na tabela projectunida. A renomeação do campo evita join adicioná-lo como name1 , já que a propriedade já é 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

Propriedades estendidas

Como recurso de pré-visualização , alguns dos tipos de recursos no Resource Graph possuem mais propriedades relacionadas a tipos 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 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 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 recurso de pré-visualização, uma consulta compartilhada pode ser acessada diretamente em uma consulta de Grafo de Recursos. 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 é o ID de Recurso da consulta compartilhada na página de Configurações para essa 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.

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 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 de tabela/nível superior com suporte

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

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 suportar a experiência do portal Open Consult , o Azure Resource Graph Explorer possui um limite global maior do que o Resource Graph SDK.

Escopo da consulta

O escopo das assinaturas ou grupos de gerenciamento dos quais os recursos são retornados por uma consulta é padrão para uma lista de assinaturas baseada no contexto do usuário autorizado. Se um grupo de gerenciamento ou uma lista de assinaturas não estiver definida, o escopo da consulta é todo o que 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 managementGroups da API REST usa a ID do grupo de gerenciamento, que é diferente do nome do grupo de gerenciamento. Quando managementGroups é especificado, recursos das primeiras 10.000 assinaturas na hierarquia do grupo de gerenciamento especificado ou abaixo dela são incluídos. 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 ID myMG.

• URI da API REST

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

• Corpo 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 as atribuições para o escopo dado e todos os escopos filhos.
• AtScopeAndAbove: Retorna as atribuições para o escopo dado e todos os escopos pais, mas não os escopos filhos.
• AtScopeAboveAndBelow: Retorna as atribuições para o escopo dado, todos os escopos pais e todos os escopos filhos.
• AtScopeExact: Retorna atribuições apenas para o escopo dado; Não há escopos parentais ou filhos incluídos.

Exemplo: Obtenha todas as atribuições de políticas no grupo de gerenciamento do 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
  

• Exemplo 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íticas nos escopos da assinatura mySubscriptionId , do grupo de gerenciamento e do Tenant Root.

• URI da API REST

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

• Exemplo 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.

  Consulta de exemplo que envolve 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 que executa o Resource Graph.

  • Bash: Use uma barra inversa (\) como personagem de fuga.

    Consulta de exemplo que escapa da propriedade $type no Bash:

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

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

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

    Consulta de exemplo que escapa da propriedade $type no PowerShell:

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

Próximas etapas

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