Справочник по REST API Azure

Добро пожаловать в справочную документацию по REST API Azure.

REST API — это конечные точки службы, которые поддерживают набор операций HTTP (методов), предоставляющих доступ на создание, получение, обновление или удаление ресурсов сервера. В этой статье описаны следующие операции.

• Вызов REST API Azure с помощью curl
• Основные компоненты пары запросов и ответов REST API.
• Как зарегистрировать клиентское приложение с помощью Microsoft Entra ID для защиты запросов REST.
• Общие сведения о создании и отправке запроса REST, а также об обработке ответа.

Совет

Большинство REST API службы Azure имеют клиентские библиотеки, предоставляющие собственный интерфейс для использования служб Azure:

.ЧИСТАЯ | Java | | Node.jsPython | Пойти | C++

Вызов REST API Azure с помощью curl

Процесс, описанный в следующей записи блога, показывает, как вызвать REST API Azure с помощью curl. Вы можете использовать curl в автоматических скриптах. Например, в сценариях автоматизации DevOps.

Вызов AZURE REST API с помощью curl

Компоненты запроса и ответа API REST

Пару запроса-ответа API REST можно разделить на пять компонентов:

1. URI запроса, который состоит из: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Несмотря на то, что URI запроса включается в заголовок сообщения запроса, мы выделяем его отдельно, так как большинство языков или платформ требуют передавать его отдельно от сообщения запроса.

   • Схема URI: указывает протокол, используемый для передачи запроса. Например, http или https.
   • Узел URI: указывает имя домена или IP-адрес сервера, где размещена конечная точка службы REST, например graph.microsoft.com.
   • Путь к ресурсу: указывает ресурс или коллекцию ресурсов, которые могут содержать несколько сегментов, используемых службой для определения выборки этих ресурсов. Например: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners запрашивает список владельцев определенного приложения в коллекции приложений.
   • Строка запроса (необязательно): предоставляет дополнительные простые параметры, такие как критерий выбора ресурса или версии API.

2. Поля заголовка сообщения HTTP-запроса :

   • Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции вы запрашиваете. Rest API Azure поддерживают методы GET, HEAD, PUT, POST и PATCH.
   • Необязательные дополнительные поля заголовка, требуемые для указанного URI и метода HTTP. Например, заголовок авторизации, который предоставляет маркер носителя, содержащий сведения об авторизации клиента для запроса.

3. Необязательные поля текста сообщения запроса HTTP для поддержки URI и операции HTTP. Например, операции POST содержат объекты в кодировке MIME, которые передаются как сложные параметры. Для операций POST или PUT тип в кодировке MIME текста должен быть указан в заголовке запроса Content-type. Для некоторых служб необходимо использовать конкретный тип MIME, например application/json.

4. Поля заголовка сообщения ответа HTTP:

   • Код состояния HTTP— от кодов успешного выполнения 2xx до кодов ошибок 4xx или 5xx. Кроме того, может быть возвращен определяемый службой код состояния, как указано в документации по API.
   • Необязательные дополнительные поля заголовка, как требуется для поддержки ответа запроса, такие как заголовок ответа Content-type.

5. Необязательные поля текста сообщения ответа HTTP:

   • В тексте ответа HTTP возвращаются объекты ответа в кодировке MIME, например ответ от метода GET, который возвращает данные. Как правило, эти объекты возвращаются в структурированном виде, например JSON или XML, как указано в заголовке ответа Content-type. Например, при запросе маркера доступа из Microsoft Entra ID он возвращается в тексте ответа в качестве access_token элемента, одного из нескольких объектов, сопряженных с именем и значением в коллекции данных. В этом примере также включается заголовок Content-Type: application/json ответа .

Регистрация клиентского приложения в Microsoft Entra ID

