Проверка подлинности и авторизация для API службы "Аналитика временных рядов Azure"

Примечание.

Служба временных рядов Аналитика (TSI) больше не будет поддерживаться после марта 2025 года. Попробуйте перенести существующие среды TSI в альтернативные решения как можно скорее. Дополнительные сведения об устаревании и миграции см. в нашей документации.

В зависимости от потребностей вашего бизнеса ваше решение может включать одно или несколько клиентских приложений, которые используются для взаимодействия с API среды службы "Аналитика временных рядов Azure". Аналитика временных рядов Azure выполняет проверку подлинности с помощью Токены безопасности Microsoft Entra на основе OAUTH 2.0. Для проверки подлинности клиентов необходимо получить маркер носителя с нужными разрешениями и передать его вместе с вызовами API. В этом документе описано несколько методов получения учетных данных, которые можно использовать для получения маркера носителя и проверки подлинности, включая использование управляемого удостоверения и регистрации приложения Microsoft Entra.

Управляемые удостоверения

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

• Управление учетными данными не требуется. Учетные данные даже недоступны.
• Управляемые удостоверения можно использовать для проверки подлинности в любой службе Azure, поддерживающей проверку подлинности Microsoft Entra, включая Azure Key Vault.
• Управляемые удостоверения можно использовать без дополнительных затрат.

Дополнительные сведения о двух типах управляемых удостоверений см. в статье Что такое управляемые удостоверения для ресурсов Azure?

Вы можете использовать управляемые удостоверения из следующих источников:

• Виртуальные машины Azure
• Службы приложений Azure
• Функции Azure
• Экземпляры контейнеров Azure
• И другие

Полный список см. в разделе Службы Azure с поддержкой управляемых удостоверений для ресурсов Azure.

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

При возможности рекомендуется использовать управляемые удостоверения, чтобы не нужно было управлять учетными данными. Если клиентское приложение не размещено в службе Azure, поддерживающей управляемые удостоверения, вы можете зарегистрировать приложение в клиенте Microsoft Entra. При регистрации приложения с помощью идентификатора Microsoft Entra создается конфигурация удостоверения для приложения, которая позволяет интегрировать его с идентификатором Microsoft Entra. Регистрируя приложение на портале Azure, следует указать, является ли оно однотенантным (доступным только в вашем клиенте) или мультитенантным (доступным в других клиентах), и при необходимости установить URI перенаправления (куда отправляются маркеры доступа).

После завершения регистрации приложения вы получите глобальный уникальный экземпляр приложения (объект приложения), который находится в вашем домашнем клиенте или каталоге. Вам также будет предоставлен глобальный уникальный идентификатор приложения (идентификатор приложения или клиента). Затем на портале можно добавить секреты или сертификаты и области, чтобы обеспечить работу приложения, настроить его фирменную символику в диалоговом окне для входа и многое другое.

При регистрации приложения на портале в домашнем клиенте автоматически создаются объект приложения, а также объект субъекта-службы. Если вы регистрируете или создаете приложение с помощью Microsoft Graph API, создание объекта субъекта-службы выполняется на отдельном этапе. Для запроса токенов необходим объект субъекта-службы.

Ознакомьтесь с контрольным списком безопасности для своего приложения. Рекомендуется использовать учетные данные с сертификатом, а не учетные данные с паролем (секреты клиента).

Дополнительные сведения см . в разделе "Объекты приложения и субъекта-службы" в идентификаторе Microsoft Entra.

Шаг 1. Создание управляемого удостоверения или регистрация приложения

После определения того, будет ли использоваться управляемое удостоверение или регистрация приложения, ваш следующий шаг — подготовить выбранный вариант.

Управляемое удостоверение

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

• Виртуальные машины Azure
• Служба приложений и Функции Azure
• Экземпляры контейнеров Azure
• И другие

Регистрация приложения

Следуйте инструкциям в разделе Регистрация приложения.

• Выбрав соответствующую платформу в шаге 4 действий Настроить платформу, настройте свои URI перенаправления и Маркеры доступа в боковой панели справа от пользовательского интерфейса.

  • URI перенаправления должны соответствовать адресу, указанному в запросе аутентификации.

    • Для приложений, размещенных в локальной среде разработки, выберите Public client (mobile & desktop) (Общедоступный клиент (мобильный и классический)). Не забудьте задать для общедоступного клиента значение Да.
    • Для одностраничных приложений, размещенных в Службе приложений Azure, выберите Интернет.

  • Определите, подходит ли URL-адрес выхода.

  • Включите поток неявного предоставления разрешения, проверив маркеры доступа или токены идентификатора.

  

  Щелкните Настроить, а затем Сохранить.

