大規模な Azure リソース データ セットの処理Working with large Azure resource data sets

Azure Resource Graph は、Azure 環境内にあるリソースを操作し、リソースに関する情報を取得することを目的に設計されています。Azure Resource Graph is designed for working with and getting information about resources in your Azure environment. Resource Graph を使用すると、数千レコードのクエリを実行する場合でも、このデータの取得が高速になります。Resource Graph makes getting this data fast, even when querying thousands of records. Resource Graph には、これらの大きなデータ セットを操作するための複数のオプションがあります。Resource Graph has several options for working with these large data sets.

高頻度のクエリの操作に関するガイダンスについては、スロットルされた要求に関するガイダンスのページを参照してください。For guidance on working with queries at a high frequency, see Guidance for throttled requests.

データ セットの結果のサイズData set result size

既定では、Resource Graph のクエリで返されるレコードは 100 個だけに制限されています。By default, Resource Graph limits any query to returning only 100 records. このコントロールにより、ユーザーとサービスの両方が、大規模なデータ セットになる意図しないクエリから保護されます。This control protects both the user and the service from unintentional queries that would result in large data sets. このようなことが最もよく発生するのは、ユーザーが自分の特定のニーズに合った方法でリソースの検索とフィルター処理を行うクエリを実験しているときです。This event most often happens as a customer is experimenting with queries to find and filter resources in the way that suits their particular needs. このコントロールは、Azure Data Explorer 言語の top または limit 演算子を使用して結果を制限する場合とは異なります。This control is different than using the top or limit Azure Data Explorer language operators to limit the results.

注意

First を使用するときは、asc または desc を使って、少なくとも 1 つの列を基に結果を並べ替えることをお勧めします。When using First, it's recommended to order the results by at least one column with asc or desc. 並べ替えを行わないと、返される結果がランダムになり、反復可能ではなくなります。Without sorting, the results returned are random and not repeatable.

既定の制限は、Resource Graph と対話するすべての方法でオーバーライドできます。The default limit can be overridden through all methods of interacting with Resource Graph. 次の例では、データ セットのサイズ制限を 200 に変更する方法を示します。The following examples show how to change the data set size limit to 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

REST API でのコントロールは $top であり、QueryRequestOptions の一部です。In the REST API, the control is $top and is part of QueryRequestOptions.

"最も制限の厳しい" コントロールが選択されます。The control that is most restrictive will win. たとえば、クエリに含まれる top または limit 演算子で指定されているレコード数が First より多い場合、返される最大レコード数は First と等しくなります。For example, if your query uses the top or limit operators and would result in more records than First, the maximum records returned would be equal to First. 同様に、top または limitFirst より小さい場合は、返されるレコード セットは top または limit で構成されている小さい方の値になります。Likewise, if top or limit is smaller than First, the record set returned would be the smaller value configured by top or limit.

First の最大許容値は現在 5000 であり、これは、結果の 1000 件のレコードを一度にページングすることで実現されます。First currently has a maximum allowed value of 5000, which it achieves by paging results 1000 records at a time.

重要

First1000 件を超えるレコード数になるように構成されている場合、改ページ位置の自動修正が機能するためには、id フィールドをクエリに反映するする必要があります。When First is configured to be greater than 1000 records, the query must project the id field in order for pagination to work. これがクエリに含まれていない場合、応答は改ページされず、結果は 1000 レコードに制限されます。If it's missing from the query, the response won't get paged and the results are limited to 1000 records.

レコードのスキップSkipping records

大規模なデータ セットを操作するための次のオプションは、Skip コントロールです。The next option for working with large data sets is the Skip control. このコントロールをクエリで使用すると、結果を返す前に定義されている数のレコードをスキップできます。This control allows your query to jump over or skip the defined number of records before returning the results. Skip は、結果セットの中間にあるレコードを取得することを目的として、意味のある方法で結果を並べ替えるクエリに便利です。Skip is useful for queries that sort results in a meaningful way where the intent is to get at records somewhere in the middle of the result set. 必要な結果が返されるデータ セットの末尾にある場合は、異なる並べ替え構成を使用し、代わりにデータ セットの先頭から結果を取得する方が効率的です。If the results needed are at the end of the returned data set, it's more efficient to use a different sort configuration and retrieve the results from the top of the data set instead.

注意

Skip を使用するときは、asc または desc を使って、少なくとも 1 つの列を基に結果を並べ替えることをお勧めします。When using Skip, it's recommended to order the results by at least one column with asc or desc. 並べ替えを行わないと、返される結果がランダムになり、反復可能ではなくなります。Without sorting, the results returned are random and not repeatable.

次の例では、クエリ結果の最初の 10 レコードをスキップして、代わりに 11 番目のレコードから結果セットを返し始める方法を示します。The following examples show how to skip the first 10 records a query would result in, instead starting the returned result set with the 11th record:

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

