Entwickeln mit Media Services v3-APIs

  • Artikel

Media Services-Logo v3

Warnung

Azure Media Services wird am 30. Juni 2024 eingestellt. Weitere Informationen finden Sie im Leitfaden zur Einstellung von AMS.

Als Entwickler können Sie Clientbibliotheken (.NET, Python, Node.js, Java und Go) verwenden, die Ihnen ermöglichen, mit der REST-API auf einfache Weise zu interagieren, um benutzerdefinierte Medienworkflows zu erstellen, zu verwalten und zu pflegen. Die Media Services v3-API basiert auf der OpenAPI-Spezifikation (ehemals Swagger).

In diesem Artikel werden Regeln erläutert, die für Entitäten und APIs gelten, wenn Sie mit Media Services v3 entwickeln.

Warnung

Es wird nicht empfohlen, die REST-API für Media Services direkt in Ihren eigenen Bibliothekscode einzuschließen, da Sie dazu für Produktionszwecke die vollständige Wiederholungslogik der Azure-Ressourcenverwaltung implementieren und verstehen müssten, wie Vorgänge mit langer Ausführungsdauer in APIs für die Azure-Ressourcenverwaltung verwaltet werden. Dies wird von den Client-SDKs für verschiedene Sprachen (.NET, Java, TypeScript, Python usw.) automatisch erledigt und verringert die Wahrscheinlichkeit, dass Probleme mit der Wiederholungslogik oder mit fehlgeschlagenen API-Aufrufen auftreten. Die Client-SDKs erledigen dies bereits für Sie.

Zugreifen auf die Azure Media Services-API

Sie müssen zuerst authentifiziert werden, um berechtigt zu sein, auf Media Services-Ressourcen und die Media Services-API zuzugreifen. Für Media Services wird die Azure Active Directory-basierte Authentifizierung unterstützt. Zwei häufige Authentifizierungsoptionen sind:

  • Dienstprinzipalauthentifizierung: Wird zur Authentifizierung eines Dienstes verwendet (z. B. Web-Apps, Funktions-Apps, Logik-Apps, API und Microservices). Bei Anwendungen, die diese Authentifizierungsmethode normalerweise nutzen, handelt es sich um Apps, mit denen Daemondienste, Dienste der mittleren Ebene oder geplante Aufträge ausgeführt werden. Beispielsweise sollte es für Web-Apps immer einen Dienst der mittleren Ebene geben, der sich mit einem Dienstprinzipal mit Media Services verbindet.
  • Benutzerauthentifizierung: Dient zum Authentifizieren einer Person, die die App für die Interaktion mit Media Services-Ressourcen verwendet. Die interaktive App sollte den Benutzer zuerst zur Eingabe seiner Anmeldeinformationen auffordern. Ein Beispiel hierfür ist eine Verwaltungskonsolen-App, die von autorisierten Benutzern zum Überwachen von Codierungsaufträgen oder Livestreaming verwendet wird.

Die Media Services-API erfordert, dass der Benutzer oder die App, die die REST-API-Anforderungen sendet, Zugriff auf die Media Services-Kontoressource hat und eine Rolle Mitwirkender oder Besitzer verwendet. Auf die API kann mit der Rolle Leser zugegriffen werden, es sind aber nur Vorgänge vom Typ Get und List verfügbar. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) für Media Services-Konten.

Anstatt ein Dienstprinzipal zu erstellen, sollten Sie die Verwendung verwalteter Identitäten für Azure-Ressourcen in Betracht ziehen, um über den Azure Resource Manager auf die Media Services-API zuzugreifen. Weitere Informationen zu verwalteten Identitäten für Azure-Ressourcen finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?.

Azure AD-Dienstprinzipal

Die Azure AD-App und der Dienstprinzipal sollten sich im selben Mandanten befinden. Nachdem Sie die App erstellt haben, können Sie für die App den Zugriff auf das Media Services-Konto über die Rolle Mitwirkender oder Besitzer gewähren.

Wenn Sie sich nicht sicher sind, ob Sie über Berechtigungen zum Erstellen einer Azure AD-App verfügen, lesen Sie Erforderliche Berechtigungen.

In der folgenden Abbildung stellen die Zahlen den Fluss der Anforderungen in chronologischer Reihenfolge dar:

Authentifizierung von Apps der mittleren Ebene mit AAD über eine Web-API

  1. Eine App der mittleren Ebene fordert ein Azure AD-Zugriffstoken an, das die folgenden Parameter enthält:

    • Azure AD-Mandantenendpunkt.
    • Media Services-Ressourcen-URI.
    • Ressourcen-URI für REST Media Services
    • Werte der Azure AD-App: Client-ID und Clientgeheimnis

    Informationen zum Abrufen aller erforderlichen Werte finden Sie in Zugriff auf Azure Media Services API.

  2. Das Azure AD-Zugriffstoken wird an die mittlere Ebene gesendet.

  3. Die mittlere Ebene sendet eine Anforderung mit dem Azure AD-Token an die Azure Media-REST-API.

  4. Die mittlere Ebene erhält die Daten von den Media Services zurück.

