Asset

  • Article

The Asset entity contains digital files (including video, audio, images, thumbnail collections, text tracks and closed caption files) and the metadata about these files. After the digital files are uploaded into an asset, they could be used in the Media Services encoding and streaming workflows.

When you encode an asset, an output asset is produced upon completion of the encoding job. Among the files mentioned above, the output asset contains XML metadata files that describe the input asset and output asset. For more information, see the Input Metadata and Output Metadata articles.

The following characteristics apply to an Asset in Media Services:

  • An Asset is a logical unit that represents a single audiovisual presentation.

  • An asset contains a collection of one to many media files.

  • The files of an asset are located in a single blob storage container.

Some examples of an Asset are: a full movie, TV show, specific edit; a clip from a movie, TV show, animation, camera ISO file, or event; a movie trailer or promotional video; an advertisement; an audio file, radio show, podcast, or sound file.

The following characteristics DO NOT apply to an Asset in Media Services:

  • Simply a storage container

  • A folder to organize and store multiple versions of the same presentation in

  • A folder for submitting batch processing of multiple audiovisual presentations to Azure Media Encoder

For example, you must not store a movie, its trailer, an advertisement, and an international edit version of the same movie in a single Asset.

This topic gives an overview of the Asset entity and also demonstrates how to execute various operations with the Media Services REST API.

Important

When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests.
For more information, see Setup for Media Services REST API Development and Connecting to Media Services with the Media Services REST API.

Asset Entity Properties

Property Type Description
Id

Read-only. Set by Media Services at creation time.		 String Unique identifier.
State

Read-only. Set by Media Services.		 Edm.Int32 An enumeration value that describes the state of the asset. Value values are:

- Initialized = 0
- Published = 1 Warning: The Publish action has been deprecated. Remove the code that checks whether an asset is in the Published state.
- Deleted = 2

An asset is always in Initialized state until it is deleted.
Created

Read-only. Set by Media Services at creation time.		 Edm.DateTime This value is set by Media Services at creation time.
LastModified

Read-only. Set by Media Services.		 Edm.DateTime This value is updated by Media Services after any property changes are made.
AlternateId

Optional.		 Edm.String An alternate Id value that corresponds to an Id in another content management system. Maximum length is 4000.
Name

Optional.		 Edm.String Friendly name for your asset. Maximum length is 512.
Options

Required. Cannot be updated after the entity has been created.		 Edm.Int32 An enumeration value that describes the encryption options that an Asset can be created with. A valid value is one value from the list below, not a combination of values from this list:

- None = 0: Specifies no asset creation options.
- StorageEncrypted = 1: Specifies that an asset's files should be encrypted on for upload and storage when creating the asset.
- CommonEncryptionProtected = 2: Specifies that an asset’s files are protected using a common encryption method (such as PlayReady).
- EnvelopeEncryptionProtected = 4
Uri

Read-only. Set by Media Services.		 Edm.String The URI of the blob storage container of the specified Asset.
Locators

Read-only. Set by Media Services.		 Locator entity set The returned entity set contains all of the Locator entities that are linked to the specified Asset.
ContentKeys

Optional.		 ContentKey entity set The returned entity set contains all of the ContentKey entities that are linked to the specified Asset.
Files

Read-only. Set by Media Services.		 File entity set The returned entity set contains all of the File entities that are linked to the specified Asset.
ParentAssets

Optional.		 Parent Assets entity set The returned entity set contains all of the parent Asset entities that are linked to the specified Asset.
StorageAccountName

Optional. Cannot be updated after the entity has been created.		 Edm.String Name of the storage account that contains the asset’s blob container.

If not specified at creation time, Media Services sets the default storage account name.
StorageAccount

Read-only. Set by Media Services.		 StorageAccount entity set The returned entity set contains all of the StorageAccount entities that are linked to the specified Asset.
DeliveryPolicies AssetDeliveryPolicy entity set The returned entity set contains delivery policies associated with the asset.
FormatOption Edm.Int32 Specifies different format options that an asset can be created with. Allowed values are: 0 (default) - specifies no asset format option; 1 - specifies that an asset's format will be AdaptiveStreaming.

Create an Asset

Assets can be created using a POST HTTP request and specifying property values.

Method Request URI HTTP Version
POST https://<accountname>.restv2.<location>.media.azure.net/api/Assets HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

POST https://<accountname>.restv2.<location>.media.azure.net/api/Assets HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization:  Bearer <token value>  
Host: media.windows.net  
Content-Length: 27  
Expect: 100-continue  
  
