本指南介绍了如何生成令牌,以及令牌的必填字段和选填字段。
如需创建令牌,您需要编写一个要签名的字符串,我们在本指南中将其称为有符号值。带符号的值包括描述您要保护的内容、带符号值的过期时间等参数。
您在创建令牌字符串时将使用带符号的值。您可以通过组合令牌的参数(例如签名值的对称密钥哈希消息身份验证代码 (HMAC))来创建令牌字符串。
媒体 CDN 使用最终组合的令牌来帮助保护您的内容。
创建令牌
使用 Ed25519 签名或对称密钥 HMAC 对已签名的值进行签名。
串联包含必需令牌字段和可选令牌字段的字符串,以编写令牌。请使用波浪号
~
字符分隔每个字段和所有参数。编写令牌时,带符号值和令牌字符串之间每个参数的值都相同,但存在以下例外情况:
FullPath
Headers
以下代码示例展示了如何以编程方式创建令牌:
Python
如需向媒体 CDN 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向媒体 CDN 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
以下部分介绍了令牌使用的字段。
必需的令牌字段
对于每个令牌,以下字段都是必填字段:
Expires
- 以下任意一项:
PathGlobs
URLPrefix
FullPath
- 以下任意一项:
Signature
hmac
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了各个参数:
字段名称 / 别名 | 令牌参数 | 有符号值 |
---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 起经过的整数秒数 | Expires=EXPIRATION_TIME ,之后令牌将失效。 |
|
要授予访问权限的路径段的列表(最多五个)。这些段可以使用英文逗号 (
不允许使用以英文分号 ( 出于上述原因,请确保您的网址不包含以下特殊字符: |
PathGlobs=PATHS |
URLPrefix |
一个可在网络中安全使用的 base64 编码网址,其中包含 例如,“https://example.com/foo/bar.ts”的一些有效 网址Prefix 值包括“https://example.com”“https://example.com/foo”和“https://example.com/foo/bar”。 |
URLPrefix=BASE_64_URL_PREFIX |
FullPath |
无。在令牌中指定 FullPath 时,不要复制在签名值中指定的路径。在令牌中,包含字段名称但不带 = 。 |
FullPath=FULL_PATH_TO_OBJECT |
Signature |
网络安全的 base64 编码版本的签名。 | 不适用 |
hmac |
HMAC 值的 Web 安全 base64 编码版本。 | 不适用 |
PathGlobs
通配符语法
下表介绍了 PathGlobs
通配符语法。
运算符 | Matches | 示例 |
---|---|---|
* (星号) |
匹配网址路径中的零个或多个字符,包括正斜杠 (/ ) 字符。
|
|
? (问号) |
匹配网址路径中的单个字符,不包括正斜杠 (/ ) 字符。
|
/videos/s?main.m3u8 与 /videos/s1main.m3u8 匹配。它与 /videos/s01main.m3u8 或 /videos/s/main.m3u8 中的任何一个都不匹配。
|
对于网址路径,glob 必须以星号 (*
) 或正斜杠 (/
) 开头。
由于 *
和 /*
会匹配所有网址路径,因此我们不建议在签名令牌中使用这两者。为了最大限度提供保护,请确保您的 glob 与您打算授予访问权限的内容相匹配。
可选令牌字段
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了参数名称、任何别名和可选参数的详细信息:
字段名称 / 别名 | 参数 | 有符号值 |
---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 以来的整数秒数 | Starts=START_TIME |
IPRanges |
一个 CIDR 格式的 IPv4 和 IPv6 地址列表(最多五个),此网址采用可保障网络安全的 base64 格式。例如,如需指定 IP 范围“192.6.13.13/32,193.5.64.135/32”,您可以指定 当客户端面临 WAN 迁移风险或应用前端的网络路径与传送路径不同时,在令牌中添加 IP 地址范围可能没有帮助。如果客户端所连接 IP 地址不属于签名请求,则媒体 CDN 会拒绝包含 以下情况可能会导致媒体 CDN 拒绝包含
所有这些因素都会导致给定客户端在视频播放会话期间具有不确定的 IP 地址。如果客户端 IP 地址在您授予访问权限后发生更改,而客户端尝试随后将视频片段下载到其播放缓冲区,则它们会从媒体 CDN 收到 |
IPRanges=BASE_64_IP_RANGES |
|
任意字符串,适用于日志分析或回放跟踪。 为避免创建无效令牌,请使用 % 编码或网络安全 base64 编码的字符串。不得对 |
SessionID=SESSION_ID_VALUE |
|
任意字符串,适用于日志分析。 为避免创建无效令牌,请使用 % 编码或网络安全 base64 编码的字符串。不得对 |
data=DATA_VALUE |
Headers |
以英文逗号分隔的标头字段名称列表。对于请求中的查找,标头名称不区分大小写。签名值中的标头名称区分大小写。如果缺少标头,则该值为空字符串。如果标头有多个副本,这些副本会用英文逗号分隔。 | Headers=HEADER_1_NAME=HEADER_1_EXPECTED_VALUE,
HEADER_2_NAME=HEADER_2_EXPECTED_VALUE |
示例
以下部分展示了生成令牌的示例。
使用 FullPath
的示例
请参考以下示例(使用 FullPath
字段):
- 所请求的项:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- 到期时间:160000000
带符号的值为:
Expires=160000000~FullPath=/tv/my-show/s01/e01/playlist.m3u8
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对已签名的值进行签名。
以下是根据有符号值创建的示例令牌:
Ed25519 签名
Expires=160000000~FullPath~Signature=SIGNATURE_OF_SIGNED_VALUE
其中 SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~FullPath~hmac=HMAC_OF_SIGNED_VALUE
其中 HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
在前面的示例中,令牌中提供了 FullPath
,但签名值中指定的路径没有重复值。这样,您就可以对请求的完整路径进行签名,而无需在令牌中复制请求。
使用 URLPrefix
的示例
请参考以下示例(使用 URLPrefix
字段):
- 所请求的项:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- 到期时间:160000000
带符号的值为:
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
在前面的示例中,我们将所请求项的路径 http://example.com/tv/my-show/s01/e01/playlist.m3u8
替换为该项路径(采用网络安全 Base64 格式 aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
)。
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对已签名的值进行签名。
以下是根据有符号值创建的示例令牌:
Ed25519 签名
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~Signature=SIGNATURE_OF_SIGNED_VALUE
其中 SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~hmac=HMAC_OF_SIGNED_VALUE
其中 HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
使用 Headers
的示例
请参考以下示例(使用 Headers
字段):
- 所请求的项:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- 到期时间:160000000
- PathGlobs 值:
*
- 预期的请求标头:
user-agent: browser
accept: text/html
带符号的值为:
Expires=160000000~PathGlobs=*~Headers=user-agent=browser,accept=text/html
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对已签名的值进行签名。
以下是根据有符号值创建的示例令牌:
Ed25519 签名
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~Signature=SIGNATURE_OF_SIGNED_VALUE
其中 SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~hmac=HMAC_OF_SIGNED_VALUE
其中 HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
在前面的示例中,令牌中提供了 Headers=user-agent,accept
,但预期的标头值并没有从签名值中重复。这样,您就可以对特定的请求标头键值对进行签名,而无需复制令牌中的值。