Разработка с помощью API Служб мультимедиа версии 3
Предупреждение
Поддержка Служб мультимедиа Azure будет прекращена 30 июня 2024 г. Дополнительные сведения см. в руководстве по прекращению поддержки AMS.
Как разработчик вы можете использовать клиентские библиотеки (.NET, Python, Node.js, Java и Go), которые позволяют взаимодействовать с REST API для простого создания, контроля и обслуживания настраиваемых рабочих процессов для мультимедиа. API Служб мультимедиа версии 3 основан на спецификации OpenAPI (ранее известной как Swagger).
Эта статья содержит сведения о правилах для работы с сущностями и API при разработке с использованием Служб мультимедиа версии 3.
Предупреждение
Не рекомендуется пытаться переносить REST API для Служб мультимедиа непосредственно в собственный код библиотеки, так как для надлежащего выполнения этого процесса в рабочей среде, потребуется реализовать всю логику повторных попыток управления ресурсами Azure и понять, как управлять длительными операциями в интерфейсах API управления ресурсами Azure. Такая обработка выполняется клиентскими пакетами SDK для разных языков (.NET, Java, TypeScript, Python и т. д.) автоматически и уменьшает вероятность возникновения проблем с логикой повторных попыток или вызовами API, завершившимися сбоем. Клиентские пакеты SDK уже выполняют такую обработку.
Доступ к API Служб мультимедиа Azure
Чтобы получить разрешение для доступа к ресурсам служб мультимедиа и API служб мультимедиа, вы должны пройти аутентификацию. Службы мультимедиа поддерживают аутентификацию на основе Azure Active Directory (Azure AD). Два распространенных способа аутентификации:
- Аутентификация на основе субъекта-службы используется для аутентификации службы (веб-приложений, приложений-функций, приложений логики, интерфейсов API и микрослужб). Этот метод аутентификации обычно используют приложения, которые выполняют службы управляющей программы, службы среднего уровня или запланированные задания. Например, для веб-приложений всегда должен существовать промежуточный уровень, который подключается к Службам мультимедиа через субъект-службу.
- Аутентификация пользователя используется для аутентификации пользователя, который использует приложение для взаимодействия с ресурсами Служб мультимедиа. Интерактивное приложение должно сначала запросить у пользователя учетные данные. Примером может послужить приложение консоли управления, которое используется авторизованными пользователями для мониторинга заданий кодирования или потоковой трансляции.
API Служб мультимедиа требует, чтобы у пользователя или приложения, выполняющего запросы к REST API, был доступ к ресурсу учетной записи Служб мультимедиа и роль участника или владельца. К API можно обращаться и с ролью читателя, но в этом случае будут доступны только операции Get и List. Дополнительные сведения см. в статье Управление доступом на основе ролей Azure (Azure RBAC) для учетных записей Служб мультимедиа.
Вместо создания субъекта-службы вы можете применить управляемые удостоверения ресурсов Azure для доступа к API Служб мультимедиа через Azure Resource Manager. Дополнительные сведения об управляемых удостоверениях в ресурсах Azure см. в статье Что такое управляемые удостоверения для ресурсов Azure?.
Субъект-служба Azure AD
Приложение Azure AD и субъект-служба должны находиться в одном арендаторе. После создания приложения назначьте ему роль участника или владельца для учетной записи Служб мультимедиа.
Если вы не уверены, что имеете достаточные полномочия для создания приложения Azure AD, изучите описанные здесь требования.
На следующем рисунке цифры обозначают поток запросов в хронологическом порядке.
Приложение среднего уровня запрашивает маркер доступа Azure AD, который содержит следующие параметры:
- Конечная точка клиента Azure AD.
- Универсальный код ресурса (URI) для ресурса служб мультимедиа.
- Универсальный код ресурса (URI) для ресурса REST служб мультимедиа.
- Значения для приложения Azure AD: идентификатор и секрет клиента.
Чтобы получить все необходимые значения, воспользуйтесь инструкцией из этой статьи.
Маркер доступа Azure AD передается на средний уровень.
Средний уровень отправляет запрос к REST API служб мультимедиа Azure с помощью маркера Azure AD.
Средний уровень получает данные из служб мультимедиа.
Примеры
Следующие примеры демонстрируют подключение с использованием субъекта-службы Azure Active Directory.
- Подключение с помощью .NET
- Подключение с помощью Node.js
- Подключение с помощью Python
- Подключение с помощью Java
Соглашения об именовании.
К именам ресурсов Служб мультимедиа версии 3 (например, "Ресурсы", "Задания", "Преобразования") применяются ограничения именования Azure Resource Manager. В соответствии с Azure Resource Manager имена ресурсов всегда уникальны. Таким образом, вы можете использовать любые уникальные строки идентификаторов (например, GUID) для имен ваших ресурсов.
Имена ресурсов Служб мультимедиа не могут включать: "<", "", ">%", "&", ":", "\", "?", "/", "*", "+", ".", одинарные кавычки или любые управляющие символы. Все остальные символы разрешены. Максимальная длина имени ресурса составляет 260 символов.
Дополнительные сведения об именовании в Azure Resource Manager см. в разделе о требованиях к именованию и в статье Соглашения об именовании.
Имена файлов и больших двоичных объектов в ресурсе
Имена файлов и больших двоичных объектов в ресурсе должны соответствовать как требованиям к именованию больших двоичных объектов, так и требованиям к именованию для NTFS. Это связано с тем, что такие файлы могут копироваться для обработки из хранилища BLOB-объектов на локальный диск NTFS.
Длительные операции
Операции, для которых в файлах Swagger для Служб мультимедиа Azure указан атрибут x-ms-long-running-operation, считаются длительными.
Сведения об отслеживании асинхронных операций в Azure см. в этой статье.
Службы мультимедиа используют следующие длительные операции:
-
Используйте параметр
removeOutputsOnStop, чтобы удалить все связанные записи трансляции при ее остановке.
После успешной передачи длительной операции вы получите ответ "201 (Создано)" и должны будете выполнить опрос на завершение операции с помощью возвращенного идентификатора операции.
В статье Track asynchronous Azure operations (Отслеживание асинхронных операций Azure) приведены подробные сведения о том, как отслеживать состояние асинхронных операций Azure с помощью значений, возвращаемых в ответе.
Для каждого события трансляции или любой из связанной с ним записи трансляции поддерживается только одна длительная операция. Запущенная длительная операция должна завершиться, прежде чем удастся запустить следующую длительную операцию для того же события трансляции или любой из связанной с ним записи трансляции. Для трансляций с несколькими записями необходимо дождаться завершения длительной операции в одной из записей трансляции, прежде чем начинать длительную операцию в другой записи.
Пакеты SDK
Примечание
Пакеты SDK для Служб мультимедиа Azure версии 3 не гарантируют потокобезопасность. При разработке приложений с несколькими потоками нужно добавить собственную логику синхронизации потоков, чтобы защитить клиент, или использовать новый объект AzureMediaServicesClient для каждого потока. Также помните, что предоставляемые кодом клиенту дополнительные объекты (например, экземпляр HttpClient в .NET) могут создавать проблемы при обработке нескольких потоков.
См. также раздел
- Пакет SDK .NET EventGrid, который включает события Служб мультимедиа
- Определения событий Служб мультимедиа
Обозреватель Служб мультимедиа Azure
Обозреватель Служб мультимедиа Azure (AMSE) — это инструмент, доступный для клиентов Windows, которые хотят узнать о Службах мультимедиа. AMSE — это приложение Winforms или C#, которое отправляет, скачивает, кодирует, транслирует видео по запросу и в режиме реального времени с помощью Служб мультимедиа. Инструмент AMSE предназначен для клиентов, которые хотят протестировать Службы мультимедиа без написания кода. Код AMSE предоставляется как ресурс для клиентов, которым необходима разработка с помощью Служб мультимедиа.
AMSE — это проект с открытым кодом, поддержка которого предоставляется сообществом (о проблемах можно сообщать по ссылке https://github.com/Azure/Azure-Media-Services-Explorer/issues). В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в статье Вопросы и ответы, связанные с правилами поведения. Чтобы задать вопрос или получить комментарии, обратитесь по адресу opencode@microsoft.com.
Фильтрация, упорядочивание и разбиение по страницам сущностей Служб мультимедиа
Ознакомьтесь со статьей Фильтрация, упорядочение и разбиение на страницы сущностей Служб мультимедиа.
Справка и поддержка
Вы можете обратиться к Службам мультимедиа с вопросами или следить за нашими обновлениями одним из следующих способов:
- ВОПРОСЫ И ОТВЕТЫ
- Stack Overflow. Пометьте вопросы тегом
azure-media-services. - @MSFTAzureMedia или используйте @AzureSupport , чтобы запросить поддержку.
- Отправьте запрос в службу поддержки через портал Azure.