Большинство служб Azure (например, поставщики azure Resource Manager и классическая модель развертывания) требуют, чтобы клиентский код прошел проверку подлинности с использованием допустимых учетных данных, прежде чем можно будет вызвать API службы. Проверка подлинности координируется между различными субъектами Microsoft Entra ID и предоставляет клиенту маркер доступа в качестве подтверждения проверки подлинности. Затем маркер отправляется в службу Azure в заголовке авторизации HTTP последующих запросов REST API. Утверждения маркера также предоставляют сведения службе, что позволяет ей проверить клиента и выполнить любую необходимую авторизацию.

Если вы используете REST API, который не использует встроенную проверку подлинности Microsoft Entra или уже зарегистрировали клиент, перейдите к разделу Создание запроса.

Предварительные требования

Клиентское приложение должно сделать конфигурацию удостоверений известной для Microsoft Entra ID перед выполнением, зарегистрировав ее в клиенте Microsoft Entra. Прежде чем зарегистрировать клиент в Microsoft Entra ID, примите во внимание следующие предварительные требования.

• Если у вас еще нет клиента Microsoft Entra, см. раздел Настройка клиента Microsoft Entra.

• В соответствии с OAuth2 Authorization Framework Microsoft Entra ID поддерживает два типа клиентов. Понимание каждого из них поможет вам решить, какой из них наиболее подходит для вашего сценария:

  • веб-или конфиденциальные клиенты выполняются на веб-сервере и могут получать доступ к ресурсам по собственному удостоверению (например, к службе или управляющей программе) или получать делегированную авторизацию для доступа к ресурсам под удостоверением вошедшего пользователя (например, веб-приложения). Только веб-клиент может безопасно хранить и представлять собственные учетные данные во время проверки подлинности Microsoft Entra для получения маркера доступа.
  • Собственные или общедоступные клиенты устанавливаются и запускаются на устройстве. Они могут получить доступ к ресурсам только при делегированной авторизации, используя удостоверение вошедшего пользователя для получения маркера доступа от имени пользователя.

• Процесс регистрации создает два связанных объекта в клиенте Microsoft Entra, где зарегистрировано приложение: объект приложения и объект субъекта-службы. Дополнительные сведения об этих компонентах и их использовании во время выполнения см. в статье Объекты приложения и субъекта-службы в Microsoft Entra ID.

Теперь вы можете зарегистрировать клиентское приложение в Microsoft Entra ID.

Регистрация клиента

Сведения о регистрации клиента, который обращается к REST API azure Resource Manager, см. в статье Использование портала для создания Microsoft Entra приложения и субъекта-службы, которые могут получать доступ к ресурсам. В статье (также доступной в версиях PowerShell и CLI для автоматизации регистрации) показано, как:

• Зарегистрируйте клиентское приложение с помощью Microsoft Entra ID.
• Настройте запросы разрешений, чтобы разрешить клиенту доступ к API Resource Manager Azure.
• Настройте параметры Azure Resource Manager Role-Based контроль доступа (RBAC) для авторизации клиента.

Если клиент обращается к API, отличному от API Resource Manager Azure, см. следующие статьи:

• Краткое руководство: регистрация приложения с помощью платформы удостоверений Майкрософт (предварительная версия)
  • Зарегистрируйте клиентское приложение с помощью Microsoft Entra ID в разделе "Регистрация приложения".
  • Создайте секретный ключ (если вы регистрируете веб-клиент) в разделе "Добавление учетных данных".
• Настройка приложения для предоставления веб-API
  • Добавление разрешений в веб-API с предоставлением их в качестве областей
• Настройка клиентского приложения для доступа к веб-API
  • Добавьте запросы разрешений в соответствии с областями, определенными для API, в разделе "Добавление разрешений для доступа к веб-API".

Теперь, когда вы завершили регистрацию клиентского приложения, перейдите к коду клиента, где создадите запрос REST и обработаете ответ.

Создание запроса

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

Получение маркера доступа

После действительной регистрации клиента можно выполнить интеграцию с Microsoft Entra ID получить маркер доступа двумя способами:

