Merge pull request #262471 from davidsmatlak/ds-arg-update-throttle-guidance-20230104

Adds content about throttle support

Author: Court72

articles/governance/resource-graph/concepts/guidance-for-throttled-requests.md

@@ -1,26 +1,27 @@
 ---
-title: Guidance for throttled requests
-description: Learn to group, stagger, paginate, and query in parallel to avoid requests being throttled by Azure Resource Graph.
+title: Guidance for throttled requests in Azure Resource Graph
+description: Learn to group, stagger, paginate, and query in parallel to avoid requests being throttled in Azure Resource Graph.
 author: davidsmatlak
 ms.author: davidsmatlak
-ms.date: 08/18/2022
+ms.date: 01/04/2024
 ms.topic: conceptual
 ms.custom: devx-track-csharp
 ---
+
 # Guidance for throttled requests in Azure Resource Graph
 
 When creating programmatic and frequent use of Azure Resource Graph data, consideration should be
-made for how throttling impacts the results of the queries. Changing the way data is requested can
+made for how throttling affects the results of the queries. Changing the way data is requested can
 help you and your organization avoid being throttled and maintain the flow of timely data about your
 Azure resources.
 
 This article covers four areas and patterns related to the creation of queries in Azure Resource
 Graph:
 
-- Understand throttling headers
-- Grouping queries
-- Staggering queries
-- The impact of pagination
+- Understand throttling headers.
+- Grouping queries.
+- Staggering queries.
+- The effect of pagination.
 
 ## Understand throttling headers
 
@@ -42,20 +43,19 @@ first 10,000 subscriptions and the `x-ms-tenant-subscription-limit-hit` header i
 To illustrate how the headers work, let's look at a query response that has the header and values of
 `x-ms-user-quota-remaining: 10` and `x-ms-user-quota-resets-after: 00:00:03`.
 
-- Within the next 3 seconds, at most 10 queries may be submitted without being throttled.
-- In 3 seconds, the values of `x-ms-user-quota-remaining` and `x-ms-user-quota-resets-after` will be
-  reset to `15` and `00:00:05` respectively.
+- Within the next 3 seconds, at most 10 queries can be submitted without being throttled.
+- In 3 seconds, the values of `x-ms-user-quota-remaining` and `x-ms-user-quota-resets-after` are reset to `15` and `00:00:05` respectively.
 
 To see an example of using the headers to _backoff_ on query requests, see the sample in
