API GET/LIST Azure Resources Graph (ARG)

API ARG GET/LIST предназначен для значительного уменьшения регулирования READ путем разгрузки запросов GET и LIST на альтернативную платформу ARG. Это действие достигается с помощью интеллектуальной маршрутизации плоскости управления, которая направляет запросы на альтернативную платформу при наличии определенного параметра. Если параметр отсутствует, запросы легко перенаправляются обратно в исходный поставщик ресурсов, обеспечивая гибкость.

ARG GET/LIST предоставляет квоту по умолчанию 4k запросов в минуту на пользователя и подписку в скользящем окне, что означает, что эта квота позволяет делать до 4,000 запросов в минуту с помощью этих API. Эта квота применяется для каждого пользователя на каждую подписку. Это означает:

• Если пользователь A обращается к подписке X, они получают до 4000 запросов в минуту.
• Если у пользователя A есть доступ к подписке Y, это считается как отдельная квота.
• Если пользователь B получает доступ к подписке X, это также отдельный лимит.
• API предоставляет заголовок ответа "x-ms-user-quota-remaining", указывающий оставшуюся квоту, и "x-ms-user-quota-resets-after", указывающий время для полного сброса квоты, на основании которого можно понять потребление квоты.

Использование API ARG GET/LIST

Чтобы использовать API ARG GET/LIST, сначала идентифицируйте, соответствует ли ваш сценарий условиям, описанным в руководству по регулированию запросов. Затем можно добавить флаг &useResourceGraph=true к применимым вызовам API GET/LIST, который направляет запрос к этой серверной части ARG для ответа.

Эта модель согласия была намеренно выбрана, чтобы позволить команде Azure Resource Graph лучше понять шаблоны использования клиентов и внести улучшения по мере необходимости.

Ознакомьтесь с некоторыми известными ограничениями здесь и часто задаваемыми вопросами.

Контракт API ARG GET/LIST

Получение очка ресурса

Этот запрос используется для поиска одного ресурса путем предоставления ресурса D.

Традиционный запрос получения точки:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion} 

Запрос на получение точки ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion}&useResourceGraph=true 

Получение коллекции подписок

Этот запрос используется для перечисления всех ресурсов в рамках одного типа ресурса в подписке.

Традиционный запрос на получение коллекции подписок:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

Запрос получения коллекции подписок ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

Получение коллекции групп ресурсов

Этот запрос используется для перечисления всех ресурсов в одной группе ресурсов.

Традиционный запрос получения точки:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

Запрос получения точки ARG GET/LIST:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

Некоторые часто используемые примеры

Сценарий. Получение виртуальной машины с помощью InstanceView

В этом конкретном примере используйте следующие запросы, чтобы получить виртуальную машину с помощью InstanceView.

Запрос команды ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines/{vm}?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

Список ВМ в группе ресурсов

В этом конкретном примере используйте следующие запросы, чтобы получить список виртуальных машин в группе ресурсов.

Запрос команды ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

Перечислить виртуальные машины VMSS (унифицированные) с помощью InstanceView

В этом конкретном примере используйте следующий запрос, чтобы получить список виртуальных машин VMSS с помощью InstanceView. Этот сценарий предназначен для виртуальной машины VMSS в гибком режиме оркестрации.

Запрос команды ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

Вывод списка виртуальных машин VMSS (Flex) с помощью InstanceView

В этом конкретном примере используйте следующие запросы, чтобы получить список виртуальных машин VMSS с помощью InstanceView.

Запрос команды ARG GET/LIST

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$filter='virtualMachineScaleSet/id' eq '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}'&$expand=instanceView&useResourceGraph=true

Список учетных записей хранения в подписке

В этом конкретном примере используйте следующие запросы, чтобы получить список учетных записей хранения в подписке.

Запрос «ARG GET/LIST»

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.storage/storageAccounts?api-version=2024-01-01&useResourceGraph=true 

