Export (0) Print
Expand All

Delivering Assets with the Media Services REST API

Updated: February 13, 2014

Microsoft Azure Media Services provides multiple mechanisms for you to deliver content to clients. You can allow them to download the content from a blob storage account, or stream it from Media Services.

The following sections describe how to deliver content to clients:

For more information and concepts and terminology related to delivering media content, see Delivering Content.

ImportantImportant
When working with the Media Services REST API, the following considerations apply:

ImportantImportant
When working with locators the following considerations apply:

  • There may be a 30-40 second delay after a Locator is created to when it is available for use. This issue applies to both SAS URL and Origin Locators.

  • You cannot have more than five unique Locators associated with a given Asset at one time. For more information, see Locator.

  • Media Services uses the value of the IAssetFile.Name property when building URLs for the streaming content (for example, http://{WAMSAccount}.origin.mediaservices.windows.net/{GUID}/{IAssetFile.Name}/streamingParameters.) For this reason, percent-encoding is not allowed. The value of the Name property cannot have any of the following percent-encoding-reserved characters: !*'();:@&=+$,/?%#[]". Also, there can only be one ‘.’ for the file name extension.

Creating the AccessPolicy with read permission

Before downloading or streaming any media content, first define an AccessPolicy with read permissions and create the appropriate Locator entity that specifies the type of delivery mechanism you want to enable for your clients. For more information on the properties available, see AccessPolicy Entity Properties.

The following example shows how to specify the AccessPolicy for read permissions for a given Asset.

POST https://media.windows.net/API/AccessPolicies HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.5
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337067658&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=dithjGvlXR9HlyAf5DE99N5OCYkPAxsHIcsTSjm9%2fVE%3d
Host: media.windows.net
Content-Length: 74
Expect: 100-continue

{"Name": "DownloadPolicy", "DurationInMinutes" : "300", "Permissions" : 1}

If successful, a 201 success code is returned describing the AccessPolicy entity that you created. You will then use the AccessPolicy Id along with the Asset Id of the asset that contains the file you want to deliver(such as an output asset) to create the Locator entity.

noteNote
This basic workflow is the same as uploading a file when ingesting an Asset. For more information on uploading a file, see Upload a file to blob storage. Also, like uploading files, if you (or your clients) need to access your files immediately, set your StartTime value to five minutes before the current time. This action is necessary because there may be clock skew between the client and Media Services. The StartTime value must be in the following DateTime format: YYYY-MM-DDTHH:mm:ssZ (for example, "2014-05-23T17:53:50Z").

Creating a SAS URL for downloading content

The following code shows how to download a media file created and uploaded previously. The AccessPolicy has read permissions set and the Locator path refers to a SAS download URL.

POST https://media.windows.net/API/Locators HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.5
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337067658&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=dithjGvlXR9HlyAf5DE99N5OCYkPAxsHIcsTSjm9%2fVE%3d
Host: media.windows.net
Content-Length: 182
Expect: 100-continue

{"AccessPolicyId": "nb:pid:UUID:38c71dd0-44c5-4c5f-8418-08bb6fbf7bf8", "AssetId" : "nb:cid:UUID:eb5540a2-116e-4d36-b084-7e9958f7f3c3", "StartTime" : "2014-05-17T16:45:53", "Type":1}

If successful, the following response is returned:

HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 1150
Content-Type: application/json;odata=verbose;charset=utf-8
Location: https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A8e5a821d-2194-4d00-8884-adf979856874')
Server: Microsoft-IIS/7.5
x-ms-request-id: 8cfd8556-3064-416a-97f2-67d9e35f0911
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 14 May 2012 21:41:32 GMT

{"d":{"__metadata":{"id":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A8e5a821d-2194-4d00-8884-adf979856874')","uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A8e5a821d-2194-4d00-8884-adf979856874')","type":"Microsoft.Cloud.Media.Vod.Rest.Data.Models.Locator"},"AccessPolicy":{"__deferred":{"uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A8e5a821d-2194-4d00-8884-adf979856874')/AccessPolicy"}},"Asset":{"__deferred":{"uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A8e5a821d-2194-4d00-8884-adf979856874')/Asset"}},"Id":"nb:lid:UUID:8e5a821d-2194-4d00-8884-adf979856874","ExpirationDateTime":"\/Date(1337049393000)\/","Type":1,"Path":"https://yourstorageaccount.blob.core.windows.net/asset-3df042ec-a396-4c62-a217-16c7a2569640?st=2012-05-14T21%3A36%3A33Z&se=2012-05-15T02%3A36%3A33Z&sr=c&si=8e5a821d-2194-4d00-8884-adf979856874&sig=y75dViDpC5V8WutrXM%2B%2FGpR3uOtqmlISiNlHU1YUBOg%3D","AccessPolicyId":"nb:pid:UUID:38c71dd0-44c5-4c5f-8418-08bb6fbf7bf8","AssetId":"nb:cid:UUID:eb5540a2-116e-4d36-b084-7e9958f7f3c3","StartTime":"\/Date(1337031393000)\/"}}

The Path property references the SAS URL for the Asset Id you specified in your request. To download the file, add the filename of the content that you want to download in the SAS URL before downloading.

The following example shows how to download the file from blob storage using a web browser:

GET https://yourstorageaccount.blob.core.windows.net/asset-3df042ec-a396-4c62-a217-16c7a2569640/samplevid.wmv?st=2012-05-14T21%3A36%3A33Z&se=2012-05-15T02%3A36%3A33Z&sr=c&si=8e5a821d-2194-4d00-8884-adf979856874&sig=y75dViDpC5V8WutrXM%2B%2FGpR3uOtqmlISiNlHU1YUBOg%3D HTTP/1.1
Accept: text/html, application/xhtml+xml, */*
Accept-Language: en-US
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)
Accept-Encoding: gzip, deflate
Host: yourstorageaccount.blob.core.windows.net
Connection: Keep-Alive

If successful, the following response is returned:

HTTP/1.1 200 OK
Content-Length: 4045744
Content-Type: application/octet-stream
Last-Modified: Mon, 14 May 2012 21:41:26 GMT
ETag: 0x8CF00317343F6D8
Server: Blob Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: da01ef74-7bf6-4837-b36d-8a6c08a26c3f
Date: Mon, 14 May 2012 22:02:45 GMT

??v?3?????>1?p????m.?v9?/??s?a?(C?D?
wsh?1hfN??C?V??,?-?sd??:?j?dCfT?,?6????8?f?p??o??"?????6C??q?????KbP???w*????i
[Remaining data truncated for readability.]
ImportantImportant
If you download storage encrypted content, you must manually decrypt it before rendering it, or use the Storage Decryption MediaProcessor in a processing task to output processed files in the clear to an OutputAsset and then download from that Asset. For more information on processing, see Creating an Encoding Job with the Media Services REST API. Also, SAS URL Locators cannot be updated after they have been created. For example, you cannot reuse the same Locator with an updated StartTime value. This is because of the way SAS URLs are created. If you want to access an asset for download after a Locator has expired, then you must create a new one with a new StartTime.

Creating an origin URL for streaming content

The only differences when creating an origin URL Locator versus a SAS URL Locator are the "Type" value and the content that you want to stream must be converted from MP4 to Smooth Streaming format (.ism*). The latter can be done through the use of the MP4 to Smooth Streaming MediaProcessor in a processing Task. For streaming to iOS devices, you also need to add a processing task that then uses the Smooth Streaming to HLS MediaProcessor to create an output Asset that contains the files necessary to stream to those devices. For an example on task chaining, see Create a Job. And unlike SAS URL Locators, origin Locators can be updated with new StartTime values after the Locator has been created. For more information on Locators and how to update them, see Locator.

The following code shows how to create an origin URL Locator:

POST https://media.windows.net/API/Locators HTTP/1.1
Content-Type: application/json;odata=verbose
Accept: application/json;odata=verbose
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
x-ms-version: 2.5
Authorization: Bearer http%3a%2f%2fschemas.xmlsoap.org%2fws%2f2005%2f05%2fidentity%2fclaims%2fnameidentifier=youraccountname&urn%3aSubscriptionId=2f84471d-b1ae-4e75-aa09-010f0fc0cf5b&http%3a%2f%2fschemas.microsoft.com%2faccesscontrolservice%2f2010%2f07%2fclaims%2fidentityprovider=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&Audience=urn%3aWindowsAzureMediaServices&ExpiresOn=1337067658&Issuer=https%3a%2f%2fwamsprodglobal001acs.accesscontrol.windows.net%2f&HMACSHA256=dithjGvlXR9HlyAf5DE99N5OCYkPAxsHIcsTSjm9%2fVE%3d
Host: media.windows.net
Content-Length: 182
Expect: 100-continue

{"AccessPolicyId": "nb:pid:UUID:38c71dd0-44c5-4c5f-8418-08bb6fbf7bf8", "AssetId" : "nb:cid:UUID:eb5540a2-116e-4d36-b084-7e9958f7f3c3", "StartTime" : "2014-05-17T16:45:53",, "Type":2}

If successful, the following response is returned:

HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 981
Content-Type: application/json;odata=verbose;charset=utf-8
Location: https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A52034bf6-dfae-4d83-aad3-3bd87dcb1a5d')
Server: Microsoft-IIS/7.5
x-ms-request-id: 2eac4158-fc78-4fa2-81ee-c9f582dc385f
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 14 May 2012 21:41:39 GMT

{"d":{"__metadata":{"id":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A52034bf6-dfae-4d83-aad3-3bd87dcb1a5d')","uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A52034bf6-dfae-4d83-aad3-3bd87dcb1a5d')","type":"Microsoft.Cloud.Media.Vod.Rest.Data.Models.Locator"},"AccessPolicy":{"__deferred":{"uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A52034bf6-dfae-4d83-aad3-3bd87dcb1a5d')/AccessPolicy"}},"Asset":{"__deferred":{"uri":"https://media.windows.net/api/Locators('nb%3Alid%3AUUID%3A52034bf6-dfae-4d83-aad3-3bd87dcb1a5d')/Asset"}},"Id":"nb:lid:UUID:52034bf6-dfae-4d83-aad3-3bd87dcb1a5d","ExpirationDateTime":"\/Date(1337049395000)\/","Type":2,"Path":"http://media.windows.net/52034bf6-dfae-4d83-aad3-3bd87dcb1a5d/","AccessPolicyId":"nb:pid:UUID:38c71dd0-44c5-4c5f-8418-08bb6fbf7bf8","AssetId":"nb:cid:UUID:eb5540a2-116e-4d36-b084-7e9958f7f3c3","StartTime":"\/Date(1337031395000)\/"}}

To reference a Smooth Streaming origin URL in a streaming media player, you must append the Path property with the name of the Smooth Streaming manifest file, followed by "/manifest". For example, using the origin URL shown in the previous example, the actual URL used by smooth streaming clients would be http://media.windows.net/52034bf6-dfae-4d83-aad3-3bd87dcb1a5d/samplevid.ism/manifest. And for HLS clients, the example would be http://media.windows.net/52034bf6-dfae-4d83-aad3-3bd87dcb1a5d/samplevid.isml/manifest(format=m3u8-aapl).

noteNote
In this section, the http://media.windows.net URI is used in the Path value as an example. The actual value depends on the Media Services deployment you are connected to.

See Also


Build Date:

2014-07-11

Community Additions

ADD
Show:
© 2014 Microsoft