Справочник по REST API Azure
Добро пожаловать в справочник по REST API Azure.
API-интерфейсы REST — это конечные точки службы, поддерживающие наборы http-операций (методов), которые предоставляют доступ к ресурсам службы для создания, извлечения, обновления и удаления. В следующих разделах вы узнаете:
- Основные компоненты пары "запрос и ответ" REST API
- Как зарегистрировать клиентское приложение в Azure Active Directory (Azure AD) для защиты запросов REST
- Общие сведения о создании и отправке запроса REST, а также об обработке ответа
Примечание
Большинство ИНТЕРФЕЙСов REST API службы Azure имеют соответствующую библиотеку клиентского пакета SDK, которая обрабатывает большую часть клиентского кода. См.
Компоненты запроса и ответа API REST
Пару запросов и ответов REST API можно разделить на 5 компонентов:
- URI запроса, который состоит из:
{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}
. Обратите внимание, что мы вызываем эту функцию отдельно, так как в большинстве языков и платформ требуется передать его отдельно от сообщения запроса, но на самом деле он включен в заголовок сообщения запроса.- Схема URI: указывает протокол, используемый для передачи запроса. Например,
http
илиhttps
. - Узел URI: доменное имя или IP-адрес сервера, на котором размещена конечная точка службы REST, например
graph.microsoft.com
- Путь к ресурсу: указывает ресурс или коллекцию ресурсов, которая может включать несколько сегментов, используемых службой при определении выбора этих ресурсов. Например:
beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners
может использоваться для запроса списка владельцев определенного приложения в коллекции приложений. - Строка запроса (необязательно): используется для предоставления дополнительных простых параметров, таких как версия API, критерии выбора ресурсов и т. д.
- Схема URI: указывает протокол, используемый для передачи запроса. Например,
- Поля заголовка сообщения HTTP-запроса
- Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции вы запрашиваете. Rest API Azure поддерживают методы GET, HEAD, PUT, POST и PATCH.
- Необязательные дополнительные поля заголовка в соответствии с требованиями указанного URI и метода HTTP. Например, заголовок авторизации, предоставляющий маркер носителя, содержащий сведения об авторизации клиента для запроса.
- Необязательные поля текста сообщения запроса HTTP для поддержки URI и операции HTTP. Например, операции POST содержат объекты в кодировке MIME, передаваемые в виде сложных параметров. Тип кодирования MIME для текста также должен быть указан в заголовке
Content-type
запроса для операций POST/PUT. Обратите внимание, что для некоторых служб требуется использовать определенный тип MIME, напримерapplication/json
. - Поля заголовка сообщения http-ответа
- Код состояния HTTP в диапазоне от кодов успешного выполнения 2xx до кодов ошибок 4xx/5xx. Кроме того, может быть возвращен определяемый службой код состояния, как указано в документации по API.
- Необязательные дополнительные поля заголовка, необходимые для поддержки ответа запроса, например
Content-type
заголовок ответа.
- Необязательные поля текста сообщения HTTP-ответа
- Объекты ответа в кодировке MIME могут возвращаться в тексте ОТВЕТА HTTP, например ответ от метода GET, возвращающего данные. Как правило, они возвращаются в структурированном формате в формате JSON или XML, как указано в заголовке
Content-type
ответа. Например, при запросе маркера доступа из Azure AD он возвращается в тексте ответа в видеaccess_token
элемента , одного из нескольких парных объектов "имя-значение" в коллекции данных. В этом примере также будет включен заголовокContent-Type: application/json
ответа .
- Объекты ответа в кодировке MIME могут возвращаться в тексте ОТВЕТА HTTP, например ответ от метода GET, возвращающего данные. Как правило, они возвращаются в структурированном формате в формате JSON или XML, как указано в заголовке
Регистрация клиентского приложения с помощью Azure AD
Большинство служб Azure (например, поставщики azure Resource Manager и классические API управления службами) требуют, чтобы клиентский код прошел проверку подлинности с использованием действительных учетных данных, прежде чем можно будет вызвать API службы. Проверка подлинности координируется между различными субъектами Azure AD, которая предоставляет клиенту маркер доступа в качестве подтверждения проверки подлинности или авторизации. Затем маркер отправляется в службу Azure в заголовке HTTP Authorization всех последующих запросов REST API. Утверждения маркера также предоставляют сведения службе, что позволяет ей проверить клиент и выполнить необходимую авторизацию.
Если вы используете REST API, который не использует встроенную проверку подлинности Azure AD, или вы уже зарегистрировали клиент, можно перейти к разделу Создание запроса.
Предварительные требования
Клиентское приложение должно сделать конфигурацию удостоверений известной для Azure AD перед выполнением, зарегистрировав ее в клиенте Azure AD. Ниже приведен список элементов, которые следует учитывать перед регистрацией клиента в Azure AD:
- Если у вас еще нет Azure AD клиента, см. статью Как получить клиент Azure Active Directory.
- В рамках OAuth2 Authorization Framework Azure AD поддерживает 2 типа клиентов. Понимание каждого из них поможет вам решить, какой из них лучше всего подходит для вашего сценария:
- веб-клиенты или конфиденциальные клиенты (запускаемые на веб-сервере) могут получать доступ к ресурсам по собственному удостоверению (т. е. службе или управляющей программе) или получить делегированную авторизацию для доступа к ресурсам под удостоверением вошедшего пользователя (т. е. веб-приложение). Только веб-клиент может безопасно хранить и представлять свои учетные данные во время проверки подлинности Azure AD для получения маркера доступа.
- Собственные и общедоступные клиенты (установленные или запущенные на устройстве) могут получать доступ к ресурсам только при делегированной авторизации, используя удостоверение вошедшего пользователя для получения маркера доступа от имени пользователя.
- В процессе регистрации в клиенте Azure AD, где зарегистрировано приложение, будут созданы 2 связанных объекта: объект приложения и объект субъекта-службы. Дополнительные сведения об этих компонентах и их использовании во время выполнения см. в статье Объекты приложения и субъекта-службы в Azure Active Directory.
Теперь мы готовы зарегистрировать клиентское приложение в Azure AD.
Регистрация клиента
Чтобы зарегистрировать клиент, который будет обращаться к Azure Resource Manager REST API, см. пошаговые инструкции по регистрации с помощью портала для создания приложения Active Directory и субъекта-службы, который может получить доступ к ресурсам. В этой статье (также доступной в версиях PowerShell и CLI для автоматизации регистрации) показано, как:
- регистрация клиентского приложения с помощью Azure AD
- настройка запросов разрешений, чтобы разрешить клиенту доступ к API Resource Manager Azure
- настройка параметров контроль доступа на основе ролей (RBAC) в Azure Resource Manager для авторизации клиента
Для всех остальных клиентов см. статью Интеграция приложений с Azure Active Directory. Эта статья покажет вам, как выполнить следующие действия:
- Зарегистрируйте клиентское приложение с помощью Azure AD в разделе "Добавление приложения"
- создайте секретный ключ (если вы регистрируете веб-клиент) в разделе "Обновление приложения"
- добавление запросов разрешений в соответствии с требованиями API в разделе "Обновление приложения"
Теперь, когда вы завершили регистрацию клиентского приложения, мы можем перейти к клиентскому коду, где вы создадите запрос REST и обработаете ответ.
Создание запроса
В этом разделе рассматриваются первые 3 из 5 компонентов, которые мы обсуждали ранее. Сначала необходимо получить маркер доступа из Azure AD, который мы будем использовать при сборке заголовка сообщения запроса.
Получение маркера доступа
После получения действительной регистрации клиента существует два способа интеграции с Azure AD для получения маркера доступа:
- Azure AD конечные точки службы OAuth2, не зависящие от платформы или языка, которые мы будем использовать. Как и в случае с конечными точками AZURE REST API, инструкции, приведенные в этом разделе, не делают никаких предположений о платформе или языке или скрипте клиента при использовании конечных точек Azure AD. Только они могут отправлять и получать HTTPS-запросы в Azure AD и анализировать ответное сообщение.
- Библиотеки проверки подлинности Майкрософт (MSAL) для конкретной платформы или языка. Библиотеки предоставляют асинхронные оболочки для запросов конечной точки OAuth2 и надежные функции обработки маркеров, такие как кэширование и управление маркерами обновления. Дополнительные сведения, включая справочную документацию, скачиваемую библиотеку и примеры кода, см. в статье Библиотеки проверки подлинности Майкрософт.
2 Azure AD конечных точек, которые вы будете использовать для проверки подлинности клиента и получения маркера доступа, называются конечными точками OAuth2 /authorize
и /token
. Способ их использования будет зависеть от регистрации приложения и типа потока предоставления авторизации OAuth2 , необходимого для поддержки приложения во время выполнения. В рамках этой статьи предполагается, что клиент будет использовать один из следующих потоков предоставления авторизации: код авторизации или учетные данные клиента. Следуйте инструкциям для того, который лучше всего соответствует вашему сценарию, чтобы получить маркер доступа, который будет использоваться в остальных разделах.
Предоставление кода авторизации (интерактивные клиенты)
Это предоставление может использоваться как веб-клиентами, так и собственными клиентами. Для делегирования доступа к ресурсам клиентскому приложению требуются учетные данные пользователя, выполнившего вход. Она использует конечную /authorize
точку для получения кода авторизации (в ответ на вход или согласие пользователя), а затем /token
конечная точка для обмена кода авторизации на маркер доступа.
Сначала клиенту потребуется запросить код авторизации у Azure AD. Дополнительные сведения о формате httpS-запроса GET к
/authorize
конечной точке и примеры запросов и ответных сообщений см. в разделе Запрос кода авторизации. Универсальный код ресурса (URI) будет содержать параметры строки запроса, включая следующие параметры, относящиеся к клиентскому приложению:client_id
— также известный как идентификатор приложения. Это GUID, назначенный клиентскому приложению при регистрации в разделе выше.redirect_uri
— версия закодированного URL-адреса [одного из] URI ответа или перенаправления, указанных при регистрации клиентского приложения. Обратите внимание, что передаваемое значение должно точно соответствовать вашей регистрации!resource
— URI идентификатора в кодировке URL- адреса, указанный вызываемым REST API. Веб-api или REST API (также называемые приложениями ресурсов) могут предоставлять один или несколько URI идентификаторов приложений в своей конфигурации. Пример:- Api поставщика Resource Manager Azure (и классического управления службами) используются
https://management.core.windows.net/
- Другие ресурсы см. в документации по API или в конфигурации приложения ресурсов в портал Azure. Дополнительные сведения см. также в
identifierUris
свойстве объекта приложения Azure AD.
- Api поставщика Resource Manager Azure (и классического управления службами) используются
Запрос к конечной точке
/authorize
сначала инициирует запрос на вход для проверки подлинности конечного пользователя. Ответ, который вы получите, будет доставлен в виде перенаправления (302) на URI, указанный вredirect_uri
. Сообщение заголовкаlocation
ответа будет содержать поле, содержащее URI перенаправления, за которым следуетcode
параметр запроса, содержащий код авторизации, необходимый для шага 2.Затем клиенту потребуется активировать код авторизации для маркера доступа. Дополнительные сведения о формате HTTPS-запроса POST к
/token
конечной точке и примерах сообщений запросов и ответов см. в статье Использование кода авторизации для запроса маркера доступа. Так как это запрос POST, на этот раз вы будете упаковывание параметров конкретного приложения в текст запроса. В дополнение к некоторым из упомянутых выше (вместе с другими новыми), вы будете передавать :code
— это параметр запроса, который будет содержать код авторизации, полученный на шаге 1.client_secret
— этот параметр понадобится только в том случае, если клиент настроен в качестве веб-приложения. Это то же значение секрета или ключа, которое вы создали ранее при регистрации клиента.
Предоставление учетных данных клиента (неинтерактивные клиенты)
Это разрешение может использоваться только веб-клиентами, позволяя приложению напрямую получать доступ к ресурсам (без делегирования пользователей), используя собственные учетные данные клиента, которые предоставляются во время регистрации. Обычно он используется неинтерактивными клиентами (без пользовательского интерфейса), работающими в качестве управляющей программы или службы, и для получения маркера доступа требуется только /token
конечная точка.
Взаимодействие между клиентом и ресурсом для этого разрешения очень похоже на шаг 2 предоставления кода авторизации. Дополнительные сведения о формате запроса HTTPS POST к /token
конечной точке и примерах сообщений запроса HTTPS POST см. в разделе "Запрос маркера доступа" статьи Обслуживание вызовов службы с использованием учетных данных клиента.
Сборка сообщения запроса
Обратите внимание, что большинство языков программирования, платформ и сред сценариев упрощают сборку и отправку сообщения запроса. Обычно они предоставляют класс web/HTTP или API, который абстрагирует создание и форматирование запроса, упрощая написание клиентского кода (например, класс HttpWebRequest в платформа .NET Framework). Для краткости мы рассмотрим только важные элементы запроса, учитывая, что большинство из них будет обработано за вас.
Универсальный код ресурса (URI) запроса
Все защищенные запросы REST требуют протокола HTTPS для схемы URI, предоставляя запрос и ответ с помощью безопасного канала, из-за того, что конфиденциальная информация передается или получается. Эта информация (т. е. код Azure AD авторизации, маркер доступа и маркер носителя, конфиденциальные данные запросов и ответов) шифруется более низким уровнем транспорта, обеспечивая конфиденциальность сообщений.
Оставшаяся часть URI запроса службы (узел, путь к ресурсу и все необходимые параметры строки запроса) будет определяться соответствующей спецификацией REST API. Например, API поставщика Azure Resource Manager используют https://management.azure.com/
, классические API управления службами Azure используют https://management.core.windows.net/
, оба требуют api-version
параметра строки запроса и т. д.
Заголовок запроса
Универсальный код ресурса (URI) запроса будет в комплекте с заголовком сообщения запроса, а также любыми дополнительными полями, определенными спецификацией REST API службы и спецификацией HTTP. Ниже приведены некоторые распространенные поля заголовка, которые могут потребоваться в запросе:
Authorization
: содержит токен носителя OAuth2 для защиты запроса, полученный ранее из Azure ADContent-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/03f09293-ce69-483a-a092-d06ea46dfb8c/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"
}
После выполнения запроса будут возвращены заголовок ответного сообщения и необязательный текст.
Обработка ответного сообщения
Теперь мы завершим работу с последними 2 из 5 компонентов.
Чтобы обработать ответ, необходимо проанализировать заголовок ответа и при необходимости текст ответа (в зависимости от запроса). В приведенном выше примере HTTPS GET мы использовали конечную точку /subscriptions для получения списка подписок для пользователя. Если ответ был успешным, мы должны получить поля заголовка ответа, аналогичные следующим:
HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;
и текст ответа, содержащий список подписок Azure и их отдельные свойства, закодированные в формате JSON, примерно так:
{
"value":[
{
"id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
"subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
"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/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
"name":"ExampleResourceGroup",
"location":"westus",
"properties":
{
"provisioningState":"Succeeded"
}
}
Как и в случае с запросом, большинство языков программирования и платформ упрощают обработку ответного сообщения. Они обычно возвращают эти сведения в приложение после запроса, что позволяет обрабатывать их в типизированном или структурированном формате. В основном вы будете заинтересованы в подтверждении кода состояния HTTP в заголовке ответа и, если это успешно, анализ текста ответа в соответствии со спецификацией API (или Content-Type
полями заголовка ответа и Content-Length
).
Вот и все! После регистрации приложения Azure AD и компонентного метода получения маркера доступа, создания и обработки HTTP-запросов можно довольно легко реплицировать код, чтобы воспользоваться преимуществами новых REST API.
См. также
- Дополнительные сведения о регистрации приложений и модели программирования Azure AD см. в статье платформа удостоверений Майкрософт (Azure Active Directory для разработчиков), в том числе полный индекс статей с практическими руководствами и кратким руководством, а также примеры кода.
- Для тестирования HTTP-запросов и ответов проверка out
- Fiddler. Fiddler — это бесплатный прокси-сервер веб-отладки, который может перехватывать запросы REST, что упрощает диагностику HTTP-запросов и ответных сообщений.
- Декодер JWT и JWT.io, которые позволяют быстро и легко создавать дампы утверждений в маркере носителя, чтобы можно было проверить их содержимое.
Используйте раздел комментариев LiveFyre, который следует за этой статьей, чтобы оставить отзыв и помочь нам уточнить и сформировать наше содержимое.