• Конечные точки службы OAuth2, не зависящие от платформы и языка, которые мы используем в этой статье. Инструкции, приведенные в этом разделе, не предполагают ничего о платформе или языке или скрипте клиента при использовании конечных точек Microsoft Entra OAuth. Единственное требование заключается в том, чтобы вы могли отправлять и получать HTTPS-запросы к Microsoft Entra ID и анализировать ответное сообщение.
• Библиотеки проверки подлинности Майкрософт (MSAL) для конкретных платформ и языков, которые выходят за рамки область этой статьи. Библиотеки предоставляют асинхронные оболочки для запросов конечной точки OAuth2 и надежные функции обработки маркеров, такие как кэширование и управление маркерами обновления. Дополнительные сведения см. в статье Обзор библиотеки проверки подлинности Майкрософт (MSAL).

Две конечные точки Microsoft Entra, используемые для проверки подлинности клиента и получения маркера доступа, называются конечными точками OAuth2 /authorize и /token . Способ их использования зависит от регистрации приложения и типа потока предоставления авторизации OAuth2 , необходимого для поддержки приложения во время выполнения. В этой статье предполагается, что клиент использует один из следующих потоков предоставления авторизации: код авторизации или учетные данные клиента. Чтобы получить маркер доступа, используемый в остальных разделах, следуйте инструкциям для потока, который лучше всего соответствует вашему сценарию.

Предоставление кода авторизации (интерактивные клиенты)

Это предоставление используется как веб-клиентами, так и собственными клиентами, требуя учетные данные от вошедшего пользователя, чтобы делегировать доступ к ресурсам клиентскому приложению. Она использует конечную /authorize точку для получения кода авторизации (в ответ на вход или согласие пользователя), а затем /token конечная точка для обмена кода авторизации на маркер доступа.

1. Во-первых, клиенту необходимо запросить код авторизации у Microsoft Entra ID. Дополнительные сведения о формате HTTPS-запроса GET к /authorize конечной точке и примеры запросов и ответных сообщений см. в разделе Запрос кода авторизации. Универсальный код ресурса (URI) содержит следующие параметры строки запроса, относящиеся к клиентскому приложению:

   • client_id: ИДЕНТИФИКАТОР GUID, назначенный клиентскому приложению во время регистрации, также известный как идентификатор приложения.

   • redirect_uri: версия одного из URI ответа или перенаправления в кодировке URL-адреса, указанная во время регистрации клиентского приложения. Передаваемое значение должно точно соответствовать значению регистрации.

   • resource: универсальный код ресурса (URI) идентификатора в кодировке URL-адреса, указанный вызываемым REST API. Веб-api или REST API (также называемые приложениями ресурсов) могут предоставлять один или несколько URI идентификаторов приложений в своей конфигурации. Пример:

     • API поставщика azure Resource Manager (и классической модели развертывания) используют https://management.core.windows.net/.
     • Сведения о других ресурсах см. в документации по API или конфигурации приложения ресурсов в портал Azure. Дополнительные сведения см. в identifierUris разделе Свойство объекта приложения Microsoft API Graph.

   Запрос к конечной точке /authorize сначала запускает запрос на вход для проверки подлинности пользователя. Возвращаемый ответ доставляется в виде перенаправления (302) на универсальный код ресурса (URI), указанный в redirect_uri. Сообщение заголовка location ответа содержит поле, содержащее универсальный код ресурса (URI) перенаправления, за которым следует code параметр запроса. Параметр code содержит код авторизации, необходимый для шага 2.

2. Затем клиенту необходимо активировать код авторизации для маркера доступа. Дополнительные сведения о формате запроса HTTPS POST к /token конечной точке и примеры запросов и ответов см. в разделе Запрос маркера доступа. Так как это запрос POST, вы упаковывание параметров приложения в текст запроса. В дополнение к некоторым из ранее упомянутых параметров (наряду с другими новыми), вы будете передавать:

   • code: этот параметр запроса содержит код авторизации, полученный на шаге 1.

   • client_secret: этот параметр нужен только в том случае, если клиент настроен как веб-приложение. Это то же значение секрета или ключа, которое вы создали ранее при регистрации клиента.

