REST API V2檢查清單
- 主題:
- 驗證
本檔案針對實作使用Adobe Pass驗證REST API V2的使用者端應用程式的程式設計人員,彙總其強制需求與建議作法。
在實作REST API V2時,遵循本檔案必須視為驗收標準的一部分,且必須用作檢查清單,以確保已採取所有必要步驟來取得成功的整合。
強制需求
1.註冊階段
需求 | 風險 | |
---|---|---|
註冊的應用程式範圍 | 使用具有REST API v2範圍的已註冊應用程式。 | 觸發HTTP 401「未獲授權」錯誤回應、系統資源超載及延遲增加的風險。 |
使用者端憑證快取 | 將使用者端憑證儲存在永久儲存體中,並重複用於每個存取權杖請求。 | 重新產生使用者端認證時,可能會遺失驗證。 |
存取權杖快取 | 將存取權杖儲存在永久儲存體中,並重複使用直到過期為止。 請勿為每個REST API v2呼叫要求新的權杖,只有在存取權杖過期時才重新整理存取權杖。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
2.設定階段
需求 | 風險 | |
---|---|---|
設定擷取 |
只有在需要提示使用者在驗證階段之前選取其MVPD (電視提供者)時,才會擷取設定回應。
| 可能會造成系統資源超載及延遲增加。 |
TV提供者選擇快取 |
將使用者的付費電視提供者(MVPD)選擇專案儲存在永久儲存空間中,以便用於所有後續階段:
| 可能會造成系統資源超載及延遲增加。 |
3.驗證階段
需求 | 風險 | |
---|---|---|
輪詢機制啟動 |
在下列條件下啟動輪詢機制:
| 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
正在停止輪詢機制 |
在下列條件下停止輪詢機制:
驗證工作階段與程式碼到期
已產生新的驗證碼
| 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
輪詢機制設定 |
在下列條件下設定輪詢機制頻率:
| 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
設定檔快取 |
將部分使用者設定檔資訊儲存在永久儲存體中,以提高效能並將不必要的REST API v2呼叫降至最低。
屬性
| 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
4. (選擇性)預先授權階段
需求 | 風險 | |
---|---|---|
預先授權決定擷取 | 使用預先授權決定進行內容篩選,永不用於播放決定。 | 違反程式設計師、MVPD和Adobe之間合約協定的風險。 略過我們的監視和警示系統的風險。 |
預先授權決定擷取重試 | 適當處理增強型錯誤碼,並利用動作欄位來決定必要的修正步驟。 只有有限數目的增強型錯誤碼才應重試,而大多數需要其他解決方案,如動作欄位中所指定。 請確定任何針對擷取預先授權決定所實作的重試機制都不會導致無止境的回圈,而且它會將重試限製為合理的數字(即2-3)。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
預先授權決定快取 | 快取成功允許記憶體中的決定改善效能,並將不必要的REST API v2呼叫減至最少,因為應用程式執行時的訂閱更新並不頻繁。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
5.授權階段
需求 | 風險 | |
---|---|---|
授權決定擷取 | 在播放之前取得授權決定 — 無論預先授權決定是否存在。 即使媒體權杖在播放期間到期,並允許資料流繼續不受中斷,並在使用者提出下一個播放請求時請求包含(新增)媒體權杖的新授權決定,無論該媒體權杖是否用於相同或不同的資源。 長時間執行的即時資料流可選擇在視訊作業後要求新的授權決定,例如暫停內容、啟動商業插播,或在MRSS發生變更時修改資產層級設定。 | 違反程式設計師、MVPD和Adobe之間合約協定的風險。 略過我們的監視和警示系統的風險。 |
授權決定擷取重試 | 適當處理增強型錯誤碼,並利用動作欄位來決定必要的修正步驟。 只有有限數目的增強型錯誤碼才應重試,而大多數需要其他解決方案,如動作欄位中所指定。 請確定為擷取授權決定所實作的重試機制不會產生無止盡的回圈,而且它會將重試限製為合理的數字(即2-3)。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 |
6.登出階段
需求 | 風險 | |
---|---|---|
登出支援 |
實作登出API以允許使用者手動登出、終止其已驗證的設定檔,並遵循為每個已移除設定檔指定的REST API v2動作名稱:
| 由於缺少使用者端應用程式端的支援,導致使用者端應用程式故障的風險。 |
7.引數和標題
需求 | 風險 | |
---|---|---|
傳送授權標頭 | 針對每個REST API v2請求傳送Authorization標頭。 | 觸發HTTP 401「未獲授權」錯誤回應、系統資源超載及延遲增加的風險。 |
傳送AP-Device-Identifier標頭 | 針對每個REST API v2要求傳送AP-Device-Identifier標頭。 即使請求來自代表裝置的伺服器,AP-Device-Identifier標頭值也必須反映實際的串流裝置識別碼。 | 觸發HTTP 400「錯誤請求」錯誤回應、系統資源超載及延遲增加的風險。 |
傳送X-Device-Info標頭 | 針對每個REST API v2請求傳送X-Device-Info標頭。 即使請求來自代表裝置的伺服器,X-Device-Info標頭值也必須反映實際的串流裝置資訊。 | 歸類為源自未知平台且視為不安全的風險,會受限於較嚴格的規則,例如較短的驗證TTL。 此外,某些欄位(例如串流裝置connectionIp和connectionPort)是諸如Spectrum的Home Base Authentication之類功能的必要欄位。 |
穩定裝置識別碼 | 計算並儲存AP-Device-Identifier標頭的穩定裝置識別碼,此識別碼不會因更新或重新啟動而變更。 對於沒有硬體識別碼的平台,請從應用程式屬性產生唯一識別碼,並加以儲存。 | 裝置識別碼變更時,可能會遺失驗證。 |
遵循API參考 | 確保您只傳送REST API v2預期的引數和標頭。 | 觸發HTTP 400「錯誤請求」錯誤回應、系統資源超載及延遲增加的風險。 |
8.錯誤處理
需求 | 風險 | |
---|---|---|
增強的錯誤碼處理支援 | 適當處理增強型錯誤碼,並利用動作欄位來決定必要的修正步驟。 只有有限數目的增強型錯誤碼才應重試,而大多數需要其他解決方案,如動作欄位中所指定。 增強錯誤碼 — REST API V2檔案中所列的大多數增強錯誤碼,如果能在啟動應用程式之前的開發階段中正確處理,就可以完全避免。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 由於遺漏處理增強型錯誤碼,導致錯誤訊息不清楚、使用者指引不正確或遞補行為不正確,因此使用者端應用程式可能會發生故障。 |
HTTP錯誤處理支援 | 區別處理HTTP錯誤回應(例如400、401、403、404、405、500)和包含增強型錯誤代碼裝載的成功回應(例如200、201),如上所述。 只有有限數量的HTTP錯誤碼需要重試,而大多數需要替代解決方案。 如果在啟動應用程式之前,在開發階段處理正確,大部分的HTTP錯誤回應都可以完全避免。 | 可能會造成系統資源超載、延遲增加,以及可能觸發HTTP 429「太多請求」錯誤回應。 由於遺漏處理增強型錯誤碼,導致錯誤訊息不清楚、使用者指引不正確或遞補行為不正確,因此使用者端應用程式可能會發生故障。 |
9.測試
使用官方的Adobe Pass驗證非生產環境開發和測試應用程式:
- 前期生產
- Release-Staging
在啟動至發行生產之前,先在這些環境中執行徹底品質保證(QA)。
使用者端應用程式必須先在非生產環境中完成端對端驗證,才能進行發行生產。
缺少簡短且有效的偵錯路徑,可能會妨礙Adobe支援和工程部門快速介入。
建議作法
1.註冊階段
在重試原始請求之前,請確定用於處理HTTP 401「未獲授權」錯誤的任何重試機制都會先重新整理存取權杖。
2.設定階段
3.驗證階段
在呼叫/api/v2/authenticate API之前,驗證透過次要(第2個)應用程式(熒幕)上的使用者輸入所提交的驗證代碼,符合以下條件:
在次要(熒幕)應用程式內使用預先選取的mvpd執行的驗證
- 使用繼續驗證工作階段 - POST /api/v2/{serviceProvider}/sessions/{code}
- 利用擷取驗證工作階段 - GET /api/v2/{serviceProvider}/sessions/{code}
如果輸入的驗證代碼錯誤或驗證工作階段過期,使用者端應用程式會收到錯誤。
支援非基本流程,以備客戶應用程式業務需要:
- 存取流程效能降低(進階功能)
- 暫時存取流程(進階功能)
- 單一登入存取流程(標準功能)
4. (選擇性)預先授權階段
5.授權階段
6.登出階段
7.引數和標題
重複使用REST API v1的程式碼來呼叫DCR API以擷取存取權杖。
8.測試
確定已跨裝置和平台測試下列基本流程:
驗證流程
- 主要應用程式(熒幕)驗證案例
- 次要應用程式(熒幕)驗證案例
(選擇性)預先授權流程
- 測試允許決定案例
- 測試拒絕決定案例
授權流程
- 測試允許決定案例
- 測試拒絕決定案例
登出流程
此外,測試其他存取流程(如果適用):
- 存取流程效能降低(進階功能)
- 暫時存取流程(進階功能)
- 單一登入存取流程(標準功能)
涵蓋MVPD最上層的整合(涵蓋使用最廣泛的提供者)。
摘要
快取存取權杖
設定檔的快取部分
支援降級功能(若業務需求)
支援TempPass功能(若業務需求)
支援單一登入功能(若業務需求)
重試機制微調
重試機制微調
媒體權杖驗證,使用錯誤碼來增強使用者體驗
實作HTTP錯誤處理