• Свяжите приложение Microsoft Entra Аналитика временных рядов Azure. Последовательно выберите Разрешения API>Add a permission (Добавить разрешение)>Интерфейсы API, используемые моей организацией.

  

  Введите Azure Time Series Insights в строке поиска, а затем выберите Azure Time Series Insights.

• Затем укажите тип разрешения API, необходимый для приложения. По умолчанию будет выделен тип Делегированные разрешения. Выберите тип разрешения и щелкните Добавить разрешения.

  

• Добавить учетные данные, если приложение будет самостоятельно вызывать интерфейсы API среды. Учетные данные позволяют приложению проходить самостоятельную проверку подлинности, не требуя взаимодействия с пользователем во время выполнения.

Шаг 2. Предоставление доступа

Когда среда Аналитики временных рядов Azure получает запрос, сначала проверяется маркер носителя вызывающей стороны. Если проверка пройдена, вызывающая сторона проходит проверку подлинности, а затем выполняется другая проверка, чтобы убедиться, что вызывающая сторона авторизована для выполнения запрошенного действия. Для авторизации любого пользователя или субъекта-службы необходимо сначала предоставить им доступ к среде, назначив роль читателя или участника.

• Чтобы предоставить доступ через пользовательский интерфейс портала Azure, следуйте инструкциям, приведенным в статье Предоставление доступа к данным в среде. При выборе пользователя можно искать управляемое удостоверение или регистрацию приложения по имени или идентификатору.

• Чтобы предоставить доступ с помощью Azure CLI, выполните следующую команду. Полный список команд, доступных для управления доступом, см. в документации.

  az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"
  

Примечание.

Для расширения timeseriesinsights для Azure CLI требуется версия 2.11.0 или более поздняя. Расширение будет автоматически установлено при первом запуске команды az tsi access-policy. Подробнее о расширениях.

Шаг 3. Запрос маркеров

После подготовки управляемого удостоверения или регистрации приложения и назначения роли вы можете начать использовать их для запроса маркеров носителя OAuth 2.0. Метод, используемый для получения маркера, будет зависеть от того, где размещается код, и от выбранного языка. При указании ресурса (также известного как "аудитория" маркера) можно определить Аналитику временных рядов Azure по URL-адресу или GUID:

• https://api.timeseries.azure.com/
• 120d688d-1518-4cf7-bd38-182f158850b6

Важно!

При использовании URL-адреса в качестве идентификатора ресурса маркер должен быть выдан по точному адресу: https://api.timeseries.azure.com/. Требуется завершающая косая черта.

• Если вы используете Postman, AuthURL будет следующим: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
• https://api.timeseries.azure.com/ является действительным адресом, а https://api.timeseries.azure.com — нет.

Управляемые удостоверения

При доступе из Службы приложений Azure или Функций следуйте указаниям в статье Получение маркеров для ресурсов Azure.

Для приложений и функций .NET при работе с управляемым удостоверением проще всего использовать клиентскую библиотеку Azure Identity для .NET. Эта клиентская библиотека популярна благодаря своей простоте и безопасности. Разработчики могут написать код один раз и позволить клиентской библиотеке определять способ проверки подлинности в зависимости от среды приложения — на рабочей станции разработчика, использующей учетную запись разработчика, или развернутая в Azure с помощью управляемого удостоверения службы. Руководство по миграции из предшествующей библиотеки AppAuthentication см. в руководстве по миграции AppAuthentication в Azure.Identity.

Запрос маркера для Аналитики временных рядов Azure с помощью C# и клиентской библиотеки Azure Identity для .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Регистрация приложения

• Используйте библиотеку проверки подлинности Майкрософт (MSAL), чтобы получить маркеры для регистрации приложений.

MSAL можно использовать во многих сценариях приложений, включая следующие:

• одностраничные приложения (JavaScript);
• веб-приложения, в которые могут входить пользователи и которые могут вызывать веб-API от имени пользователя;
• веб-API, вызывающий другой подчиненный веб-API от имени выполнившего вход пользователя;
• классическое приложение, вызывающее веб-API от имени выполнившего вход пользователя;
• мобильное приложение, вызывающее веб-API от имени пользователя, вошедшего в систему в интерактивном режиме;
• классическая управляющая программа / управляющая программа службы, вызывающая веб-API от своего имени.

Пример кода на C#, демонстрирующий получение маркера в качестве регистрации приложения и запрос данных из среды 2-го поколения см. в примере приложения на сайте GitHub

Важно!

Если вы используете библиотеку проверки подлинности Azure Active Directory (ADAL), перейдите в MSAL.

Общие заголовки и параметры

В этом разделе описаны общие заголовки HTTP-запросов и параметры, используемые для выполнения запросов к API Аналитики временных рядов Azure 1-го и 2-го поколения. Требования к конкретному API подробно описаны в справочной документации по REST API Аналитики временных рядов Azure.

Совет

Дополнительные сведения об использовании интерфейсов REST API, а также о HTTP-запросах и обработке HTTP-ответов см. в справочнике по Azure REST API

Заголовки HTTP

Обязательные заголовки запроса описаны ниже.

Обязательный заголовок запроса	Description
Авторизация	Для проверки подлинности с помощью Аналитики временных рядов Azure необходимо передать допустимый маркер носителя OAuth 2.0 в заголовок Authorization.

Совет

Ознакомьтесь со статьей, посвященной примеру визуализации пакета SDK клиента, размещенному в службе Аналитики временных рядов Azure, чтобы узнать, как выполнять проверку подлинности с помощью API Аналитики временных рядов Azure программным способом с помощью пакета клиента SDK клиента для JavaScript (с диаграммами и графиками).

Дополнительные заголовки запроса описаны ниже.

Дополнительный заголовок запроса.	Description
Content-type	Поддерживается только application/json.
x-ms-client-request-id	Идентификатор запроса клиента Служба записывает это значение. Позволяет службе выполнять трассировку операций между службами.
x-ms-client-session-id	Идентификатор сеанса клиента. Служба записывает это значение. Позволяет службе выполнять трассировку группы связанных операций между службами.
x-ms-client-application-name	Имя приложения, создавшего этот запрос. Служба записывает это значение.

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

Заголовок ответа	Description
Content-type	Поддерживается только application/json.
x-ms-request-id	Идентификатор запроса, сформированный сервером. Можно использовать для обращения в корпорацию Майкрософт, чтобы исследовать запрос.
x-ms-property-not-found-behavior	Необязательный заголовок ответа API. Возможные значения: ThrowError (по умолчанию) или UseNull.

Параметры HTTP

Совет

Дополнительные сведения об обязательных и необязательных запросах см. в справочной документации.

Обязательные параметры строки запроса URL-адреса зависят от версии API.

Выпуск	Значения версии API
Поколение 1	api-version=2016-12-12
Поколение 2	api-version=2020-07-31

Необязательные параметры строки запроса URL-адреса включают установку времени ожидания для времени выполнения HTTP-запроса.

Необязательный параметр запроса	Description	Версия
timeout=<timeout>	Время ожидания на стороне сервера для выполнения HTTP-запроса. Применяется только к API получения событий среды и получения агрегатов среды. Значение времени ожидания должно быть в формате длительности ISO 8601 (например, "PT20S") и должно находиться в диапазоне 1-30 s. Значение по умолчанию: 30 s.	Поколение 1
storeType=<storeType>	Для сред 2-го поколения с включенным теплым хранилищем запрос можно выполнить либо в WarmStore, либо в ColdStore. Этот параметр в запросе определяет, в каком хранилище должен выполняться запрос. Если этот параметр не определен, запрос будет выполнен в холодном хранилище. Чтобы запросить теплое хранилище, параметру storeType следует присвоить значение WarmStore. Если этот параметр не определен, запрос будет выполнен для холодного хранилища.	Поколение 2

Следующие шаги

• Пример кода, который вызывает API Аналитики временных рядов Azure 1-го поколения, см. в статье Запрос данных 1-го поколения с помощью C#.

• Пример кода, который вызывает API Аналитики временных рядов Azure 2-го поколения, см. в статье Запрос данных 2-го поколения с помощью C#.

• Справочные сведения об API см. в справочной документации по API запроса.