Проверка подлинности и авторизация для 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. Здесь вы найдете инструкции по настройке управляемых удостоверений для следующих компонентов:
Регистрация приложения
Следуйте инструкциям в разделе Регистрация приложения.
Выбрав соответствующую платформу в шаге 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 запроса.