使用 .NET SDK 配置资产传送策略Configure asset delivery policies with .NET SDK

Note

Google Widevine 内容保护服务目前在 Azure 中国区域不可用。Google Widevine content protection services are currently unavailable in the Azure China regions.

概述Overview

如果打算传送加密资产,媒体服务内容传送工作流中的步骤之一是为资产配置传送策略。If you plan to delivery encrypted assets, one of the steps in the Media Services content delivery workflow is configuring delivery policies for assets. 资产传送策略告知媒体服务希望如何传送资产:应该将资产动态打包成哪种流式处理协议(例如 MPEG DASH、HLS、平滑流或全部),是否要动态加密资产以及如何加密(信封或常用加密)。The asset delivery policy tells Media Services how you want for your asset to be delivered: into which streaming protocol should your asset be dynamically packaged (for example, MPEG DASH, HLS, Smooth Streaming, or all), whether or not you want to dynamically encrypt your asset and how (envelope or common encryption).

本文介绍为何以及如何创建和配置资产传送策略。This article discusses why and how to create and configure asset delivery policies.

Note

创建 AMS 帐户后,系统会将一个处于“已停止”状态的默认 流式处理终结点添加到帐户。 When your AMS account is created, a default streaming endpoint is added to your account in the Stopped state. 若要开始流式传输内容并利用动态打包和动态加密,要从中流式传输内容的流式处理终结点必须处于“正在运行”状态。 To start streaming your content and take advantage of dynamic packaging and dynamic encryption, the streaming endpoint from which you want to stream content has to be in the Running state.

此外,要使用动态打包和动态加密,资产必须包含一组自适应比特率 MP4 或自适应比特率平滑流式处理文件。Also, to be able to use dynamic packaging and dynamic encryption your asset must contain a set of adaptive bitrate MP4s or adaptive bitrate Smooth Streaming files.

可以将不同的策略应用到同一个资产。You could apply different policies to the same asset. 例如,可以将 PlayReady 加密应用到平滑流,将 AES 信封应用到 MPEG DASH 和 HLS。For example, you could apply PlayReady encryption to Smooth Streaming and AES Envelope encryption to MPEG DASH and HLS. 将阻止流式处理传送策略中未定义的任何协议(例如,添加仅将 HLS 指定为协议的单个策略)。Any protocols that are not defined in a delivery policy (for example, you add a single policy that only specifies HLS as the protocol) will be blocked from streaming. 如果根本没有定义任何资产传送策略,则属例外。The exception is if you have no asset delivery policy defined at all. 此时,将允许所有明文形式的协议。Then, all protocols will be allowed in the clear.

如果要传送存储加密资产,则必须配置资产的传送策略。If you want to deliver a storage encrypted asset, you must configure the asset’s delivery policy. 在流式传输资产之前,流式处理服务器会删除存储加密,然后再使用指定的传送策略流式传输内容。Before your asset can be streamed, the streaming server removes the storage encryption and streams your content using the specified delivery policy. 例如,要传送使用高级加密标准 (AES) 信封加密密钥加密的资产,请将策略类型设为 DynamicEnvelopeEncryptionFor example, to deliver your asset encrypted with Advanced Encryption Standard (AES) envelope encryption key, set the policy type to DynamicEnvelopeEncryption. 要删除存储加密并以明文的形式流式传输资产,请将策略类型设为 NoDynamicEncryptionTo remove storage encryption and stream the asset in the clear, set the policy type to NoDynamicEncryption. 下面是演示如何配置这些策略类型的示例。Examples that show how to configure these policy types follow.

根据配置资产传送策略的方式,可以动态打包、加密和流式传输以下流式处理协议:平滑流式处理、HLS 和 MPEG DASH。Depending on how you configure the asset delivery policy, you can dynamically package, encrypt, and stream the following streaming protocols: Smooth Streaming, HLS, and MPEG DASH.

以下列表显示了用于流式传输平滑流、HLS 和 DASH 的格式。The following list shows the formats that you use to stream Smooth, HLS, and DASH.

