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

  • Статья

Добро пожаловать в справочник по REST API Azure.

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

  • Основные компоненты пары "запрос и ответ" REST API
  • Как зарегистрировать клиентское приложение в Azure Active Directory (Azure AD) для защиты запросов REST
  • Общие сведения о создании и отправке запроса REST, а также об обработке ответа

Примечание

Большинство ИНТЕРФЕЙСов REST API службы Azure имеют соответствующую библиотеку клиентского пакета SDK, которая обрабатывает большую часть клиентского кода. См.

Azure .NET SDK;
Пакет Azure SDK для Java
Azure CLI 2.0 SDK

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

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

  1. 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, критерии выбора ресурсов и т. д.
  2. Поля заголовка сообщения HTTP-запроса
    • Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции вы запрашиваете. Rest API Azure поддерживают методы GET, HEAD, PUT, POST и PATCH.
    • Необязательные дополнительные поля заголовка в соответствии с требованиями указанного URI и метода HTTP. Например, заголовок авторизации, предоставляющий маркер носителя, содержащий сведения об авторизации клиента для запроса.
  3. Необязательные поля текста сообщения запроса HTTP для поддержки URI и операции HTTP. Например, операции POST содержат объекты в кодировке MIME, передаваемые в виде сложных параметров. Тип кодирования MIME для текста также должен быть указан в заголовке Content-type запроса для операций POST/PUT. Обратите внимание, что для некоторых служб требуется использовать определенный тип MIME, например application/json.
  4. Поля заголовка сообщения http-ответа
    • Код состояния HTTP в диапазоне от кодов успешного выполнения 2xx до кодов ошибок 4xx/5xx. Кроме того, может быть возвращен определяемый службой код состояния, как указано в документации по API.
    • Необязательные дополнительные поля заголовка, необходимые для поддержки ответа запроса, например Content-type заголовок ответа.
  5. Необязательные поля текста сообщения HTTP-ответа
    • Объекты ответа в кодировке MIME могут возвращаться в тексте ОТВЕТА HTTP, например ответ от метода GET, возвращающего данные. Как правило, они возвращаются в структурированном формате в формате JSON или XML, как указано в заголовке Content-type ответа. Например, при запросе маркера доступа из Azure AD он возвращается в тексте ответа в виде access_token элемента , одного из нескольких парных объектов "имя-значение" в коллекции данных. В этом примере также будет включен заголовок Content-Type: application/json ответа .

Регистрация клиентского приложения с помощью 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 конечная точка для обмена кода авторизации на маркер доступа.

  1. Сначала клиенту потребуется запросить код авторизации у 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.

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

  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 AD
  • 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/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, который следует за этой статьей, чтобы оставить отзыв и помочь нам уточнить и сформировать наше содержимое.