Trabalhando com grandes conjuntos de dados de recurso do Azure

  • Artigo

O Azure Resource Graph foi projetado para trabalhar com informações sobre os recursos em seu ambiente do Azure e obtê-las. O Resource Graph facilita a obtenção esses dados rapidamente, mesmo ao consultar milhares de registros. O Resource Graph tem várias opções para trabalhar com esses grandes conjuntos de dados.

Para obter orientação sobre como trabalhar com consultas em alta frequência, veja Diretrizes para solicitações limitadas.

Tamanho do resultado do conjunto de dados

Por padrão, o Resource Graph limita qualquer consulta a retornar apenas 1000 registros. Esse controle protege o usuário e o serviço de consultas não intencionais que resultariam em grandes conjuntos de dados. Esse evento geralmente ocorre quando um cliente está experimentando consultas para localizar e filtrar recursos da maneira que atende às suas necessidades específicas. Esse controle é diferente de usar os operadores de linguagem de programação top ou limit do Azure Data Explorer para limitar os resultados.

Observação

É recomendável ordenar os resultados em pelo menos uma coluna com asc ou desc quando First for usado. Os resultados retornados são aleatórios e não podem ser repetidos quando não são classificados.

O limite padrão pode ser substituído por meio de todos os métodos de interação com o Resource Graph. Os exemplos a seguir mostram como alterar o limite de tamanho do conjunto de dados para 200:

az graph query -q "Resources | project name | order by name asc" --first 200 --output table

Search-AzGraph -Query "Resources | project name | order by name asc" -First 200

Na API REST, o controle é $top e faz parte de QueryRequestOptions.

O controle que for mais restritivo prevalecerá. Por exemplo, se sua consulta usa os operadores top ou limit e resultaria em mais registros do que First, o máximo de registros retornado seria igual a First. Da mesma forma, se top ou limit for menor do que First, o conjunto de registros retornado será o menor valor configurado por top ou limit.

O parâmetro First tem um valor máximo permitido de 1000.

Limitação do tamanho do resultado da exportação de CSV

Ao usar a funcionalidade de exportação de CSV (valor separado por vírgulas) do Azure Resource Graph Explorer, o conjunto de resultados é limitado a 55.000 registros. Esse é um limite da plataforma que não pode ser substituído usando um tíquete de suporte do Azure.

Para baixar os resultados do CSV do portal do Azure, navegue até o Azure Resource Graph Explorer e execute uma consulta. Na barra de ferramentas, clique em Baixar como CSV.

Ignorando os registros

A próxima opção para trabalhar com grandes conjuntos de dados é o controle Skip. Esse controle permite que sua consulta pule ou ignore o número definido de registros antes de retornar os resultados. Skip é útil para consultas que classificam os resultados de uma maneira significativa, em que a intenção é chegar a registros em algum lugar no meio do conjunto de resultados. Se os resultados necessários estão no final do conjunto de dados retornado, é mais eficiente usar uma configuração de classificação diferente e, em vez disso, recuperar os resultados da parte superior do conjunto de dados.

Observação

É recomendável ordenar os resultados em pelo menos uma coluna com asc ou desc quando Skip for usado. Os resultados retornados são aleatórios e não podem ser repetidos quando não são classificados. Se limit ou take for usado na consulta, Skip será ignorado.

Os exemplos a seguir mostram como ignorar os primeiros 10 registros em que uma consulta resultaria, começando em vez disso o conjunto de resultados pelo 11º registro:

az graph query -q "Resources | project name | order by name asc" --skip 10 --output table

Search-AzGraph -Query "Resources | project name | order by name asc" -Skip 10

Na API REST, o controle é $skip e faz parte de QueryRequestOptions.

Resultados da paginação

Quando é necessário dividir um conjunto de resultados em conjuntos de registros menores para processamento ou porque um conjunto de resultados excede o valor máximo permitido de 1000 registros retornados, use paginação. A API RESTQueryResponse fornece valores para indicar se um conjunto de resultados foi subdividido: resultTruncated e $skipToken. resultTruncated é um valor booliano que informa ao consumidor se existem registros adicionais não retornados na resposta. Essa condição também pode ser identificada quando a propriedade count é menor do que a propriedade totalRecords. totalRecords define quantos registros correspondem à consulta.

O valor de resultTruncated é true quando há menos recursos disponíveis do que uma consulta está solicitando ou quando a paginação está desabilitada ou não é possível porque:

  • A consulta contém um operador limit ou sample/take.
  • Todas as colunas de saída são tipo dynamic ou null.

Quando resultTruncated é true, a propriedade $skipToken não é definida.

Os exemplos a seguir mostram como ignorar os primeiros 3.000 registros e retornar os primeiros 1.000 registros depois dos registros ignorados com a CLI do Azure e o Azure PowerShell:

az graph query -q "Resources | project id, name | order by id asc" --first 1000 --skip 3000

Search-AzGraph -Query "Resources | project id, name | order by id asc" -First 1000 -Skip 3000

Importante

A resposta não incluirá a $skipToken se:

  • A consulta contém um operador limit ou sample/take.
  • Todas as colunas de saída são tipo dynamic ou null.

Para ver um exemplo, confira a Consulta de próxima página na documentação da API REST.

Formatação de resultados

Os resultados de uma consulta do Resource Graph são fornecidos em dois formatos, Table e ObjectArray. O formato é configurado com o parâmetro resultFormat como parte das opções de solicitação. O formato Table é o valor padrão para resultFormat.

Os resultados de CLI do Azure são fornecidos, por padrão, em JSON. Os resultados no Azure PowerShell são um objeto PSResourceGraphResponse, mas podem ser rapidamente convertidos em JSON com o ConvertTo-Json cmdlet na propriedade Data. Para outros SDKs, os resultados da consulta podem ser configurados para gerar o formato ObjectArray.

Formato - Table

O formato padrão, Table, retorna resultados em um formato JSON projetado para realçar o design da coluna e os valores da linha das propriedades retornadas pela consulta. Esse formato se assemelha bastante aos dados apresentados em uma tabela ou planilha estruturada, com as colunas identificadas primeiro e, em seguida, cada linha representando os dados alinhados a essas colunas.

A seguir está um exemplo de um resultado de consulta com a formatação Table:

{
    "totalRecords": 47,
    "count": 1,
    "data": {
        "columns": [{
                "name": "name",
                "type": "string"
            },
            {
                "name": "type",
                "type": "string"
            },
            {
                "name": "location",
                "type": "string"
            },
            {
                "name": "subscriptionId",
                "type": "string"
            }
        ],
        "rows": [
            [
                "veryscaryvm2-nsg",
                "microsoft.network/networksecuritygroups",
                "eastus",
                "11111111-1111-1111-1111-111111111111"
            ]
        ]
    },
    "facets": [],
    "resultTruncated": "true"
}

Formato - ObjectArray

O formato ObjectArray também retorna resultados em um formato JSON. No entanto, esse design é semelhante ao relacionamento do par chave/valor comum em JSON, com a correspondência dos dados da coluna e da linha em grupos de matrizes.

A seguir está um exemplo de um resultado de consulta com a formatação ObjectArray:

{
    "totalRecords": 47,
    "count": 1,
    "data": [{
        "name": "veryscaryvm2-nsg",
        "type": "microsoft.network/networksecuritygroups",
        "location": "eastus",
        "subscriptionId": "11111111-1111-1111-1111-111111111111"
    }],
    "facets": [],
    "resultTruncated": "true"
}

Próximas etapas