Создание устойчивых запросов к ресурсам с помощью ARG и подхода провайдера ресурсов

В ситуациях, где качество и надёжность данных критически важны, настоятельно рекомендуется гибридная стратегия запросов. Этот подход сочетает вызовы Azure Resource Graph (ARG) с запасным вариантом API Resource Provider (RP), который служит источником истины для каждого ресурса. Внедряя интеллектуальную логику, которая автоматически запускает запасной вариант при возникновении проблем с свежестью данных, задержками индексации или задержками, вы значительно повышаете устойчивость своего решения. Это гарантирует, что пользователи испытывают минимальные перебои и продолжают получать точную информацию о ресурсах up-toдаты.

Распространённый сценарий: опрос сразу после создания ресурса

Многие пользователи опрашивают ресурсы сразу после создания — иногда в течение 1–2 секунд — как часть процесса записи, например, до тех пор, пока resource provisioningState не достигнет конечного состояния или пока определённые свойства не появятся в ответе. Поскольку индексация ARG может ещё не завершена, звонящие могут получить 404 Not Found, несмотря на наличие ресурса. В таких случаях гибридная стратегия помогает избежать ложноотрицательных результатов.

Два обходных пути для работы с коротким окном перед завершением индексации ARG:

1. Попробуйте использовать флаг useResourceGraph=true несколько раз, пока вызов не вернёт 200 OK.

2. Попробуйте повторить без флага useResourceGraph=true, чтобы напрямую вернуться к API Resource Provider.

Обе стратегии помогают гарантировать, что пользователи всегда получают максимально точное состояние ресурса — не сталкиваясь с кратковременными пробелами в свежести данных.

Известные ограничения

• Состояние работоспособности виртуальной машины VMSS в настоящее время не поддерживается. Если вам нужны эти данные, вы можете поделиться своим сценарием и предложить добавление функций на наших форумах отзывов.
• Расширения виртуальных машин и виртуальных машин VMSS - Рабочие состояния расширений виртуальных машин и VMSS не поддерживаются. Если вам нужны эти данные, вы можете поделиться своим сценарием и предложить добавление функций на наших форумах отзывов.
• Поддерживаемые ресурсы . API ARG GET/LIST поддерживает все типы ресурсов в составе resources и computeresources таблицы. Если вам нужен тип ресурса, который не входит в эти таблицы, вы можете поделиться своим сценарием и предложить добавление функций на наших форумах отзывов.
• Поддержка отдельных версий API. ARG GET/LIST сегодня поддерживает только одну версию API для каждого типа ресурса, которая обычно является последней версией типа, существующего в спецификации REST API Azure. Функция ARG GET/LIST возвращает apiVersion поле в полезных данных ресурса ответа, указывающее версию типа ресурса, который использовался при получении сведений о ресурсе. Вызывающие стороны могут применить это поле для понимания используемой версии API, если она относится к своему сценарию.
• Поддержка клиентов
  • REST API Azure: поддерживается
  • Пакет SDK Для Azure: поддерживаемый пример кода .NET
  • PowerShell: в настоящее время не поддерживается
  • Azure CLI: в настоящее время не поддерживается
  • Портал Azure: в настоящее время не поддерживается
• Проблемы десериализации клиента
  • Если клиент использует REST API для выдачи вызовов GET, обычно нет проблем с десериализацией из-за различий версий API.
  • Если клиент использует SDK Azure для выполнения GET-запросов, из-за более гибких настроек десериализации на всех языках, проблем с десериализацией возникнуть не должно, если только не произошли изменения, нарушающие контракт, для целевого типа ресурса.