-[Query in Parallel](#query-in-parallel).
+[Query in parallel](#query-in-parallel).
 
 ## Grouping queries
 
 Grouping queries by the subscription, resource group, or individual resource is more efficient than
 parallelizing queries. The quota cost of a larger query is often less than the quota cost of many
 small and targeted queries. The group size is recommended to be less than _300_.
 
-- Example of a poorly optimized approach
+- Example of a poorly optimized approach.
 
   ```csharp
   // NOT RECOMMENDED
@@ -76,7 +76,7 @@ small and targeted queries. The group size is recommended to be less than _300_.
   }
   ```
 
-- Example #1 of an optimized grouping approach
+- Example of an optimized grouping approach.
 
   ```csharp
   // RECOMMENDED
@@ -99,7 +99,7 @@ small and targeted queries. The group size is recommended to be less than _300_.
   }
   ```
 
-- Example #2 of an optimized grouping approach for getting multiple resources in one query
+- Example of an optimized grouping approach for getting multiple resources in one query.
 
   ```kusto
   Resources | where id in~ ({resourceIdGroup}) | project name, type
@@ -129,22 +129,21 @@ small and targeted queries. The group size is recommended to be less than _300_.
 
 ## Staggering queries
 
-Because of the way throttling is enforced, we recommend queries to be staggered. That is, instead of
-sending 60 queries at the same time, stagger the queries into four 5-second windows:
+Because of the way throttling is enforced, we recommend queries to be staggered. For example, instead of sending 60 queries at the same time, stagger the queries into four 5-second windows.
 
-- Non-staggered query schedule
+- Nonstaggered query schedule.
 
   | Query Count         | 60  | 0    | 0     | 0     |
   |---------------------|-----|------|-------|-------|
   | Time Interval (sec) | 0-5 | 5-10 | 10-15 | 15-20 |
 
-- Staggered query schedule
+- Staggered query schedule.
 
   | Query Count         | 15  | 15   | 15    | 15    |
   |---------------------|-----|------|-------|-------|
   | Time Interval (sec) | 0-5 | 5-10 | 10-15 | 15-20 |
 
-Here's an example of respecting throttling headers when querying Azure Resource Graph:
+The following code is an example of respecting throttling headers when querying Azure Resource Graph.
 
 ```csharp
 while (/* Need to query more? */)
@@ -166,12 +165,11 @@ while (/* Need to query more? */)
 }
 ```
 
-### Query in Parallel
+### Query in parallel
 
 Even though grouping is recommended over parallelization, there are times where queries can't be
-easily grouped. In these cases, you may want to query Azure Resource Graph by sending multiple
-queries in a parallel fashion. Here's an example of how to _backoff_ based on throttling headers
-in such scenarios:
+easily grouped. In these cases, you might want to query Azure Resource Graph by sending multiple
+queries in a parallel fashion. The following example shows how to _backoff_ based on throttling headers.
 
 ```csharp
 IEnumerable<IEnumerable<string>> queryGroup = /* Groups of queries  */
@@ -205,44 +203,39 @@ async Task ExecuteQueries(IEnumerable<string> queries)
 
 ## Pagination
 
-Since Azure Resource Graph returns at most 1,000 entries in a single query response, you may need to
-[paginate](./work-with-data.md#paging-results) your queries to get the complete dataset you're
-looking for. However, some Azure Resource Graph clients handle pagination differently than others.
-
-- C# SDK
+Because Azure Resource Graph returns a maximum of 1,000 entries in a single query response, you might need to [paginate](./work-with-data.md#paging-results) your queries to get the complete dataset you want. But some Azure Resource Graph clients handle pagination differently than others.
 
-  When using ResourceGraph SDK, you need to handle pagination by passing the skip token being
-  returned from the previous query response to the next paginated query. This design means you need
-  to collect results from all paginated calls and combine them together at the end. In this case,
-  each paginated query you send takes one query quota:
+When using ResourceGraph SDK, you need to handle pagination by passing the skip token being
+returned from the previous query response to the next paginated query. This design means you need
+to collect results from all paginated calls and combine them together at the end. In this case,
+each paginated query you send takes one query quota.
 
-  ```csharp
-  var results = new List<object>();
-  var queryRequest = new QueryRequest(
-    subscriptions: new[] { mySubscriptionId },
-    query: "Resources | project id, name, type");
+```csharp
+var results = new List<object>();
+var queryRequest = new QueryRequest(
+  subscriptions: new[] { mySubscriptionId },
+  query: "Resources | project id, name, type");
+var azureOperationResponse = await this.resourceGraphClient
+  .ResourcesWithHttpMessagesAsync(queryRequest, header)
+  .ConfigureAwait(false);
+while (!string.IsNullOrEmpty(azureOperationResponse.Body.SkipToken))
+{
+  queryRequest.Options ??= new QueryRequestOptions();
+  queryRequest.Options.SkipToken = azureOperationResponse.Body.SkipToken;
   var azureOperationResponse = await this.resourceGraphClient
-    .ResourcesWithHttpMessagesAsync(queryRequest, header)
-    .ConfigureAwait(false);
-  while (!string.IsNullOrEmpty(azureOperationResponse.Body.SkipToken))
-  {
-    queryRequest.Options ??= new QueryRequestOptions();
-    queryRequest.Options.SkipToken = azureOperationResponse.Body.SkipToken;
-    var azureOperationResponse = await this.resourceGraphClient
-        .ResourcesWithHttpMessagesAsync(queryRequest, header)
-        .ConfigureAwait(false);
-    results.Add(azureOperationResponse.Body.Data.Rows);
+      .ResourcesWithHttpMessagesAsync(queryRequest, header)
+      .ConfigureAwait(false);
+  results.Add(azureOperationResponse.Body.Data.Rows);
 
-  // Inspect throttling headers in query response and delay the next call if needed.
-  }
-  ```
+// Inspect throttling headers in query response and delay the next call if needed.
+}
+```
 
-## Still get throttled?
+## Still being throttled?
 
-If you're getting throttled after exercising the above recommendations, contact the [Azure Resource
-Graph team](mailto:[email protected]).
+If you used this article's recommendations and your Azure Resource Graph queries are still being throttled, contact the [Azure Resource Graph team](mailto:[email protected]). The team supports Azure Resource Graph but doesn't support [Microsoft Graph throttling](/graph/throttling).
 
-Provide these details:
+Provide these details when you contact the Azure Resource Graph team:
 
 - Your specific use-case and business driver needs for a higher throttling limit.
 - How many resources do you have access to? How many of the are returned from a single query?