Développer avec les API Media Services v3

  • Article

Logo de Media Services v3

Avertissement

Azure Media Services sera mis hors service le 30 juin 2024. Pour plus d’informations, consultez le Guide de mise hors service AMS.

En tant que développeur, vous pouvez utiliser des bibliothèques clientes (.NET, Python, Node.js, Java et Go) qui vous permettent d’interagir avec l’API REST afin de créer, de gérer et de maintenir facilement les workflows multimédias personnalisés. L’API Media Services v3 s’appuie sur la spécification OpenAPI (anciennement appelée Swagger).

Cet article décrit les règles qui s’appliquent aux entités et API lors du développement avec Media Services v3.

Avertissement

Il n’est pas recommandé de tenter d’envelopper l’API REST pour Media Services directement dans votre propre code de bibliothèque, car réaliser correctement cette opération à des fins de production vous oblige à implémenter la logique de nouvelle tentative complète de gestion des ressources Azure et à comprendre comment gérer les opérations durables dans les API de gestion des ressources Azure. Cette fonction est gérée automatiquement par les SDK clients pour différents langages (.NET, Java, TypeScript, Python, etc.) et réduit les risques de problèmes concernant la logique de nouvelle tentative ou les échecs d’appels d’API. Les kits SDK client gèrent déjà cette fonction pour vous.

Accéder à l'API Azure Media Services

Pour être autorisé à accéder aux ressources Media Services et à l’API Media Services, vous devez tout d’abord être authentifié. Media Services prend en charge l’authentification avec Azure Active Directory (Azure AD). Parmi les options d’authentification courantes figurent les suivantes :

  • Authentification d’un principal de service : Utilisée pour authentifier un service (applications web, applications de fonction, applications logiques, API et microservices, par exemple). Les applications qui utilisent généralement cette méthode d’authentification sont des applications qui exécutent des services démon, des services de niveau intermédiaire ou des travaux planifiés, Par exemple, pour les applications web, un niveau intermédiaire devrait toujours se connecter à Media Services avec un principal de service.
  • Authentification utilisateur : Utilisée pour authentifier une personne qui utilise l’application pour interagir avec les ressources Media Services. L’application interactive invite tout d’abord l’utilisateur à entrer ses informations d’identification. Par exemple, une application de console de gestion peut être utilisée par les utilisateurs autorisés pour contrôler les travaux d’encodage ou de streaming en direct.

L’API Media Services implique que l’utilisateur ou l'application à l'origine des requêtes API REST ait accès à la ressource de compte Media Services et utilise un rôle Contributeur ou Propriétaire. L’API est accessible avec le rôle Lecteur, mais seules les opérations Get ou List sont disponibles. Pour en savoir plus, consultez Contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour les comptes Media Services.

Au lieu de créer un principal de service, envisagez d’utiliser des identités gérées pour permettre aux ressources Azure d'accéder à l’API Media Services via Azure Resource Manager. Pour en savoir plus sur les identités managées pour les ressources Azure, consultez Que sont les identités managées pour les ressources Azure ?

Principal du service Azure AD

L’application Azure AD et le principal du service doivent se trouver dans le même locataire. Après avoir créé l’application, attribuez à l'application le rôle Contributeur ou Propriétaire pour accéder au compte Media Services.

Si vous ne savez pas si vous disposez des autorisations pour créer une application Azure AD, consultez Autorisations requises.

Dans la figure suivante, les nombres représentent le flux des requêtes dans l’ordre chronologique :

Authentification d’application de niveau intermédiaire avec AAD à partir d’une API web

  1. Une application de niveau intermédiaire nécessite un jeton d’accès Azure AD qui possède les paramètres suivants :

    • Point de terminaison de locataire Azure AD.
    • URI de ressource Media Services.
    • URI de ressource pour REST Media Services.
    • Valeurs de l’application Azure AD : ID client et secret client.

    Pour obtenir toutes les valeurs nécessaires, consultez Accéder à l’API Azure Media Services.

  2. Le jeton d’accès Azure AD est envoyé au niveau intermédiaire.

  3. Le niveau intermédiaire envoie une requête à l’API REST Azure Media avec le jeton Azure AD.

  4. Le niveau intermédiaire récupère les données de Media Services.