Предоставление учетных данных клиента (неинтерактивные клиенты)

Это разрешение используется только веб-клиентами, позволяя приложению напрямую обращаться к ресурсам (без делегирования пользователей) с помощью учетных данных клиента, которые предоставляются во время регистрации. Предоставление обычно используется неинтерактивными клиентами (без пользовательского интерфейса), которые выполняются как служба или управляющая программа. Для получения маркера доступа требуется только /token конечная точка.

Взаимодействие клиента и ресурса для этого разрешения аналогично шагу 2 предоставления кода авторизации. Дополнительные сведения о формате запроса HTTPS POST к /token конечной точке и примеры запросов и ответов см. в разделе "Получение маркера" статьи платформа удостоверений Майкрософт и поток учетных данных клиента OAuth 2.0.

Сборка сообщения запроса

Большинство языков программирования или платформ и сред сценариев упрощают сборку и отправку сообщения запроса. Обычно они предоставляют веб-класс или HTTP-класс или API, который абстрагирует создание или форматирование запроса, упрощая написание клиентского кода (HttpWebRequestнапример, класса в платформа .NET Framework). Для краткости и из-за того, что большая часть задачи обрабатывается автоматически, в этом разделе рассматриваются только важные элементы запроса.

Универсальный код ресурса (URI) запроса

Так как конфиденциальная информация передается и получается, все запросы REST требуют протокола HTTPS для схемы URI, предоставляя запросу и ответу безопасный канал. Сведения (т. е. код Microsoft Entra авторизации, маркер доступа или носителя и конфиденциальные данные запросов и ответов) шифруются более низким уровнем транспорта, обеспечивая конфиденциальность сообщений.

Оставшаяся часть URI запроса службы (узел, путь к ресурсу и все необходимые параметры строки запроса) определяется соответствующей спецификацией REST API. Например, API поставщика azure Resource Manager используют https://management.azure.com/, а классическую модель развертывания Azure — https://management.core.windows.net/. Для обоих требуется api-version параметр строки запроса.

Заголовок запроса

Универсальный код ресурса (URI) запроса входит в заголовок сообщения запроса, а также все дополнительные поля, необходимые для спецификации REST API службы и спецификации HTTP. Для запроса могут потребоваться следующие общие поля заголовка:

• Authorization: содержит токен носителя OAuth2 для защиты запроса, полученный ранее из Microsoft Entra ID.
• Content-Type: обычно устанавливается значение "application/json" (пары "имя-значение" в формате JSON) и указывает тип MIME текста запроса.
• Host: доменное имя или IP-адрес сервера, на котором размещена конечная точка службы REST.

Текст запроса

Как упоминалось ранее, текст сообщения запроса является необязательным в зависимости от конкретной операции, которую вы запрашиваете, и требований к ее параметрам. Если это необходимо, спецификация API для запрашиваемой службы также указывает кодировку и формат.

Текст запроса отделяется от заголовка пустой строкой в соответствии с полем заголовка Content-Type . Пример текста в формате application/json будет выглядеть следующим образом:

{
  "<name>": "<value>"
}

Отправка запроса

Теперь, когда у вас есть универсальный код ресурса (URI) запроса службы и создан соответствующий заголовок и текст сообщения запроса, вы можете отправить запрос в конечную точку службы REST.

Например, вы можете отправить метод запроса HTTPS GET для поставщика Resource Manager Azure, используя поля заголовка запроса, аналогичные приведенным ниже (обратите внимание, что текст запроса пуст):

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Вы также можете отправить метод запроса HTTPS PUT для поставщика Resource Manager Azure, используя поля заголовка и текста запроса, как показано в следующем примере:

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

После выполнения запроса возвращаются заголовок ответного сообщения и необязательный текст.

Обработка ответного сообщения

Процесс завершается двумя последними из пяти компонентов.