• Запрос непроцессируемых ресурсов
  • Существуют редкие сценарии, в которых ARG GET/LIST не может правильно индексировать ресурс, причем эта ошибка не связана с существованием ресурса. Чтобы не жертвовать качеством данных, ARG GET/LIST отказывается обслуживать вызовы GET для этих ресурсов и возвращает код ошибки HTTP 422.
  • Клиенты ARG GET/LIST должны рассматривать HTTP 422 как постоянную ошибку. Клиенты должны повторить попытку, вернувшись к поставщику ресурсов (удалив useResourceGraph=true флаг). Так как ошибка применима специально к ARG GET/LIST, резервный доступ к поставщикам ресурсов должен привести к успешному выполнению E2E.
• Поддерживаемый уровень согласованности
  • При использовании ARG GET или LIST полученные данные отражают последние изменения с небольшой задержкой (обычно всего за несколько секунд), а не в режиме реального времени. Это называется "ограниченной устаревшим" и обеспечивает быстрые масштабируемые запросы, предоставляя согласованное и up-toпредставление даты ресурсов Azure. В отличие от прямых вызовов поставщиков ресурсов, которые гарантируют точность в реальном времени (строгая согласованность), ARG оптимизирован для производительности с предсказуемыми данными почти в реальном времени.
  • В ответах точки ресурса ARG GET/LIST предоставляет заголовок ответа x-ms-arg-snapshot-timestamp, указывающий метку времени при индексировании возвращаемого моментального снимка ресурса. Значение заголовка — время UTC в формате ISO8601. (Например, "x-ms-arg-snapshot-timestamp" : "2023-01-20T18:55:59.5610084Z").

Пример кода пакета SDK

Ниже приведен пример кода .NET для вызова API ARG GET/LIST путем создания ARMClient с политикой, которая добавляет флаг useResourceGraph=true к каждому вызову:

Сначала мы создаем настраиваемый ArmClientOption с политикой, которая добавляет флаг useResourceGraph=True на каждый вызов.

var armClientOptions = new ArmClientOptions(); armClientOptions.AddPolicy(new ArgGetListHttpPipelinePolicy(), HttpPipelinePosition.PerCall); 

Затем мы создадим ArmClient с помощью пользовательских ArmClientOptions:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), null, armClientOptions); 

Что делать, если мы хотим создать ARMClient с помощью подписки по умолчанию? Мы задали значение клиента ArmClient следующим образом:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), defaultSubId, armClientOptions);

При необходимости для создания клиента по умолчанию, который не добавляет useResourceGraph флаг, код клиента выбирает, какой клиент следует использовать в зависимости от конкретного сценария и потребностей. Для этого используйте следующий блок кода:

ArmClient defaultClient = new ArmClient(new DefaultAzureCredential(), null, new ArmClientOptions()); 

Затем используйте эту политику для добавления параметров запроса для каждого запроса через клиент:

internal class ArgGetListHttpPipelinePolicy : HttpPipelineSynchronousPolicy 

{ 
    private static const string UseResourceGraph = "useResourceGraph"; 
    public override void OnSendingRequest(HttpMessage message) 

    { 
        // Adds the required query parameter to explicitly query ARG GET/LIST if the flag is not already present 
        if (!message.Request.Uri.ContainsQuery(UseResourceGraph)) 
        { 
          message.Request.Uri.AppendQuery(UseResourceGraph, bool.TrueString); 
        } 
    } 
} 

Часто задаваемые вопросы

• Как убедиться, что API ARG GET/LIST возвращает ответ?

  Существует несколько способов, которые можно определить при запросе ARG GET/LIST:

  • В теле ответа поле apiVersion ресурсов будет заполнено, если оно предоставляется с помощью ARG GET/LIST. 
  • ARG GET/LIST/ARG возвращает несколько дополнительных заголовков ответа, некоторые из которых:
    • x-ms-arg-snapshot-timestamp
    • x-ms-user-quota-remaining
    • x-ms-пользовательская квота сбрасывается через
    • x-ms-resource-graph-request-duration

• Как узнать, какая версия API использовалась ARG GET/LIST?

  Это значение возвращается в поле apiVersion в ответе ресурса сегодня. 

