有关从媒体服务 v2 迁移到 v3 的指导Migration guidance for moving from Media Services v2 to v3

通过将此 URL (https://docs.microsoft.com/api/search/rss?search=%22Migrate+from+Azure+Media+Services+v2+to+v3%22&locale=en-us) 复制并粘贴到 RSS 源阅读器中获取有关何时重新访问此页以获得更新的通知。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.

本文介绍 Azure 媒体服务 v3 中引入的更改,说明两个版本之间的差异,并提供迁移指导。This article describes changes that were introduced in Azure Media Services v3, shows differences between two versions, and provides the migration guidance.

如果你目前基于旧版媒体服务 v2 API 开发了一个视频服务,则在迁移到 v3 API 之前,应查看以下指导原则和注意事项。If you have a video service developed today on top of the legacy Media Services v2 APIs, you should review the following guidelines and considerations prior to migrating to the v3 APIs. v3 API 中的许多优势和新功能可以改进开发体验和媒体服务的功能。There are many benefits and new features in the v3 API that improve the developer experience and capabilities of Media Services. 但是,如本文的已知问题部分中所述,API 版本的变化也带来了一些限制。However, as called out in the Known Issues section of this article, there are also some limitations due to changes between the API versions. 在媒体服务团队不断改进 v3 API 并解决版本差距的过程中,本页面会得到维护。This page will be maintained as the Media Services team makes continued improvements to the v3 APIs and addresses the gaps between the versions.


目前,无法使用 Azure 门户来管理 v3 资源。Currently, you cannot use the Azure portal to manage v3 resources. 请使用 REST APICLI 或受支持的 SDK 之一。Use the REST API, CLI, or one of the supported SDKs.

媒体服务 v3 的优势Benefits of Media Services v3

API 更便于访问API is more approachable

  • v3 基于一个统一的 API 接口,该接口公开了基于 Azure 资源管理器构建的管理和操作功能。v3 is based on a unified API surface, which exposes both management and operations functionality built on Azure Resource Manager. Azure 资源管理器模板可用于创建和部署转换、流式处理终结点、直播活动等等。Azure Resource Manager templates can be used to create and deploy Transforms, Streaming Endpoints, Live Events, and more.
  • OpenAPI 规范(以前称为 Swagger)文档。OpenAPI Specification (formerly called Swagger) document. 公开所有服务组件的架构,包括基于文件的编码。Exposes the schema for all service components, including file-based encoding.
  • 适用于 .NET、.NET Core、Node.jsPythonJavaGo 和 Ruby 的 SDK。SDKs available for .NET, .NET Core, Node.js, Python, Java, Go, and Ruby.
  • 简化脚本支持的 Azure CLI 集成。Azure CLI integration for simple scripting support.

新增功能New features

  • 对于基于文件的作业处理,可以使用 HTTP(S) URL 作为输入。For file-based Job processing, you can use a HTTP(S) URL as the input.
    无需事先在 Azure 中存储内容,无需创建资产。You do not need to have content already stored in Azure, nor do you need to create Assets.
  • 为基于文件的作业处理引入了转换的概念。Introduces the concept of Transforms for file-based Job processing. 使用转换可以生成可重用的配置、创建 Azure 资源管理器模板,并隔离多个客户或租户之间的处理设置。A Transform can be used to build reusable configurations, to create Azure Resource Manager Templates, and isolate processing settings between multiple customers or tenants.
  • 一个资产可以有多个流式处理定位符,其中每个流式处理定位符有不同的动态打包和动态加密设置。An Asset can have multiple Streaming Locators each with different Dynamic Packaging and Dynamic Encryption settings.
  • 内容保护支持多密钥功能。Content protection supports multi-key features.
  • 使用媒体服务将单比特率贡献源转码为具有多比特率的输出流时,可以流式传输最长 24 小时的直播活动。You can stream Live Events that are up to 24 hours long when using Media Services for transcoding a single bitrate contribution feed into an output stream that has multiple bitrates.
  • 直播活动支持新的低延迟实时传送视频流。New Low Latency live streaming support on Live Events. 有关详细信息,请参阅延迟For more information, see latency.
  • 直播活动预览版支持动态打包和动态加密。Live Event Preview supports Dynamic Packaging and Dynamic Encryption. 这样,用户便可以使用预览版中的内容保护以及 DASH 和 HLS 打包。This enables content protection on Preview as well as DASH and HLS packaging.
  • 与 v2 API 中的节目实体相比,实时输出更易于使用。Live Output is simpler to use than the Program entity in the v2 APIs.
  • 改进的 RTMP 支持(提高了稳定性并提供了更多的源编码器支持)。Improved RTMP support (increased stability and more source encoder support).
  • RTMPS 安全引入。RTMPS secure ingest.
    创建直播活动时,将获得 4 个引入 URL。When you create a Live Event, you get 4 ingest URLs. 这 4 个引入 URL 几乎是相同的,具有相同的流式处理令牌 (AppId),仅端口号部分不同。The 4 ingest URLs are almost identical, have the same streaming token (AppId), only the port number part is different. 其中两个 URL 是 RTMPS 的主要和备份 URL。Two of the URLs are primary and backup for RTMPS.
  • 可对实体使用基于角色的访问控制 (RBAC)。You have role-based access control (RBAC) over your entities.

自 v2 以来的更改Changes from v2

  • 对于通过 v3 创建的资产,媒体服务仅支持 Azure 存储服务器端存储加密For Assets created with v3, Media Services supports only the Azure Storage server-side storage encryption.
    • 对于通过 v2 API 创建的,并采用媒体服务提供的存储加密 (AES 256) 的资产,可以使用 v3 API。You can use v3 APIs with Assets created with v2 APIs that had storage encryption (AES 256) provided by Media Services.
    • 无法使用 v3 API 创建采用旧版 AES 256 存储加密的新资产。You cannot create new Assets with the legacy AES 256 storage encryption using v3 APIs.
  • v3 中资产的属性与 v2 不同,请参阅属性如何映射The Asset's properties in v3 differ to from v2, see how the properties map.
  • v3 SDK 现在已与存储 SDK 分离,可让你更精细地控制所要使用的存储 SDK 版本,并避免版本控制问题。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.
  • 在 v3 API 中,所有编码比特率以“比特/秒”为单位。In the v3 APIs, all of the encoding bit rates are in bits per second. 这与 v2 Media Encoder Standard 预设不同。This is different than the v2 Media Encoder Standard presets. 例如,v2 中的比特率指定为 128 (kbps),而在 v3 中,则指定 128000(比特/秒)。For example, the bitrate in v2 would be specified as 128 (kbps), but in v3 it would be 128000 (bits/second).
  • v3 中不存在实体 AssetFile、AccessPolicy 和 Ingestmanifest。Entities AssetFiles, AccessPolicies, and IngestManifests do not exist in v3.
  • v3 中不存在 IAsset.ParentAssets 属性。The IAsset.ParentAssets property does not exist in v3.
  • 现在,Contentkey 不再是实体,而是流式处理定位符的一个属性。ContentKeys is no longer an entity, it is now a property of the Streaming Locator.
  • 事件网格支持替换 NotificationEndpoint。Event Grid support replaces NotificationEndpoints.
  • 以下实体已重命名The following entities were renamed
    • 作业输出取代了任务,现在是作业的一部分。Job Output replaces Task, and is now part of a Job.
    • 流式处理定位符取代了定位符。Streaming Locator replaces Locator.
    • 直播活动取代了频道。Live Event replaces Channel.
      直播活动计费基于实时频道计量器。Live Events billing is based on Live Channel meters. 有关详细信息,请参阅计费定价For more information, see billing and pricing.
    • 实时输出取代了节目。Live Output replaces Program.
  • 实时输出在创建时启动,在删除后停止。Live Outputs start on creation and stop when deleted. v2 API 中的节目以不同的方式工作,它们必须在创建后启动。Programs worked differently in the v2 APIs, they had to be started after creation.
  • 若要获取有关作业的信息,需要知道创建作业时使用的转换名称。To get information about a job, you need to know the Transform name under which the job was created.
  • 在 v2 中,XML 输入输出元数据文件将作为编码作业的结果生成。In v2, XML input and output metadata files get generated as the result of an encoding job. 在 v3 中,元数据格式已从 XML 更改为 JSON。In v3, the metadata format changed from XML to JSON.


查看适用于媒体服务 v3 资源的命名约定。Review the naming conventions that are applied to Media Services v3 resources. 还要查看命名 BlobAlso review naming blobs.

与 v2 API 之间的功能差距Feature gaps with respect to v2 APIs

与 v2 API 相比,v3 API 存在以下功能差距。The v3 API has the following feature gaps with respect to the v2 API. 我们正在弥补这些差距。Closing the gaps is work in progress.

  • 媒体分析处理器(Azure 媒体服务索引器 2 预览版、Face Redactor 等)不可通过 v3 访问。The legacy media analytics processors (Azure Media Services Indexer 2 Preview, Face Redactor, etc.) are not accessible via v3.
    想要从媒体索引器 1 或 2 预览版迁移的客户可以立即使用 v3 API 中的 AudioAnalyzer 预设。Customers who wish to migrate from the Media Indexer 1 or 2 preview can immediately use the AudioAnalyzer preset in the v3 API. 此新预设包含的功能比旧版媒体索引器 1 或 2 更多。This new preset contains more features than the older Media Indexer 1 or 2.

  • v2 API 中的许多 Media Encoder Standard 高级功能目前在 v3 中不可用,例如:Many of the advanced features of the Media Encoder Standard in v2 APIs are currently not available in v3, such as:

    • 资产拼接Stitching of Assets
    • 叠加Overlays
    • 裁剪Cropping
    • 缩略图子画面Thumbnail Sprites
    • 在输入不包含音频时插入静音曲目Inserting a silent audio track when input has no audio
    • 在输入不包含视频时插入视频轨道Inserting a video track when input has no video
  • 包含转码的直播活动目前不支持静态图像插入中间流,以及通过 API 调用执行的广告标记插入。Live Events with transcoding currently do not support Slate insertion mid-stream and ad marker insertion via API call.


请将本文加入书签,并不时地查看最新信息。Please bookmark this article and keep checking for updates.

代码差异Code differences

下表显示了常见方案中 v2 和 v3 的代码差异。The following table shows the code differences between v2 and v3 for common scenarios.

方案Scenario V2 APIV2 API V3 APIV3 API
创建资产并上传文件Create an asset and upload a file v2 .NET 示例v2 .NET example v3 .NET 示例v3 .NET example
提交作业Submit a job v2 .NET 示例v2 .NET example v3 .NET 示例v3 .NET example

演示如何先创建转换,再提交作业。Shows how to first create a Transform and then submit a Job.
发布使用 AES 加密的资产Publish an asset with AES encryption 1.创建 ContentKeyAuthorizationPolicyOption1. Create ContentKeyAuthorizationPolicyOption
2.创建 ContentKeyAuthorizationPolicy2. Create ContentKeyAuthorizationPolicy
3.创建 AssetDeliveryPolicy3. Create AssetDeliveryPolicy
4.创建资产并上传内容或提交作业并使用输出资产4. Create Asset and upload content OR Submit job and use output asset
5.将 AssetDeliveryPolicy 与 Asset 关联5. Associate AssetDeliveryPolicy with Asset
6.创建 ContentKey6. Create ContentKey
7.将 ContentKey 附加到 Asset7. Attach ContentKey to Asset
8.创建 AccessPolicy8. Create AccessPolicy
9.创建 Locator9. Create Locator

v2 .NET 示例v2 .NET example
1.创建内容密钥策略1. Create Content Key Policy
2.创建 Asset2. Create Asset
3.上传内容或将 Asset 用作 JobOutput3. Upload content or use Asset as JobOutput
4.创建流式处理定位符4. Create Streaming Locator

v3 .NET 示例v3 .NET example
获取作业详细信息和管理作业Get job details and manage jobs 使用 v2 管理作业Manage jobs with v2 使用 v3 管理作业Manage jobs with v3

已知问题Known issues

  • 目前,无法使用 Azure 门户来管理 v3 资源。Currently, you cannot use the Azure portal to manage v3 resources. 请使用 REST API、CLI 或支持的 SDK 之一。Use the REST API, CLI, or one of the supported SDKs.
  • 需要在帐户中预配媒体预留单位 (MRU) 才能控制作业的并发和性能,特别是涉及到视频或音频分析的那些作业。You need to provision Media Reserved Units (MRUs) in your account in order to control the concurrency and performance of your Jobs, particularly ones involving Video or Audio Analysis. 有关详细信息,请参阅缩放媒体处理For more information, see Scaling Media Processing. 可以使用适用于媒体服务 v3 的 CLI 2.0、使用 Azure 门户v2 API 来管理 MRU。You can manage the MRUs using CLI 2.0 for Media Services v3, using the Azure portal, or using the v2 APIs. 无论使用的是媒体服务 v2 还是 v3 API,都需要预配 MRU。You need to provision MRUs, whether you are using Media Services v2 or v3 APIs.
  • 无法使用 v2 API 来管理通过 v3 API 创建的媒体服务实体。Media Services entities created with the v3 API cannot be managed by the v2 API.
  • 并非 V2 API 中的所有实体都自动出现在 V3 API 中。Not all entities in the V2 API automatically show up in the V3 API. 以下是这两个版本中不兼容的实体的示例:Following are examples of entities in the two versions that are incompatible:
    • 在 v2 中创建作业和任务不会在 v3 中显示,因为它们不与转换相关联。Jobs and Tasks created in v2 do not show up in v3 as they are not associated with a Transform. 建议切换到 v3 转换和作业。The recommendation is to switch to v3 Transforms and Jobs. 在切换过程中,需要花费一段相对较短的时间来监视即时 v2 作业。There will be a relatively short time period of needing to monitor the inflight v2 Jobs during the switchover.
    • 无法持续使用 v3 来管理通过 v2 创建的频道和节目(映射到 v3 中的直播活动和实时输出)。Channels and Programs created with v2 (which are mapped to Live Events and Live Outputs in v3) cannot continue being managed with v3. 建议在方便停止频道时切换到 v3 直播活动和实时输出。The recommendation is to switch to v3 Live Events and Live Outputs at a convenient Channel stop.
      目前,无法持续迁移正在运行的频道。Presently, you cannot migrate continuously running Channels.


在媒体服务团队不断改进 v3 API 并解决版本差距的过程中,本页面会得到维护。This page will be maintained as the Media Services team makes continued improvements to the v3 APIs and addresses the gaps between the versions.

后续步骤Next steps

若要了解如何轻松地开始编码和流式传输视频文件,请查看流文件To see how easy it is to start encoding and streaming video files, check out Stream files.