平滑流:Smooth Streaming:

{流式处理终结点名称-媒体服务帐户名称}.streaming.mediaservices.chinacloudapi.cn/{定位符 ID}/{文件名}.ism/Manifest{streaming endpoint name-media services account name}.streaming.mediaservices.chinacloudapi.cn/{locator ID}/{filename}.ism/Manifest

HLS:HLS:

{流式处理终结点名称-媒体服务帐户名称}.streaming.mediaservices.chinacloudapi.cn/{定位符 ID}/{文件名}.ism/Manifest(format=m3u8-aapl){streaming endpoint name-media services account name}.streaming.mediaservices.chinacloudapi.cn/{locator ID}/{filename}.ism/Manifest(format=m3u8-aapl)

MPEG DASHMPEG DASH

{流式处理终结点名称-媒体服务帐户名称}.streaming.mediaservices.chinacloudapi.cn/{定位符 ID}/{文件名}.ism/Manifest(format=mpd-time-csf){streaming endpoint name-media services account name}.streaming.mediaservices.chinacloudapi.cn/{locator ID}/{filename}.ism/Manifest(format=mpd-time-csf)

注意事项Considerations

  • 删除 AssetDeliveryPolicy 之前,应删除所有与此资产关联的流式处理定位符。Before deleting the AssetDeliveryPolicy, you should delete all of the streaming locators associated with the asset. 如果需要,可稍后使用新的 AssetDeliveryPolicy 创建新的流式处理定位符。You can later create new streaming locators, if desired, with a new AssetDeliveryPolicy.
  • 如果未设置资产传送策略,则无法在存储加密的资产上创建流式处理定位符。A streaming locator cannot be created on a storage encrypted asset when no asset delivery policy is set. 如果资产未经过存储加密,则即使未设置资产传送策略,系统也可让你顺利地创建定位符和流式处理资产。If the Asset isn’t storage encrypted, the system will let you create a locator and stream the asset in the clear without an asset delivery policy.
  • 可将多个资产传送策略关联到单个资产,但只能指定一种方法来处理给定的 AssetDeliveryProtocol。You can have multiple asset delivery policies associated with a single asset but you can only specify one way to handle a given AssetDeliveryProtocol. 也就是说,如果尝试链接两个指定 AssetDeliveryProtocol.SmoothStreaming 协议的传送策略,则会导致出错,因为当客户端发出平滑流请求时,系统不知道要应用哪个策略。Meaning if you try to link two delivery policies that specify the AssetDeliveryProtocol.SmoothStreaming protocol that will result in an error because the system does not know which one you want it to apply when a client makes a Smooth Streaming request.
  • 如果资产包含现有的流式处理定位符,则不能将新策略链接到该资产(可以取消现有策略与资产的链接,或者更新与该资产关联的传送策略)。If you have an asset with an existing streaming locator, you cannot link a new policy to the asset (you can either unlink an existing policy from the asset, or update a delivery policy associated with the asset). 必须先删除流式传输定位符,再调整策略,然后重新创建流式传输定位符。You first have to remove the streaming locator, adjust the policies, and then re-create the streaming locator. 重新创建流式处理定位符时,可以使用同一个 locatorId,但应确保该操作不会导致客户端出现问题,因为内容可能已被源缓存。You can use the same locatorId when you recreate the streaming locator but you should ensure that won’t cause issues for clients since content can be cached by the origin.

清除资产传送策略Clear asset delivery policy

以下 ConfigureClearAssetDeliveryPolicy 方法会指定不应用动态加密,而是使用以下任一协议传送流:MPEG DASH、HLS 和平滑流协议。The following ConfigureClearAssetDeliveryPolicy method specifies to not apply dynamic encryption and to deliver the stream in any of the following protocols: MPEG DASH, HLS, and Smooth Streaming protocols. 可能需要对存储加密资产应用此策略。You might want to apply this policy to your storage encrypted assets.