Чтобы обработать ответ, выполните синтаксический анализ заголовка ответа и, при необходимости, текста ответа (в зависимости от запроса). В примере HTTPS GET, приведенном в предыдущем разделе, вы использовали конечную точку /subscriptions для получения списка подписок для пользователя. При условии, что ответ был успешным, вы должны получить поля заголовка ответа, аналогичные следующему примеру:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

Кроме того, вы получите текст ответа, содержащий список подписок Azure и их отдельные свойства, закодированные в формате JSON, примерно так:

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Аналогичным образом для примера HTTPS PUT вы должны получить заголовок ответа, аналогичный следующему, с подтверждением успешности операции PUT по добавлению ExampleResourceGroup:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

Кроме того, вы получите текст ответа, который подтверждает содержимое добавленной группы ресурсов, закодированное в формате JSON, примерно так:

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Как и в случае с запросом, большинство языков программирования и платформ упрощают обработку ответного сообщения. Как правило, они возвращают эти сведения приложению после запроса, что позволяет обрабатывать их в типизированном или структурированном формате. В основном вы заинтересованы в подтверждении кода состояния HTTP в заголовке ответа и анализе текста ответа в соответствии со спецификацией API (или Content-Type полями заголовка ответа и Content-Length ).

Асинхронные операции, регулирование и разбиение по страницам

Шаблон создания, отправки и обработки ответа, рассматриваемый в этой статье, является синхронным и применяется ко всем сообщениям REST. Однако некоторые службы также поддерживают асинхронную модель, которая требует дополнительной обработки заголовков ответов для отслеживания или выполнения асинхронного запроса. Дополнительные сведения см. в разделе Отслеживание асинхронных операций Azure.

Resource Manager применяет ограничение на количество запросов на чтение и запись в час, чтобы предотвратить отправку приложением слишком большого количества запросов. Если приложение превышает эти ограничения, запросы регулируются. Заголовок ответа содержит количество оставшихся запросов для область. Дополнительные сведения см. в статье Throttling Resource Manager requests (Регулирование запросов Resource Manager).

Некоторые операции со списком возвращают свойство с именем nextLink в тексте отклика. Это свойство отображается, если результаты слишком велики для возврата в одном ответе. Как правило, ответ включает свойство nextLink, когда операция со списком возвращает более 1000 элементов. Если nextLink отсутствует в результатах, возвращаемые результаты завершаются. Если nextLink содержит URL-адрес, возвращаемые результаты являются частью всего результированного набора.

Ответ имеет следующий формат:

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

Чтобы получить следующую страницу результатов, отправьте запрос GET на URL-адрес в свойстве nextLink. URL-адрес содержит маркер продолжения, указывающий, где вы находитесь в результатах. Продолжайте отправлять запросы на URL-адрес nextLink, пока он не будет содержать URL-адрес в возвращаемых результатах.

Устойчивость API Azure

Rest API Azure предназначены для обеспечения устойчивости и непрерывной доступности. Операции уровня управления (запросы, отправленные в management.azure.com) в REST API:

• Распределяются между регионами. Некоторые службы являются региональными.

• Распределяются между зонами доступности (как и регионами) в расположениях с несколькими зонами доступности.

• Не зависят от единственного логического центра обработки данных.

• Никогда не отключаются для операций обслуживания.

См. также

Вот и все. После регистрации приложения Microsoft Entra и использования модульного метода получения маркера доступа и обработки HTTP-запросов можно довольно легко реплицировать код, чтобы воспользоваться преимуществами новых ИНТЕРФЕЙСов REST API. Дополнительные сведения о регистрации приложений и модели программирования Microsoft Entra см. в документации по платформа удостоверений Майкрософт.

Сведения о тестировании HTTP-запросов и ответов см. в разделе:

• Фиддлер. Fiddler — это бесплатный прокси-сервер веб-отладки, который может перехватывать запросы REST, что упрощает диагностику сообщений запросов и ответов HTTP.
• JWT.ms, которые позволяют быстро и легко создавать дампы утверждений в маркере носителя, чтобы можно было проверить их содержимое.