Beispiele

Sehen Sie sich die folgenden Beispiele an, die zeigen, wie Sie sich mit dem Azure AD-Dienstprinzipal verbinden können:

Benennungskonventionen

Azure Media Services-v3-Ressourcennamen (beispielsweise Objekte, Aufträge und Transformationen) unterliegen den Namenseinschränkungen von Azure Resource Manager. Ressourcennamen sind gemäß den Vorgaben von Azure Resource Manager immer eindeutig. Daher können Sie beliebige Zeichenfolgen für eindeutige Bezeichner (beispielsweise GUIDs) als Ressourcennamen verwenden.

Media Services-Ressourcennamen dürfen nicht enthalten: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', das einfache Anführungszeichen oder andere Steuerzeichen. Alle anderen Zeichen sind zulässig. Ein Ressourcenname darf maximal 260 Zeichen lang sein.

Weitere Informationen zu Azure Resource Manager-Benennungen finden Sie in den Benennungsanforderungen und in den Benennungskonventionen.

Namen von Dateien/Blobs in einer Ressource

Die Namen von Dateien/Blobs innerhalb einer Ressource müssen die Anforderungen an Blobnamen und die Anforderungen an NTFS-Namen erfüllen. Diese Anforderungen bestehen, da die Dateien zur Verarbeitung aus Blob Storage auf einen lokalen NTFS-Datenträger kopiert werden können.

Zeitintensive Vorgänge

Die in den swagger-Dateien von Azure Media Services mit x-ms-long-running-operation gekennzeichneten Vorgänge sind zeitintensive Vorgänge.

Weitere Informationen zum Verfolgen asynchroner Azure-Vorgänge finden Sie unter Asynchrone Vorgänge.

Media Services verfügt über die folgenden zeitintensiven Vorgänge:

Nach erfolgreicher Übermittlung eines zeitintensiven Vorgangs erhalten Sie eine Bestätigung vom Typ „201 – Erstellt“ und müssen anhand der zurückgegebenen Vorgangs-ID abfragen, ob der Vorgang abgeschlossen ist.

Der Artikel Nachverfolgen asynchroner Vorgänge in Azure enthält ausführliche Informationen zur Nachverfolgung des Status asynchroner Azure-Vorgänge anhand von Werten aus der zurückgegebenen Antwort.

Für jedes Liveereignis bzw. für jede zugehörige Liveausgabe wird jeweils nur ein einzelner zeitintensiver Vorgang unterstützt. Wurde ein zeitintensiver Vorgang gestartet, muss er erst abgeschlossen werden, bevor der nächste zeitintensive Vorgang für das gleiche Liveereignis oder für eine der zugehörigen Liveausgaben gestartet wird. Bei Liveereignissen mit mehreren Liveausgaben müssen Sie warten, bis ein zeitintensiver Vorgang für eine Liveausgabe abgeschlossen wurde, bevor Sie einen zeitintensiven Vorgang für eine weitere Liveausgabe auslösen.

SDKs

Hinweis

Für die Azure Media Services v3 SDKs wird keine Threadsicherheit garantiert. Wenn Sie eine Multithread-App entwickeln, sollten Sie zum Schutz des Clients Ihre eigene Threadsynchronisierungslogik hinzufügen oder für jeden Thread ein neues AzureMediaServicesClient-Objekt verwenden. Achten Sie außerdem auf Multithreadingprobleme, die durch optionale Objekte entstehen können, die von Ihrem Code für den Client bereitgestellt werden (beispielsweise eine HttpClient-Instanz in .NET).

SDK Verweis
.NET SDK .NET-Referenz
Java SDK Java-Referenz
Python SDK Python-Referenz
Node.js SDK Node.js-Referenz
Go SDK Go-Referenz

Weitere Informationen

Azure Media Services Explorer

Azure Media Services Explorer (AMSE) ist ein Tool für Windows-Kunden, die sich über Media Services informieren möchten. Bei AMSE handelt es sich um eine WinForms-/C#-Anwendung zum Hochladen, Herunterladen, Codieren und Streamen von VoD- und Liveinhalten mit Media Services. Das AMSE-Tool richtet sich an Kunden, die Media Services ohne Programmieraufwand testen möchten. Der AMSE-Code wird als Ressource für Kunden bereitgestellt, die mit Media Services entwickeln möchten.

AMSE ist ein Open-Source-Projekt mit communitybasiertem Support. Probleme können hier gemeldet werden: https://github.com/Azure/Azure-Media-Services-Explorer/issues. Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Filterung, Sortierung und Paginierung von Media Services-Entitäten

Informationen finden Sie unter Filterung, Sortierung, Paginierung von Azure Media Services-Entitäten.

Anfordern von Hilfe und Support

Sie können Media Services mit Fragen kontaktieren oder unsere Updates mit einer der folgenden Methoden verfolgen: