本指南說明如何產生權杖,以及權杖的必要和選用欄位。
如要建立權杖,請編寫要簽署的字串,在本指南中稱為「已簽署的值」。簽署的值包含描述受保護內容的參數、簽署值的到期時間等。
建立權杖字串時,您會使用已簽署的值。您可透過組合權杖的參數 (例如簽署值的對稱金鑰雜湊式訊息驗證碼 (HMAC)),建立權杖字串。
Media CDN 會使用最終組成的權杖,協助保護您的內容。
建立權杖
使用 Ed25519 簽章或對稱金鑰 HMAC 簽署已簽署的值。
將含有必要權杖欄位和選用權杖欄位的字串串連起來,即可組成權杖。請以半形波浪號
~
分隔各個欄位和所有參數。編寫權杖時,簽署值和權杖字串中每個參數的值都相同,但下列情況除外:
FullPath
Headers
以下程式碼範例說明如何以程式輔助方式建立權杖:
Python
如要向 Media CDN 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
如要向 Media 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` 的有效 URLPrefix 值包括 `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 |
採用 Base64 編碼的網路安全 HMAC 值。 | 不適用 |
PathGlobs
萬用字元語法
下表說明 PathGlobs
萬用字元語法。
運算子 | 相符 | 範例 |
---|---|---|
* (星號) |
比對網址路徑中零個或多個字元,包括斜線 (/ ) 字元。 |
|
? (問號) |
比對網址路徑中的單一字元,不包括斜線 (/ ) 字元。 |
/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 |
最多五個 IPv4 和 IPv6 位址的清單 (採用 CIDR 格式),這些位址的網址採用網頁安全 Base64 格式。舉例來說,如要指定 IP 範圍「192.6.13.13/32,193.5.64.135/32」,請指定 如果用戶端有 WAN 遷移風險,或是應用程式前端的網路路徑與傳送路徑不同,則在權杖中加入 IPRanges 可能沒有幫助。如果用戶端連線時使用的 IP 位址不在已簽署的要求中,Media CDN 會以 在下列情況下,Media CDN 可能會以
這些因素都可能導致特定用戶端在影片播放期間擁有非決定性 IP 位址。如果發出存取權後用戶端 IP 位址變更,且用戶端嘗試將影片片段下載至播放緩衝區,則會收到 Media 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
,但預期的標頭值不會從簽署值重複。這樣一來,您就能簽署特定要求標頭鍵/值組合,而不必在權杖中重複這些值。