Develop with Media Services v3 APIs

  • Article

Media Services logo v3

Warning

Azure Media Services will be retired June 30th, 2024. For more information, see the AMS Retirement Guide.

As a developer, you can use client libraries for (.NET, Python, Node.js, Java, and Go) that allow you to interact with the REST API to easily create, manage, and maintain custom media workflows. The Media Services v3 API is based on the OpenAPI specification (formerly known as a Swagger).

This article discusses rules that apply to entities and APIs when you develop with Media Services v3.

Warning

It is not advised to attempt to wrap the REST API for Media Services directly into your own library code, as doing so properly for production purposes would require you to implement the full Azure Resource Management retry logic and understand how to manage long running operations in Azure Resource Management APIs. This is handled by the client SDKs for various languages - .NET, Java, TypeScript, Python, etc. - automatically and reduces the chances of you having issues with retry logic or failed API calls. The client SDKs all handle this for you already.

Accessing the Azure Media Services API

To be authorized to access Media Services resources and the Media Services API, you must first be authenticated. Media Services supports Azure Active Directory (Azure AD)-based authentication. Two common authentication options are:

  • Service principal authentication: Used to authenticate a service (for example: web apps, function apps, logic apps, API, and microservices). Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs. For example, for web apps there should always be a mid-tier that connects to Media Services with a Service Principal.
  • User authentication: Used to authenticate a person who is using the app to interact with Media Services resources. The interactive app should first prompt the user for the user's credentials. An example is a management console app used by authorized users to monitor encoding jobs or live streaming.

The Media Services API requires that the user or app making the REST API requests have access to the Media Services account resource and use a Contributor or Owner role. The API can be accessed with the Reader role but only Get or List operations will be available. For more information, see Azure role-based access control (Azure RBAC) for Media Services accounts.

Instead of creating a service principal, consider using managed identities for Azure resources to access the Media Services API through Azure Resource Manager. To learn more about managed identities for Azure resources, see What is managed identities for Azure resources.

Azure AD service principal

The Azure AD app and service principal should be in the same tenant. After you create the app, give the app Contributor or Owner role access to the Media Services account.

If you're not sure whether you have permissions to create an Azure AD app, see Required permissions.

In the following figure, the numbers represent the flow of the requests in chronological order:

Middle-tier app authentication with AAD from a web API

  1. A middle-tier app requests an Azure AD access token that has the following parameters:

    • Azure AD tenant endpoint.
    • Media Services resource URI.
    • Resource URI for REST Media Services.
    • Azure AD app values: the client ID and client secret.

    To get all the needed values, see Access Azure Media Services API.

  2. The Azure AD access token is sent to the middle tier.

  3. The middle tier sends request to the Azure Media REST API with the Azure AD token.

  4. The middle tier gets back the data from Media Services.

Samples

See the following samples that show how to connect with Azure AD service principal:

Naming conventions

Azure Media Services v3 resource names (for example, Assets, Jobs, Transforms) are subject to Azure Resource Manager naming constraints. In accordance with Azure Resource Manager, the resource names are always unique. Thus, you can use any unique identifier strings (for example, GUIDs) for your resource names.

Media Services resource names can't include: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', the single quote character, or any control characters. All other characters are allowed. The max length of a resource name is 260 characters.

For more information about Azure Resource Manager naming, see Naming requirements and Naming conventions.

Names of files/blobs within an asset

The names of files/blobs within an asset must follow both the blob name requirements and the NTFS name requirements. The reason for these requirements is the files can get copied from blob storage to a local NTFS disk for processing.

Long-running operations

The operations marked with x-ms-long-running-operation in the Azure Media Services swagger files are long running operations.

For details about how to track asynchronous Azure operations, see Async operations.

Media Services has the following long-running operations:

On successful submission of a long operation, you receive a '201 Created' and must poll for operation completion using the returned operation ID.

The track asynchronous Azure operations article explains in depth how to track the status of asynchronous Azure operations through values returned in the response.

Only one long-running operation is supported for a given Live Event or any of its associated Live Outputs. Once started, a long running operation must complete before starting a subsequent long-running operation on the same LiveEvent or any associated Live Outputs. For Live Events with multiple Live Outputs, you must await the completion of a long running operation on one Live Output before triggering a long running operation on another Live Output.

SDKs

Note

The Azure Media Services v3 SDKs aren't guaranteed to be thread-safe. When developing a multi-threaded app, you should add your own thread synchronization logic to protect the client or use a new AzureMediaServicesClient object per thread. You should also be careful of multi-threading issues introduced by optional objects provided by your code to the client (like an HttpClient instance in .NET).

SDK Reference
.NET SDK .NET ref
Java SDK Java ref
Python SDK Python ref
Node.js SDK Node.js ref
Go SDK Go ref

See also

Azure Media Services Explorer

Azure Media Services Explorer (AMSE) is a tool available to Windows customers who want to learn about Media Services. AMSE is a Winforms/C# application that does upload, download, encode, stream VOD and live content with Media Services. The AMSE tool is for clients who want to test Media Services without writing any code. The AMSE code is provided as a resource for customers who want to develop with Media Services.

AMSE is an Open Source project, support is provided by the community (issues can be reported to https://github.com/Azure/Azure-Media-Services-Explorer/issues). This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any other questions or comments.

Filtering, ordering, paging of Media Services entities

See Filtering, ordering, paging of Azure Media Services entities.