有关创建 AssetDeliveryPolicy 时可以指定哪些值的信息,请参阅定义 AssetDeliveryPolicy 时使用的类型部分。For information on what values you can specify when creating an AssetDeliveryPolicy, see the Types used when defining AssetDeliveryPolicy section.

    static public void ConfigureClearAssetDeliveryPolicy(IAsset asset)
    {
        IAssetDeliveryPolicy policy =
        _context.AssetDeliveryPolicies.Create("Clear Policy",
        AssetDeliveryPolicyType.NoDynamicEncryption,
        AssetDeliveryProtocol.HLS | AssetDeliveryProtocol.SmoothStreaming | AssetDeliveryProtocol.Dash, null);
        
        asset.DeliveryPolicies.Add(policy);
    }

DynamicCommonEncryption 资产传送策略DynamicCommonEncryption asset delivery policy

以下 CreateAssetDeliveryPolicy 方法将创建 AssetDeliveryPolicy,该策略配置为将动态常用加密 (DynamicCommonEncryption) 应用到平滑流式处理协议(将阻止流式处理其他协议)。The following CreateAssetDeliveryPolicy method creates the AssetDeliveryPolicy that is configured to apply dynamic common encryption (DynamicCommonEncryption) to a smooth streaming protocol (other protocols will be blocked from streaming). 该方法采用以下两种参数:Asset(要将传送策略应用到的资产)和 IContentKeyCommonEncryption 类型的内容密钥。有关详细信息,请参阅:创建内容密钥)。The method takes two parameters: Asset (the asset to which you want to apply the delivery policy) and IContentKey (the content key of the CommonEncryption type, for more information, see: Creating a content key).

有关创建 AssetDeliveryPolicy 时可以指定哪些值的信息,请参阅定义 AssetDeliveryPolicy 时使用的类型部分。For information on what values you can specify when creating an AssetDeliveryPolicy, see the Types used when defining AssetDeliveryPolicy section.

    static public void CreateAssetDeliveryPolicy(IAsset asset, IContentKey key)
    {
        Uri acquisitionUrl = key.GetKeyDeliveryUrl(ContentKeyDeliveryType.PlayReadyLicense);
        
        Dictionary<AssetDeliveryPolicyConfigurationKey, string> assetDeliveryPolicyConfiguration =
                new Dictionary<AssetDeliveryPolicyConfigurationKey, string>
            {
                {AssetDeliveryPolicyConfigurationKey.PlayReadyLicenseAcquisitionUrl, acquisitionUrl.ToString()},
            };
    
            var assetDeliveryPolicy = _context.AssetDeliveryPolicies.Create(
                    "AssetDeliveryPolicy",
                AssetDeliveryPolicyType.DynamicCommonEncryption,
                AssetDeliveryProtocol.SmoothStreaming,
                assetDeliveryPolicyConfiguration);
    
            // Add AssetDelivery Policy to the asset
            asset.DeliveryPolicies.Add(assetDeliveryPolicy);
    
            Console.WriteLine();
            Console.WriteLine("Adding Asset Delivery Policy: " +
                assetDeliveryPolicy.AssetDeliveryPolicyType);
     }

下例演示将 PlayReady 添加到资产传送策略。The following example demonstrates PlayReady being added to the asset delivery policy.

    static public void CreateAssetDeliveryPolicy(IAsset asset, IContentKey key)
    {
        // Get the PlayReady license service URL.
        Uri acquisitionUrl = key.GetKeyDeliveryUrl(ContentKeyDeliveryType.PlayReadyLicense);


        Dictionary<AssetDeliveryPolicyConfigurationKey, string> assetDeliveryPolicyConfiguration =
            new Dictionary<AssetDeliveryPolicyConfigurationKey, string>
        {
            {AssetDeliveryPolicyConfigurationKey.PlayReadyLicenseAcquisitionUrl, acquisitionUrl.ToString()}

        };

        var assetDeliveryPolicy = _context.AssetDeliveryPolicies.Create(
                "AssetDeliveryPolicy",
            AssetDeliveryPolicyType.DynamicCommonEncryption,
            AssetDeliveryProtocol.Dash,
            assetDeliveryPolicyConfiguration);


        // Add AssetDelivery Policy to the asset
        asset.DeliveryPolicies.Add(assetDeliveryPolicy);

    }

