Utilisation de jeux de données volumineux d’Azure Resource Graph

  • Article

Azure Resource Graph est conçu pour obtenir et utiliser des informations sur des ressources dans votre environnement Azure. Resource Graph permet d’obtenir ces données rapidement, même en cas d’interrogation de milliers d’enregistrements. Resource Graph offre plusieurs options pour utiliser ces jeux de données volumineux.

Pour obtenir des conseils sur l’utilisation des requêtes à une fréquence élevée, voir Instructions pour les requêtes limitées.

Taille du jeu de résultats

Par défaut, Resource Graph limite à 1 000 le nombre d’enregistrements retournés par une requête. Ce contrôle protège l’utilisateur et le service contre des requêtes involontaires qui auraient pour effet de retourner des jeux de données volumineux. Cela se produit le plus souvent quand un client expérimente des requêtes pour rechercher et filtrer des ressources d’une manière correspondant à ses besoins particuliers. Ce contrôle diffère de l’utilisation des opérateurs linguistiques top ou limit d’Azure Data Explorer pour limiter les résultats.

Notes

Lorsque vous utilisez First, il est recommandé d’ordonner les résultats sur au moins une colonne avec asc ou desc. À défaut de tri, les résultats retournés sont aléatoires et non reproductibles.

La limite par défaut peut être modifiée via toutes les méthodes d’interaction avec Resource Graph. Les exemples suivants montrent comment modifier la limite de taille de jeu de données en la définissant sur 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

Dans l’API REST, le contrôle est $top et fait partie de QueryRequestOptions.

Le contrôle le plus restrictif l’emporte. Par exemple, si votre requête utilise les opérateurs top ou limit et aurait pour effet de retourner plus d’enregistrements qu’avec l’opérateur First, le nombre maximal d’enregistrements retournés est égal à celui obtenu avec l’opérateur First. De même, si les opérateurs top ou limit ont pour effet de retourner un nombre d’enregistrements inférieur à celui que retournerait l’opérateur First, le jeu d’enregistrements retourné est celui comprenant le plus petit nombre d’enregistrements retournés par les opérateurs top ou limit.

Le paramètre First a une valeur maximale autorisée de 1 000.

Limitation de la taille des résultats CSV exportés

Lorsque vous utilisez la fonctionnalité d’exportation CSV de l’Explorateur Azure Resource Graph, le jeu de résultats est limité à 55 000 enregistrements. Il s’agit d’une limite de la plateforme qui ne peut pas être résolue par l’envoi d’un ticket de support Azure.

Pour télécharger les résultats CSV à partir du portail Azure, accédez à l’Explorateur Azure Resource Graph et exécutez une requête. Dans la barre d’outils, cliquez sur Télécharger au format CSV.

Omission d’enregistrements

L’option suivante pour la manipulation de jeux de données volumineux est l’utilisation du contrôle Skip. Ce contrôle permet à votre requête d’omettre ou d’ignorer le nombre défini d’enregistrements avant de retourner les résultats. Le contrôle Skip est utile pour les requêtes qui trient les résultats de façon explicite lorsque l’intention est d’accéder à des enregistrements quelque part au milieu de jeu de résultats. Si les résultats nécessaires figurent à la fin du jeu de données retourné, il est plus efficace d’utiliser une configuration de tri différente afin de récupérer à la place les résultats à partir de la partie supérieure du jeu de données.

Notes

Lorsque vous utilisez Skip, il est recommandé d’ordonner les résultats sur au moins une colonne avec asc ou desc. À défaut de tri, les résultats retournés sont aléatoires et non reproductibles. Si limit ou take sont utilisés dans la requête, Skip (Ignorer) est ignoré.

Les exemples suivants montrent comment ignorer les 10 premiers enregistrements qu’une requête retournerait, en retournant le jeu de résultats à partir du 11e enregistrement :

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

Dans l’API REST, le contrôle est $skip et fait partie de QueryRequestOptions.

Résultats de pagination

S’il est nécessaire de diviser un jeu de résultats en jeux d’enregistrements plus petits à des fins de traitement ou parce que le jeu de résultats dépasse la valeur maximale autorisée de 1000 enregistrements retournés, utilisez une pagination. Pour indiquer qu’un jeu de résultats a été divisé, l’API RESTQueryResponse fournit les valeurs resultTruncated et $skipToken. resultTruncated est une valeur booléenne qui informe le consommateur s’il existe davantage d’enregistrements non retournés dans la réponse. Cette condition peut également être identifiée lorsque la valeur de la propriété count est inférieure à celle de la propriété totalRecords. La valeur totalRecords définit le nombre d’enregistrements correspondant à la requête.

resultTruncated a pour valeur true lorsque moins de ressources sont disponibles que lorsqu’une requête procède à l’interrogation, ou lorsque la pagination est désactivée ou impossible :

  • La requête contient un opérateur limit ou sample/take.
  • Toutes les colonnes de sortie sont de type dynamic ou null.

Quand la valeur resultTruncated est true, la propriété $skipToken n’est pas définie.

Les exemples suivants montrent comment ignorer (skip) les 3 000 premiers enregistrements et retourner les 1 000 premiers (first) enregistrements suivants avec Azure CLI et 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

Important

La réponse n’inclut pas $skipToken si :

  • La requête contient un opérateur limit ou sample/take.
  • Toutes les colonnes de sortie sont de type dynamic ou null.

Pour obtenir un exemple, voir Requête Page suivante dans la documentation de l’API REST.

Mise en forme des résultats

Les résultats d’une requête Resource Graph sont fournis aux formats Table et ObjectArray . Le format est configuré avec le paramètre resultFormat dans le cadre des options de requête. Le format Table est la valeur par défaut du paramètre resultFormat.

Les résultats de l’interface Azure CLI sont fournis au format JSON par défaut. Les résultats dans Azure PowerShell sont un objet PSResourceGraphResponse. Cependant, ils peuvent être convertis rapidement au format JSON à l’aide de la cmdlet ConvertTo-Json sur la propriété Données. Pour les autres kits SDK, les résultats de la requête peuvent être configurés pour sortir au format ObjectArray.

Format - Table

Le format par défaut (Table ) retourne les résultats dans un format JSON conçu pour mettre en évidence la conception des colonnes et les valeurs de lignes des propriétés retournées par la requête. Ce format se rapproche beaucoup de celui d’une table de données structurée ou d’une feuille de calcul avec les colonnes identifiées en premier et chaque ligne représentant les données alignées à ces colonnes.

Voici un exemple de résultat de requête au format 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"
}

Format - ObjectArray

Le format ObjectArray retourne également les résultats au format JSON. Toutefois, cette conception s’aligne sur la relation de paire clé/valeur courante du format JSON, où les données de colonne et de ligne sont mises en correspondance dans des groupes de tableaux.

Voici un exemple de résultat de requête au format ObjectArray :

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

Étapes suivantes