Step 3 - Set up to migrate to the V3 REST API or client SDK

Article
07/10/2023

migration steps 2

The following describes the steps to take to set up your environment to use the Media Services V3 API.

SDK model

In the V2 API, there were two different client SDKs, one for the management API, which allowed programmatic creation of accounts, and one for resource management.

Previously, developers would work with an Azure service principal client ID and client secret, along with a specific V2 REST API endpoint for their AMS account.

The V3 API is Azure Resource Management (ARM) based. It uses Azure Active Directory (Azure AD) service principal IDs and keys to connect to the API. Developers will need to create service principals or managed identities to connect to the API. In the V3 API, the API uses standard ARM endpoints, uses a similar and consistent model to all other Azure services.

Customers previously using the 2015-10-01 version of the ARM management API to manage their V2 accounts should use the 2020-05-01 (or later) version of the ARM management API supported for V3 API access.

Create a new media services account for testing

Find your tenant and subscription ids in the portal and create a Media Services account. Then, select API access and service principal authentication to generate a new Azure AD application ID and secrets for use with this test account.

Create a media services account. Get credentials to access Media Services API.

Download client SDK of your choice and set up your environment

SDKs available for .NET, .NET Core, Node.js, Python, Java, and Go.
Azure CLI integration for simple scripting support.

Note

A community PHP SDK is no longer available for Azure Media Services on V3. If you're using PHP on V2, you should migrate to the REST API directly in your code.

Open API specifications

V3 is based on a unified API surface, which exposes both management and operations functionality built on Azure Resource Manager. Azure Resource Manager templates can be used to create and deploy transforms, streaming endpoints, live events, and more.
The OpenAPI Specification (formerly called Swagger) document explains the schema for all service components.
All client SDKs are derived and generated from the Open API specification published on GitHub. At the time of publication of this article, the latest Open API specifications are maintained publicly in GitHub. The 2020-05-01 version is the latest stable release.

Read the REST API reference pages.

You should use the 2020-05-01 (or later) version.

Read the article, Connect to Media Services v3 API with .NET to set up your environment.

If you simply want to install the latest SDK using PackageManager, use the following command:

Install-Package Microsoft.Azure.Management.Media

Or to install the latest SDK using the .NET CLI use the following command:

dotnet add package Microsoft.Azure.Management.Media

Additionally, full .NET samples are available in Azure-Samples/media-services-v3-dotnet for various scenarios. The projects in this repository show how to implement different Azure Media Services scenarios using the v3 version.

Get started adjusting your code

Search your code base for instances of CloudMediaContext usage to begin the upgrade process to the V3 API.

The following code shows how the v2 API was previously accessed using the v2 .NET SDK. Developers would begin with creating a CloudMediaContext and create an instance with an AzureAdTokenCredentials object.


class Program
	{
	    // Read values from the App.config file.
        private static readonly string _AADTenantDomain =
            ConfigurationManager.AppSettings["AMSAADTenantDomain"];
        private static readonly string _RESTAPIEndpoint =
            ConfigurationManager.AppSettings["AMSRESTAPIEndpoint"];
        private static readonly string _AMSClientId =
            ConfigurationManager.AppSettings["AMSClientId"];
        private static readonly string _AMSClientSecret =
            ConfigurationManager.AppSettings["AMSClientSecret"];

	    private static CloudMediaContext _context = null;

	    static void Main(string[] args)
	    {
        try
        {
            AzureAdTokenCredentials tokenCredentials =
                new AzureAdTokenCredentials(_AADTenantDomain,
                    new AzureAdClientSymmetricKey(_AMSClientId, _AMSClientSecret),
                    AzureEnvironments.AzureChinaCloudEnvironment);

            var tokenProvider = new AzureAdTokenProvider(tokenCredentials);

            _context = new CloudMediaContext(new Uri(_RESTAPIEndpoint), tokenProvider);

Step 3 - Set up to migrate to the V3 REST API or client SDK

SDK model

Create a new media services account for testing

Download client SDK of your choice and set up your environment

Open API specifications

Additional resources