DynamicEnvelopeEncryption 资产传送策略DynamicEnvelopeEncryption asset delivery policy

以下 CreateAssetDeliveryPolicy 方法将创建 AssetDeliveryPolicy,该策略配置为将动态信封加密 (DynamicEnvelopeEncryption) 应用到平滑流式处理、HLS 和 DASH 协议(如果不指定协议,则将阻止对这些协议进行流式处理)。The following CreateAssetDeliveryPolicy method creates the AssetDeliveryPolicy that is configured to apply dynamic envelope encryption (DynamicEnvelopeEncryption) to Smooth Streaming, HLS, and DASH protocols (if you decide to not specify some protocols, they will be blocked from streaming). 该方法采用以下两种参数:Asset(要将传送策略应用到的资产)和 IContentKeyEnvelopeEncryption 类型的内容密钥。有关详细信息,请参阅:创建内容密钥)。The method takes two parameters: Asset (the asset to which you want to apply the delivery policy) and IContentKey (the content key of the EnvelopeEncryption type, for more information, see: Creating a content key).

有关创建 AssetDeliveryPolicy 时可以指定哪些值的信息,请参阅定义 AssetDeliveryPolicy 时使用的类型部分。For information on what values you can specify when creating an AssetDeliveryPolicy, see the Types used when defining AssetDeliveryPolicy section.

    private static void CreateAssetDeliveryPolicy(IAsset asset, IContentKey key)
    {

        //  Get the Key Delivery Base Url by removing the Query parameter.  The Dynamic Encryption service will
        //  automatically add the correct key identifier to the url when it generates the Envelope encrypted content
        //  manifest.  Omitting the IV will also cause the Dynamic Encryption service to generate a deterministic
        //  IV for the content automatically.  By using the EnvelopeBaseKeyAcquisitionUrl and omitting the IV, this
        //  allows the AssetDelivery policy to be reused by more than one asset.
        //
        Uri keyAcquisitionUri = key.GetKeyDeliveryUrl(ContentKeyDeliveryType.BaselineHttp);
        UriBuilder uriBuilder = new UriBuilder(keyAcquisitionUri);
        uriBuilder.Query = String.Empty;
        keyAcquisitionUri = uriBuilder.Uri;

        // The following policy configuration specifies: 
        //   key url that will have KID=<Guid> appended to the envelope and
        //   the Initialization Vector (IV) to use for the envelope encryption.
        Dictionary<AssetDeliveryPolicyConfigurationKey, string> assetDeliveryPolicyConfiguration =
            new Dictionary<AssetDeliveryPolicyConfigurationKey, string> 
        {
            {AssetDeliveryPolicyConfigurationKey.EnvelopeBaseKeyAcquisitionUrl, keyAcquisitionUri.ToString()},
        };

        IAssetDeliveryPolicy assetDeliveryPolicy =
            _context.AssetDeliveryPolicies.Create(
                        "AssetDeliveryPolicy",
                        AssetDeliveryPolicyType.DynamicEnvelopeEncryption,
                        AssetDeliveryProtocol.SmoothStreaming | AssetDeliveryProtocol.HLS | AssetDeliveryProtocol.Dash,
                        assetDeliveryPolicyConfiguration);

        // Add AssetDelivery Policy to the asset
        asset.DeliveryPolicies.Add(assetDeliveryPolicy);

        Console.WriteLine();
        Console.WriteLine("Adding Asset Delivery Policy: " + assetDeliveryPolicy.AssetDeliveryPolicyType);
    }

定义 AssetDeliveryPolicy 时使用的类型Types used when defining AssetDeliveryPolicy