{ "Name" : "NewJSONAsset" }

List an Asset

Assets can be retrieved using a GET HTTP request.

Method Request URI HTTP Version
GET https://<accountname>.restv2.<location>.media.azure.net/api/Assets HTTP/1.1
Method Request URI HTTP Version
GET https://<accountname>.restv2.<location>.media.azure.net/api/Assets('assetid') HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

GET https://<accountname>.restv2.<location>.media.azure.net/api/Assets('nb:cid:UUID:fccb8cd9-7afa-4365-a36e-d5d68409bb64') HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization: Bearer <token value>  
Host: media.windows.net  
Content-Length: 0

Update an Asset

Assets can be updated using a MERGE HTTP request and the specific properties that you want to change.

Method Request URI HTTP Version
MERGE https://<accountname>.restv2.<location>.media.azure.net/api/Assets('assetid') HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

MERGE https://<accountname>.restv2.<location>.media.azure.net/api/Assets('nb:cid:UUID:80782407-3f87-4e60-a43e-5e4454232f60') HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization: Bearer <token value>  
Host: media.windows.net  
Content-Length: 21  
Expect: 100-continue  
  
{"Name" : "NewName" }

Delete an Asset

Assets can be deleted by referencing the Asset Id value. When an asset is deleted, all of its locators are deleted by Microsoft Azure Media Services. If the asset had origin locators, these locators will be revoked and deleted as well. All links to ContentKeys will be deleted and any ContentKeys not linked to other assets will be deleted.

Method Request URI HTTP Version
DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Assets('assetid') HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Assets('nb:cid:UUID:fccb8cd9-7afa-4365-a36e-d5d68409bb64') HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization: Bearer <token value>  
Host: media.windows.net  
Content-Length: 0

Publish an Asset

Note

The Publish action has been deprecated. Starting with the latest Media Services release, Publish should not be used.

If your code uses Publish, be aware of the following considerations:

  1. The Publish action does not delete locators associated with the asset. You must explicitly delete the locators in code after calling Publish.
  2. The Publish action does not set the asset state to Published. Remove the code that checks whether an asset is in the Published state. Currently, an asset can only have the Initialized or Deleted state.

Linking Content Keys to Assets

You can link a ContentKey to an asset by referencing the asset Id with an HTTP POST request. The Uri of the ContentKey must be included in the body of the request. You can only link a ContentKey type that matches the type specified in the asset’s CreationOptions. For example, if the Asset has options set to StorageEncrypted(1), the ContentKey must be of the StorageEncryption(1) type.

Method Request URI HTTP Version
POST https://<accountname>.restv2.<location>.media.azure.net/api/Assets(‘Asset Id')/$links/ContentKeys HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

POST https://<accountname>.restv2.<location>.media.azure.net/api/Assets('nb:cid:UUID:3ac4c50a-09c1-4ea3-b39c-c336d97f5a13')/$links/ContentKeys HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization: Bearer <token value>  
Host: media.windows.net  
Content-Length: 121  
Expect: 100-continue  
  
{ "uri": "https://&lt;accountname&gt;.restv2.&lt;location&gt;.media.azure.net/api/ContentKeys('nb%3Akid%3AUUID%3A5db89211-c9d9-404b-a6bc-3e6b91c7a214')"}

You can remove ContentKey links from an asset by referencing the asset id and the ContentKey Id in an HTTP DELETE request. If the ContentKey is not linked to any other assets, it will be deleted.

Method Request URI HTTP Version
DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Assets(‘Asset Id')/$links/ContentKeys('ContentKey Id') HTTP/1.1

Sample Request

To get the latest x-ms-version:, see Media Services REST.

DELETE https://<accountname>.restv2.<location>.media.azure.net/api/Assets('nb:cid:UUID:3ac4c50a-09c1-4ea3-b39c-c336d97f5a13')/$links/ContentKeys('nb:kid:UUID:5db89211-c9d9-404b-a6bc-3e6b91c7a214') HTTP/1.1  
Content-Type: application/json;odata=verbose  
Accept: application/json;odata=verbose  
DataServiceVersion: 3.0  
MaxDataServiceVersion: 3.0  
x-ms-version: 2.19  
Authorization: Bearer <token value>  
Host: media.windows.net  
Content-Length: 0

See Also

AccessPolicy
ContentKey
AssetFile
Job
JobTemplate
Locator
MediaProcessor
Task
TaskTemplate
Ingesting Assets with the Media Services REST API
Quotas and Limitations