• Что происходит, если вызывающий вызывает API ARG GET/LIST с useResourceGraph=true флагом ресурса, не поддерживаемого ARG GET/LIST?  

  Все неподдерживаемые или невозможные для маршрутизации запросы приводят к игнорированию useResourceGraph=true, и вызов автоматически направляется поставщику ресурсов. Пользователю не нужно предпринимать никаких действий.  

• Какие разрешения требуются для запроса API ARG GET/LIST?

  Для API ARG GET/LIST не требуются специальные разрешения; API ARG GET/LIST эквивалентны API GET, основанным на встроенных поставщиках ресурсов, поэтому применяется стандартный RBAC. Вызывающие пользователи должны иметь по крайней мере разрешения READ для ресурсов/областей, к которым они пытаются получить доступ. 

• Что такое стратегия отката, если при использовании API ARG GET/LIST возникают проблемы?  

  При подключении через флаг useResourceGraph=trueвызывающий объект может выбрать удаление флага (или) задать значение useResourceGraph=false, и вызов автоматически направляется поставщику ресурсов. 

• Что делать, если вы получаете 404 Not Found при попытке получить ресурс из ARG GET/LIST, который был недавно создан?

  Это распространенный сценарий для многих служб, где клиенты создают ресурсы и через 1–2 секунды в рамках другого рабочего процесса WRITE делают GET-запрос. Например, клиенты создают новый ресурс и сразу после этого пытаются создать оповещение, отслеживающее его метрики. Возможно, ресурс еще не индексирован ARG GET/LIST. Существует два способа обойти эту ситуацию:

  • Повторите попытку в ARG GET/LIST несколько раз, пока не вернется код состояния 200. 
  • Повторите попытку без флага ARG GET/LIST, чтобы вернуться к поставщику ресурсов. Настоящий код состояния 404 не попадает к поставщику ресурсов, так как Azure Resource Manager возвращает ошибку напрямую, в то время как лжекод 404 должен предоставляться поставщиками ресурсов для получения фактических данных.

• Какие параметры URI поддерживаются API ARG GET/LIST?

  API ARG GET/LIST поддерживает ряд параметров URI, которые помогают адаптировать результаты запросов на страницы и настраивать их. К ним относятся стандартные параметры разбиения на страницы OData:

  • $top. Указывает количество возвращаемых записей.
  • $skip. Пропускает указанное количество записей.
  • $skipToken. Используется для получения следующей страницы результатов в запросах с разбивкой на страницы.

  Параметры запроса для виртуальных машин и виртуальных машин VMSS —

  • statusOnly: statusOnly=true позволяет получать состояние выполнения всех виртуальных машин в подписке.
  • $expand=instanceView: выражение расширения, которое следует применить к операции. InstanceView позволяет получить состояние времени выполнения всех виртуальных машин, это можно указать только в том случае, если указан допустимый параметр $filter
  • $filter. Параметр системного запроса для фильтрации виртуальных машин, возвращенных в ответе. Допустимое значение : virtualMachineScaleSet/id eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}

• Что делать, если при использовании параметра useResourceGraph при вызове Azure Resource Graph возникают проблемы?

  Если при использовании useResourceGraph параметра с ARG возникают какие-либо проблемы, создайте запрос в службу поддержки Azure Resource Graph на портале Azure в разделе "Справка и поддержка".

• Как вы различаете троттлинг ARM и ARG?

  Пожалуйста, обратитесь к различению запросов на троттлинг для ARG и ARM.

• Что делать, если ARG GET/LIST API не работает?

  Рассматривайте это как сценарий отключения сервера ресурсов с ошибкой внутреннего сервера 500. ARM не делает автоматическую повторную попытку, поэтому сначала повторите с useResourceGraph=true. Если всё равно не получится, попробуйте повторить без флага, и звонок перейдёт напрямую к провайдеру ресурсов.