AssetDeliveryProtocolAssetDeliveryProtocol

以下枚举说明可以为资产传递协议设置的值。The following enum describes values you can set for the asset delivery protocol.

    [Flags]
    public enum AssetDeliveryProtocol
    {
        /// <summary>
        /// No protocols.
        /// </summary>
        None = 0x0,

        /// <summary>
        /// Smooth streaming protocol.
        /// </summary>
        SmoothStreaming = 0x1,

        /// <summary>
        /// MPEG Dynamic Adaptive Streaming over HTTP (DASH)
        /// </summary>
        Dash = 0x2,

        /// <summary>
        /// Apple HTTP Live Streaming protocol.
        /// </summary>
        HLS = 0x4,

        ProgressiveDownload = 0x10, 
 
        /// <summary>
        /// Include all protocols.
        /// </summary>
        All = 0xFFFF
    }

AssetDeliveryPolicyTypeAssetDeliveryPolicyType

以下枚举说明可以为资产传递策略类型设置的值。The following enum describes values you can set for the asset delivery policy type.

    public enum AssetDeliveryPolicyType
    {
        /// <summary>
        /// Delivery Policy Type not set.  An invalid value.
        /// </summary>
        None,

        /// <summary>
        /// The Asset should not be delivered via this AssetDeliveryProtocol. 
        /// </summary>
        Blocked, 

        /// <summary>
        /// Do not apply dynamic encryption to the asset.
        /// </summary>
        /// 
        NoDynamicEncryption,  

        /// <summary>
        /// Apply Dynamic Envelope encryption.
        /// </summary>
        DynamicEnvelopeEncryption,

        /// <summary>
        /// Apply Dynamic Common encryption.
        /// </summary>
        DynamicCommonEncryption
        }

ContentKeyDeliveryTypeContentKeyDeliveryType

以下枚举说明可用于配置到客户端的内容密钥传递方法的值。The following enum describes values you can use to configure the delivery method of the content key to the client.

  public enum ContentKeyDeliveryType
  {
      /// <summary>
      /// None.
      ///
      </summary>
      None = 0,

      /// <summary>
      /// Use PlayReady License acquisition protocol
      ///
      </summary>
      PlayReadyLicense = 1,

      /// <summary>
      /// Use MPEG Baseline HTTP key protocol.
      ///
      </summary>
      BaselineHttp = 2

  }

AssetDeliveryPolicyConfigurationKeyAssetDeliveryPolicyConfigurationKey

以下枚举说明为配置用于获取资产传递策略的特定配置的密钥可以设置的值。The following enum describes values you can set to configure keys used to get specific configuration for an asset delivery policy.

    public enum AssetDeliveryPolicyConfigurationKey
    {
        /// <summary>
        /// No policies.
        /// </summary>
        None,

        /// <summary>
        /// Exact Envelope key URL.
        /// </summary>
        EnvelopeKeyAcquisitionUrl,

        /// <summary>
        /// Base key url that will have KID=<Guid> appended for Envelope.
        /// </summary>
        EnvelopeBaseKeyAcquisitionUrl,

        /// <summary>
        /// The initialization vector to use for envelope encryption in Base64 format.
        /// </summary>
        EnvelopeEncryptionIVAsBase64,

        /// <summary>
        /// The PlayReady License Acquisition Url to use for common encryption.
        /// </summary>
        PlayReadyLicenseAcquisitionUrl,

        /// <summary>
        /// The PlayReady Custom Attributes to add to the PlayReady Content Header
        /// </summary>
        PlayReadyCustomAttributes,

        /// <summary>
        /// The initialization vector to use for envelope encryption.
        /// </summary>
        EnvelopeEncryptionIV
    }

媒体服务学习路径Media Services learning paths

媒体服务 v3(最新版本)Media Services v3 (latest)

查看最新版本的 Azure 媒体服务!Check out the latest version of Azure Media Services!

媒体服务 v2(旧版)Media Services v2 (legacy)