Exemples

Les exemples suivants montrent comment se connecter à un principal de service Azure AD :

Conventions d’affectation de noms

Les noms de ressources Azure Media Services v3 (par exemple Assets, Jobs, Transforms) sont sujets à des restrictions d’appellation par Azure Resource Manager. Conformément à Azure Resource Manager, les noms des ressources sont toujours uniques. Ainsi, vous pouvez utiliser n’importe quelle chaîne d’identificateur unique (par exemple des GUID) pour les noms de vos ressources.

Les noms de ressources Media Services ne peuvent pas inclure : '<', '>', '%', '&', ' :', '\', ' ?', '/', '*', '+', '.', le caractère de guillemet unique ou tout caractère de contrôle. Tous les autres caractères sont autorisés. La longueur maximale d’un nom de ressources est de 260 caractères.

Pour en savoir plus sur l’affectation de noms avec Azure Resource Manager, consultez : Exigences d’affectation des noms et Convention d’affectation de noms.

Noms des fichiers/objets blob dans une ressource

Les noms des fichiers/objets blob au sein d’une ressource doivent respecter les exigences en matière de nom d’objet blob et de nom NTFS. Ces exigences se justifient par le fait que les fichiers peuvent être copiés du stockage d’objets blob vers un disque NTFS local à des fins de traitement.

Opérations de longue durée

Les opérations marquées par x-ms-long-running-operation dans les fichiers swagger Azure Media Services exécutent des opérations de longue durée.

Pour plus d’informations sur le suivi des opérations asynchrones Azure, consultez Opérations asynchrones.

Media Services propose les opérations de longue durée suivantes :

En cas de soumission réussie d’une longue opération, vous recevez un message « 201 créé » et devez interroger la fin de l’opération à l’aide de l’ID d’opération retourné.

L’article Suivre les opérations asynchrones Azure explique en détail comment suivre l’état des opérations asynchrones Azure à l’aide des valeurs retournées dans la réponse.

Une seule opération de longue durée est prise en charge pour un événement en direct donné ou l’une de ses sorties en temps réel associées. Une fois démarrée, une opération de longue durée doit se terminer avant de commencer une opération de longue durée ultérieure sur le même LiveEvent ou sur les sorties en temps réel associées. Pour les événements en direct avec plusieurs sorties en temps réel, vous devez attendre la fin de l’exécution d’une opération de longue durée sur une sortie en temps réel avant de déclencher une opération de longue durée sur une autre sortie en temps réel.

Kits SDK

Notes

Les kits SDK Azure Media Services v3 ne sont pas garantis thread-safe. Lorsque vous développez une application multithread, vous devez ajouter votre propre logique de synchronisation de thread pour protéger le client, ou utiliser un objet AzureMediaServicesClient différent pour chaque thread. Vous devez également faire attention aux problèmes liés au multithreading provoqués par les objets facultatifs qui sont fournis au client par votre code (comme une instance HttpClient dans .NET, par exemple).

Kit SDK Informations de référence
Kit de développement logiciel (SDK) .NET Ref de .NET
Kit SDK Java Ref de Java
Kit de développement logiciel (SDK) Python Ref de Python
Kit de développement logiciel (SDK) Node.js Ref de Node.js
Kit de développement logiciel (SDK) Go Ref de Go

Voir aussi

Azure Media Services Explorer

Azure Media Services Explorer (AMSE) est un outil disponible pour les clients Windows qui souhaitent en savoir plus sur Media Services. AMSE est une application Winforms/C# qui charge, télécharge, encode, diffuse en continu du contenu VOD et en direct avec Media Services. L’outil AMSE est destiné aux clients qui souhaitent tester Media Services sans écrire de code. Le code AMSE est fourni en tant que ressource pour les clients qui souhaitent développer avec Media Services.

AMSE est un projet open source, son support est assuré par la Communauté (les problèmes peuvent être signalés sur https://github.com/Azure/Azure-Media-Services-Explorer/issues). Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Filtrage, classement et pagination d’entités Media Services

Consultez Filtrage, tri et pagination des entités Azure Media Services.

Obtenir de l’aide et du support

Vous pouvez contacter Media Services pour vous poser des questions ou suivre nos mises à jour en suivant l’une des méthodes suivantes :