REST API でのコントロールは $skip であり、QueryRequestOptions の一部です。In the REST API, the control is $skip and is part of QueryRequestOptions.

ページングの結果Paging results

処理のために、または結果セットが返されるレコード数の最大許容値 1000 を超えるために、結果セットを小さなレコード セットに分割する必要がある場合は、ページングを使用します。When it's necessary to break a result set into smaller sets of records for processing or because a result set would exceed the maximum allowed value of 1000 returned records, use paging. REST APIQueryResponse では、結果セットが分割されていることを示す値として、resultTruncated$skipToken が提供されています。The REST API QueryResponse provides values to indicate of a results set has been broken up: resultTruncated and $skipToken. resultTruncated はブール値で、応答で返されていない追加のレコードがあるかどうかをコンシューマーに通知します。resultTruncated is a boolean value that informs the consumer if there are additional records not returned in the response. この状態は、count プロパティが totalRecords プロパティより小さい場合も示されます。This condition can also be identified when the count property is less than the totalRecords property. totalRecords では、クエリに一致したレコード数が定義されています。totalRecords defines how many records that match the query.

ページングが無効になっているか、id 列がないためにページングを使用できない場合、または使用可能なリソースがクエリで要求されている量に満たない場合、resultTruncatedtrue です。resultTruncated is true when either paging is disabled or not possible due to no id column or when there are less resources available than a query is requesting. resultTruncatedtrue のときは、 $skipToken プロパティは設定されません。When resultTruncated is true, the $skipToken property is not set.

次の例では、Azure CLI および Azure PowerShell で、最初の 3000 個のレコードをスキップし、これらのスキップされたレコードの後の最初の 1000 個のレコードを返す方法を示します。The following examples show how to skip the first 3000 records and return the first 1000 records after those records skipped with Azure CLI and 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

重要

改ページ位置の自動修正が機能するためには、id フィールドをクエリに反映する必要があります。The query must project the id field in order for pagination to work. それがクエリにないと、応答には $skipToken が含まれません。If it's missing from the query, the response won't include the $skipToken.

例については、REST API のドキュメントの「Next page query (次のページのクエリ)」をご覧ください。For an example, see Next page query in the REST API docs.

結果の書式設定Formatting results

Resource Graph クエリの結果は TableObjectArray の 2 つの形式で提供されます。Results of a Resource Graph query are provided in two formats, Table and ObjectArray. この形式は、要求オプションの一部として resultFormat パラメーターを使用して構成されます。The format is configured with the resultFormat parameter as part of the request options. Table 形式は resultFormat の既定値です。The Table format is the default value for resultFormat.

既定では、Azure CLI の結果は JSON で提供されます。Results from Azure CLI are provided in JSON by default. Azure PowerShell の結果は、既定では PSCustomObject になりますが、ConvertTo-Json コマンドレットを使用してすぐに JSON に変換することができます。Results in Azure PowerShell are a PSCustomObject by default, but they can quickly be converted to JSON using the ConvertTo-Json cmdlet. 他の SDK のために、ObjectArray 形式を出力するようにクエリ結果を構成できます。For other SDKs, the query results can be configured to output the ObjectArray format.

形式 - TableFormat - Table

既定の形式である Table は、クエリによって返されるプロパティの列のデザインと行の値を強調表示するように設計された JSON 形式で結果を返します。The default format, Table, returns results in a JSON format designed to highlight the column design and row values of the properties returned by the query. この形式は、構造化テーブルまたはスプレッドシートで定義されているデータによく似ており、最初に列が識別され、その後でデータを示す各行がこれらの列に合わせて表示されます。This format closely resembles data as defined in a structured table or spreadsheet with the columns identified first and then each row representing data aligned to those columns.

Table 形式でのクエリ結果の例を次に示します。Here is a sample of a query result with the Table formatting:

{
    "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"
}

形式 - ObjectArrayFormat - ObjectArray

ObjectArray 形式でも結果は JSON 形式で返されます。The ObjectArray format also returns results in a JSON format. ただし、このデザインは、列と行データが配列グループで一致する、JSON で共通するキーと値のペアの関係に対応しています。However, this design aligns to the key/value pair relationship common in JSON where the column and the row data are matched in array groups.

ObjectArray 形式でのクエリ結果の例を次に示します。Here is a sample of a query result with the ObjectArray formatting:

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

ObjectArray 形式を使用するように resultFormat を設定する例を以下に示します。Here are some examples of setting resultFormat to use the ObjectArray format:

var requestOptions = new QueryRequestOptions( resultFormat: ResultFormat.ObjectArray);
var request = new QueryRequest(subscriptions, "Resources | limit 1", options: requestOptions);
request_options = QueryRequestOptions(
    result_format=ResultFormat.object_array
)
request = QueryRequest(query="Resources | limit 1", subscriptions=subs_list, options=request_options)
response = client.resources(request)

次のステップNext steps