|
| 1 | +--- |
| 2 | +title: Migrate from Azure Media Services v2 to v3 |
| 3 | +description: This article describes changes that were introduced in Azure Media Services v3 and shows differences between two versions. |
| 4 | +services: media-services |
| 5 | +documentationcenter: na |
| 6 | +author: Juliako |
| 7 | +manager: femila |
| 8 | +editor: '' |
| 9 | +tags: '' |
| 10 | +keywords: azure media services, stream, broadcast, live, offline |
| 11 | + |
| 12 | +ms.service: media-services |
| 13 | +ms.devlang: multiple |
| 14 | +ms.topic: article |
| 15 | +ms.tgt_pltfrm: multiple |
| 16 | +ms.workload: media |
| 17 | +ms.date: 03/09/2020 |
| 18 | +ms.author: juliako |
| 19 | +--- |
| 20 | + |
| 21 | +# Media Services v2 vs. v3 |
| 22 | + |
| 23 | +>Get notified about when to revisit this page for updates by copying and pasting this URL: `https://docs.microsoft.com/api/search/rss?search=%22Migrate+from+Azure+Media+Services+v2+to+v3%22&locale=en-us` into your RSS feed reader. |
| 24 | +
|
| 25 | +This article describes changes that were introduced in Azure Media Services v3 and shows differences between two versions. |
| 26 | + |
| 27 | +## General changes from v2 |
| 28 | + |
| 29 | +* For assets created with v3, Media Services supports only the [Azure Storage server-side storage encryption](https://docs.microsoft.com/azure/storage/common/storage-service-encryption). |
| 30 | + * You can use v3 APIs with Assets created with v2 APIs that had [storage encryption](../previous/media-services-rest-storage-encryption.md) (AES 256) provided by Media Services. |
| 31 | + * You cannot create new Assets with the legacy AES 256 [storage encryption](../previous/media-services-rest-storage-encryption.md) using v3 APIs. |
| 32 | +* The [Asset](assets-concept.md)'s properties in v3 differ to from v2, see [how the properties map](assets-concept.md#map-v3-asset-properties-to-v2). |
| 33 | +* The v3 SDKs are now decoupled from the Storage SDK, which gives you more control over the version of Storage SDK you want to use and avoids versioning issues. |
| 34 | +* In the v3 APIs, all of the encoding bit rates are in bits per second. This is different than the v2 Media Encoder Standard presets. For example, the bitrate in v2 would be specified as 128 (kbps), but in v3 it would be 128000 (bits/second). |
| 35 | +* Entities AssetFiles, AccessPolicies, and IngestManifests do not exist in v3. |
| 36 | +* The IAsset.ParentAssets property does not exist in v3. |
| 37 | +* ContentKeys is no longer an entity, it is now a property of the Streaming Locator. |
| 38 | +* Event Grid support replaces NotificationEndpoints. |
| 39 | +* The following entities were renamed |
| 40 | + * Job Output replaces Task, and is now part of a Job. |
| 41 | + * Streaming Locator replaces Locator. |
| 42 | + * Live Event replaces Channel.<br/>Live Events billing is based on Live Channel meters. For more information, see [billing](live-event-states-billing.md) and [pricing](https://azure.microsoft.com/pricing/details/media-services/). |
| 43 | + * Live Output replaces Program. |
| 44 | +* Live Outputs start on creation and stop when deleted. Programs worked differently in the v2 APIs, they had to be started after creation. |
| 45 | +* To get information about a job, you need to know the Transform name under which the job was created. |
| 46 | +* In v2, XML [input](../previous/media-services-input-metadata-schema.md) and [output](../previous/media-services-output-metadata-schema.md) metadata files get generated as the result of an encoding job. In v3, the metadata format changed from XML to JSON. |
| 47 | +* In Media Services v2, initialization vector (IV) can be specified. In Media Services v3, the FairPlay IV cannot be specified. While it does not impact customers using Media Services for both packaging and license delivery, it can be an issue when using a third party DRM system to deliver the FairPlay licenses (hybrid mode). In that case, it is important to know that the FairPlay IV is derived from the cbcs key ID and can be retrieved using this formula: |
| 48 | + |
| 49 | + ``` |
| 50 | + string cbcsIV = Convert.ToBase64String(HexStringToByteArray(cbcsGuid.ToString().Replace("-", string.Empty))); |
| 51 | + ``` |
| 52 | +
|
| 53 | + with |
| 54 | +
|
| 55 | + ``` |
| 56 | + public static byte[] HexStringToByteArray(string hex) |
| 57 | + { |
| 58 | + return Enumerable.Range(0, hex.Length) |
| 59 | + .Where(x => x % 2 == 0) |
| 60 | + .Select(x => Convert.ToByte(hex.Substring(x, 2), 16)) |
| 61 | + .ToArray(); |
| 62 | + } |
| 63 | + ``` |
| 64 | +
|
| 65 | + For more information, see the [Azure Functions C# code for Media Services v3 in hybrid mode for both Live and VOD operations](https://github.com/Azure-Samples/media-services-v3-dotnet-core-functions-integration/tree/master/LiveAndVodDRMOperationsV3). |
| 66 | + |
| 67 | +> [!NOTE] |
| 68 | +> Review the naming conventions that are applied to [Media Services v3 resources](media-services-apis-overview.md#naming-conventions). Also review [naming blobs](assets-concept.md#naming). |
| 69 | +
|
| 70 | +## Feature gaps with respect to v2 APIs |
| 71 | +
|
| 72 | +The v3 API has the following feature gaps with respect to the v2 API. Closing the gaps is work in progress. |
| 73 | +
|
| 74 | +* The [Premium Encoder](../previous/media-services-premium-workflow-encoder-formats.md) and the legacy [media analytics processors](../previous/media-services-analytics-overview.md) (Azure Media Services Indexer 2 Preview, Face Redactor, etc.) are not accessible via v3.<br/>Customers who wish to migrate from the Media Indexer 1 or 2 preview can immediately use the AudioAnalyzer preset in the v3 API. This new preset contains more features than the older Media Indexer 1 or 2. |
| 75 | +* Many of the [advanced features of the Media Encoder Standard in v2](../previous/media-services-advanced-encoding-with-mes.md) APIs are currently not available in v3, such as: |
| 76 | + |
| 77 | + * Stitching of Assets |
| 78 | + * Overlays |
| 79 | + * Cropping |
| 80 | + * Thumbnail Sprites |
| 81 | + * Inserting a silent audio track when input has no audio |
| 82 | + * Inserting a video track when input has no video |
| 83 | +* Live Events with transcoding currently do not support Slate insertion mid-stream and ad marker insertion via API call. |
| 84 | +
|
| 85 | +> [!NOTE] |
| 86 | +> Please bookmark this article and keep checking for updates. |
| 87 | + |
| 88 | +## Code differences |
| 89 | +
|
| 90 | +The following table shows the code differences between v2 and v3 for common scenarios. |
| 91 | +
|
| 92 | +|Scenario|V2 API|V3 API| |
| 93 | +|---|---|---| |
| 94 | +|Create an asset and upload a file |[v2 .NET example](https://github.com/Azure-Samples/media-services-dotnet-dynamic-encryption-with-aes/blob/master/DynamicEncryptionWithAES/DynamicEncryptionWithAES/Program.cs#L113)|[v3 .NET example](https://github.com/Azure-Samples/media-services-v3-dotnet-tutorials/blob/master/AMSV3Tutorials/UploadEncodeAndStreamFiles/Program.cs#L169)| |
| 95 | +|Submit a job|[v2 .NET example](https://github.com/Azure-Samples/media-services-dotnet-dynamic-encryption-with-aes/blob/master/DynamicEncryptionWithAES/DynamicEncryptionWithAES/Program.cs#L146)|[v3 .NET example](https://github.com/Azure-Samples/media-services-v3-dotnet-tutorials/blob/master/AMSV3Tutorials/UploadEncodeAndStreamFiles/Program.cs#L298)<br/><br/>Shows how to first create a Transform and then submit a Job.| |
| 96 | +|Publish an asset with AES encryption |1. Create ContentKeyAuthorizationPolicyOption<br/>2. Create ContentKeyAuthorizationPolicy<br/>3. Create AssetDeliveryPolicy<br/>4. Create Asset and upload content OR Submit job and use output asset<br/>5. Associate AssetDeliveryPolicy with Asset<br/>6. Create ContentKey<br/>7. Attach ContentKey to Asset<br/>8. Create AccessPolicy<br/>9. Create Locator<br/><br/>[v2 .NET example](https://github.com/Azure-Samples/media-services-dotnet-dynamic-encryption-with-aes/blob/master/DynamicEncryptionWithAES/DynamicEncryptionWithAES/Program.cs#L64)|1. Create Content Key Policy<br/>2. Create Asset<br/>3. Upload content or use Asset as JobOutput<br/>4. Create Streaming Locator<br/><br/>[v3 .NET example](https://github.com/Azure-Samples/media-services-v3-dotnet-tutorials/blob/master/AMSV3Tutorials/EncryptWithAES/Program.cs#L105)| |
| 97 | +|Get job details and manage jobs |[Manage jobs with v2](../previous/media-services-dotnet-manage-entities.md#get-a-job-reference) |[Manage jobs with v3](https://github.com/Azure-Samples/media-services-v3-dotnet-tutorials/blob/master/AMSV3Tutorials/UploadEncodeAndStreamFiles/Program.cs#L546)| |
| 98 | +
|
| 99 | +## Asset specific changes |
| 100 | +
|
| 101 | +### Map v3 asset properties to v2 |
| 102 | +
|
| 103 | +The following table shows how the [Asset](https://docs.microsoft.com/rest/api/media/assets/createorupdate#asset)'s properties in v3 map to Asset's properties in v2. |
| 104 | +
|
| 105 | +|v3 properties|v2 properties| |
| 106 | +|---|---| |
| 107 | +|`id` - (unique) the full Azure Resource Manager path, see examples in [Asset](https://docs.microsoft.com/rest/api/media/assets/createorupdate)|| |
| 108 | +|`name` - (unique) see [Naming conventions](media-services-apis-overview.md#naming-conventions) || |
| 109 | +|`alternateId`|`AlternateId`| |
| 110 | +|`assetId`|`Id` - (unique) value starts with the `nb:cid:UUID:` prefix.| |
| 111 | +|`created`|`Created`| |
| 112 | +|`description`|`Name`| |
| 113 | +|`lastModified`|`LastModified`| |
| 114 | +|`storageAccountName`|`StorageAccountName`| |
| 115 | +|`storageEncryptionFormat`| `Options` (creation options)| |
| 116 | +|`type`|| |
| 117 | +
|
| 118 | +### Storage side encryption |
| 119 | +
|
| 120 | +To protect your Assets at rest, the assets should be encrypted by the storage side encryption. The following table shows how the storage side encryption works in Media Services: |
| 121 | +
|
| 122 | +|Encryption option|Description|Media Services v2|Media Services v3| |
| 123 | +|---|---|---|---| |
| 124 | +|Media Services Storage Encryption|AES-256 encryption, key managed by Media Services.|Supported<sup>(1)</sup>|Not supported<sup>(2)</sup>| |
| 125 | +|[Storage Service Encryption for Data at Rest](https://docs.microsoft.com/azure/storage/common/storage-service-encryption)|Server-side encryption offered by Azure Storage, key managed by Azure or by customer.|Supported|Supported| |
| 126 | +|[Storage Client-Side Encryption](https://docs.microsoft.com/azure/storage/common/storage-client-side-encryption)|Client-side encryption offered by Azure storage, key managed by customer in Key Vault.|Not supported|Not supported| |
| 127 | +
|
| 128 | +<sup>1</sup> While Media Services does support handling of content in the clear/without any form of encryption, doing so isn't recommended. |
| 129 | +
|
| 130 | +<sup>2</sup> In Media Services v3, storage encryption (AES-256 encryption) is only supported for backwards compatibility when your Assets were created with Media Services v2. Meaning v3 works with existing storage encrypted assets but won't allow creation of new ones. |
| 131 | +
|
| 132 | +## Ask questions, give feedback, get updates |
| 133 | +
|
| 134 | +Check out the [Azure Media Services community](media-services-community.md) article to see different ways you can ask questions, give feedback, and get updates about Media Services. |
| 135 | +
|
| 136 | +## Next steps |
| 137 | +
|
| 138 | +[Migration guidance for moving from Media Services v2 to v3](migrate-from-v2-to-v3.md) |
0 commit comments