本指南說明如何產生權杖,以及權杖的必要和選用欄位。
如要建立權杖,請撰寫要簽署的字串,在本指南中稱為「已簽署的值」。簽署值包含的參數會說明您要保護的內容、簽署值的到期時間等。
建立權杖字串時,請使用已簽署的值。您可以透過組合權杖的參數 (例如已簽署值的對稱金鑰雜湊型訊息驗證碼 (HMAC)),建立權杖字串。
Media CDN 會使用最終組合的權杖,協助保護內容。
建立權杖
使用 Ed25519 簽章或對稱金鑰 HMAC 簽署已簽署的值。
串連包含必要權杖欄位和選用權杖欄位的字串,即可組成權杖。請以波浪號
~分隔各個欄位和參數。建立權杖時,每個參數的值在已簽署值和權杖字串之間都相同,但有下列例外狀況:
FullPathHeaders
以下程式碼範例說明如何以程式輔助方式建立權杖:
Python
如要向 Media CDN 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Media CDN 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
以下各節說明權杖使用的欄位。
必要的權杖欄位
每個權杖都必須包含下列欄位:
Expires- 下列任一項:
PathGlobsURLPrefixFullPath
- 下列其中一項:
Signaturehmac
除非另有指定,否則參數名稱和值會區分大小寫。
下表說明各個參數:
| 欄位名稱/別名 | 權杖參數 | 帶正負號的值 |
|---|---|---|
|
自 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 |
HMAC 值的網路安全 Base64 編碼版本。 | 不適用 |
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 |
以半形逗號分隔的標頭欄位名稱清單,最多 10 個。在要求中查詢時,標頭名稱不區分大小寫。已簽署值中的標頭名稱會區分大小寫。如果缺少標頭,值會是空白字串。
因此,建議您使用不透明的值 (例如工作階段或裝置 ID) 簽署自訂標頭。請避免簽署值通常包含半形逗號的標頭,例如 |
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 值:
* - 預期的要求標頭:
x-session-id: abcd1234x-client-version: 5.2.0
簽署的值為:
Expires=160000000~PathGlobs=*~Headers=x-session-id=abcd1234,x-client-version=5.2.0
如要建立權杖,請使用 Ed25519 簽章或對稱金鑰 HMAC 簽署已簽署的值。
以下是根據已簽署值建立的權杖範例:
Ed25519 簽章
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~Signature=SIGNATURE_OF_SIGNED_VALUE
其中 SIGNATURE_OF_SIGNED_VALUE 是先前建立的簽署值 ED25519 簽章。
對稱金鑰 HMAC
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~hmac=HMAC_OF_SIGNED_VALUE
其中 HMAC_OF_SIGNED_VALUE 是先前建立的已簽署值對稱金鑰 HMAC。
在上述範例中,權杖中會提供 Headers=x-session-id,x-client-version,但預期的標頭值不會從已簽署的值重複。這樣一來,您就能簽署特定要求標頭鍵/值組合,而不必複製權杖中的值。