REST API V2检查表 rest-api-v2-checklist

要求

风险

使用具有REST API v2作用域的注册应用程序。

可能会触发HTTP 401“未授权”错误响应，导致系统资源过载并增加延迟。

将客户端凭据存储在永久存储中，并在每个访问令牌请求中重复使用它们。

重新生成客户端凭据时，身份验证可能会丢失。

将访问令牌存储在永久存储中并重复使用，直到其过期。

不要为每个REST API v2调用请求新令牌，仅在访问令牌过期时才刷新访问令牌。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

要求

风险

只有在需要在身份验证阶段之前提示用户选择其MVPD（电视提供商）时，才检索配置响应。

在以下情况下，无需检索配置响应：

• 用户已经过身份验证。
• 授予用户临时访问权限。
• 用户身份验证已过期，但可以提示用户确认他们仍然是之前选择的MVPD的订阅者。

存在系统资源过载和延迟增加的风险。

将用户的付费电视提供商(MVPD)选择存储在永久存储中，以将其用于所有后续阶段：

• 从配置响应存储，用户选择MVPD“id”。
• 从配置响应存储中，用户选择MVPD “displayName”。
• 从配置响应存储，用户选择MVPD“logoUrl”。

存在系统资源过载和延迟增加的风险。

要求

风险

在以下条件下启动轮询机制：

在主（屏幕）应用程序内执行的身份验证

• 当浏览器组件加载了会话端点请求中为“redirectUrl”参数指定的URL后，当用户到达最终目标页面时，主（流）应用程序应开始轮询。

在辅助（屏幕）应用程序内执行的身份验证

• 主（流）应用程序应在用户启动身份验证过程后立即开始轮询 — 即在收到“会话”端点响应并向用户显示身份验证代码之后。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

在以下条件下停止轮询机制：

成功身份验证

• 成功检索用户的配置文件信息，确认其身份验证状态，因此不再需要轮询。

身份验证会话和代码过期

• 身份验证会话和代码到期，用户必须重新启动身份验证过程，使用以前的身份验证代码的轮询应立即停止。

已生成新的身份验证代码

• 如果用户请求新的身份验证代码，则现有会话将失效，使用以前的身份验证代码的轮询应立即停止。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

在以下条件下配置轮询机制频率：

在主（屏幕）应用程序内执行的身份验证

• 主（流）应用程序应每3-5秒或更长时间轮询一次。

在辅助（屏幕）应用程序内执行的身份验证

• 主（流）应用程序应每3-5秒轮询一次。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

将部分用户配置文件信息存储在永久存储中，以提高性能并最大程度地减少不必要的REST API v2调用。

缓存应侧重于以下配置文件响应字段：

mvpd

• 客户端应用程序可以使用此项来跟踪用户选择的电视提供商，并在预授权或授权阶段继续使用它。
• 当当前用户配置文件过期时，客户端应用程序可以使用记住的MVPD选择，只需请求用户进行确认。

属性

• 用于根据不同的用户元数据键（例如，zip、maxRating等）个性化用户体验。
• 用户元数据在验证流程完成后变为可用，因此客户端应用程序无需查询单独的端点即可检索用户元数据信息，因为它已包含在配置文件信息中。
• 某些元数据属性可能会在授权阶段更新，具体取决于MVPD（例如Charter）和特定的元数据属性（例如householdID）。 因此，客户端应用程序可能需要在授权后再次查询Profiles API以检索最新的用户元数据。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

要求

风险

将预授权决策用于内容过滤，从不用于播放决策。

违反程序员、MVPD和Adobe之间合同协议的风险。

绕过我们的监控和警报系统的风险。

正确处理增强的错误代码，并利用操作字段确定必要的修正步骤。

只有有限数量的增强型错误代码需要重试，而大多数需要操作字段中指定的替代分辨率。

请确保为检索预授权决策而实施的任何重试机制不会导致无休止循环，并且它会将重试限制为合理的数字（即2-3）。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

缓存成功允许在内存中进行决策，以提高性能并最大程度地减少不必要的REST API v2调用，因为应用程序运行时订阅更新并不频繁。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

要求

风险

在播放之前获取授权决策 — 无论是否存在预授权决策。

即使媒体令牌在播放期间过期，并允许流继续无中断运行，并在用户发出下次播放请求时请求包含（新增）媒体令牌的新授权决策，而不考虑它是针对同一资源还是其他资源。

长时间运行的实时流可以选择在视频操作后请求新的授权决策，例如在MRSS发生更改时暂停内容、启动商业中断或修改资产级配置。

违反程序员、MVPD和Adobe之间合同协议的风险。

绕过我们的监控和警报系统的风险。

正确处理增强的错误代码，并利用操作字段确定必要的修正步骤。

只有有限数量的增强型错误代码需要重试，而大多数需要操作字段中指定的替代分辨率。

请确保为检索授权决策而实施的任何重试机制不会导致无休止的循环，并且它将重试限制为合理的数字（即2-3）。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

要求

风险

实施注销API以允许用户手动注销，终止其已验证的配置文件，并遵循为每个已删除的配置文件指定的REST API v2操作名称：

• 对于支持注销端点的MVPD，客户端应用程序需要导航到用户代理中提供的“url”。
• 对于“appleSSO”类型配置文件，客户端应用程序需要引导用户也从合作伙伴级别（Apple的系统设置）注销。

由于缺少对客户端应用程序端的支持，导致客户端应用程序出现故障的风险。

要求

风险

为每个REST API v2请求发送授权标头。

可能会触发HTTP 401“未授权”错误响应，导致系统资源过载并增加延迟。

为每个REST API v2请求发送AP-Device-Identifier标头。

即使请求来自代表设备的服务器，AP-Device-Identifier标头值也必须反映实际的流设备标识符。

触发HTTP 400“错误请求”错误响应、系统资源过载和延迟增加的风险。

为每个REST API v2请求发送X-Device-Info标头。

即使请求来自代表设备的服务器，X-Device-Info标头值也必须反映实际的流设备信息。

风险被分类为源自未知平台并被视为不安全，因而会受更严格的规则的约束，如更短的身份验证TTL。

此外，某些字段，如流设备connectionIp和connectionPort，对于频谱的Home Base Authentication等功能是必需的。

计算并存储AP-Device-Identifier标头的稳定设备标识符，该标识符不会随着更新或重新启动而更改。

对于没有硬件标识符的平台，从应用程序属性生成唯一标识符并将其保留。

当设备标识符更改时，存在身份验证丢失的风险。

确保只发送REST API v2预期的参数和标头。

触发HTTP 400“错误请求”错误响应、系统资源过载和延迟增加的风险。

要求

风险

正确处理增强的错误代码，并利用操作字段确定必要的修正步骤。

只有有限数量的增强型错误代码需要重试，而大多数需要操作字段中指定的替代分辨率。

如果在启动应用程序之前的开发阶段进行了正确处理，增强型错误代码 — REST API V2文档中列出的大多数增强型错误代码都可以完全阻止。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

由于缺少处理增强的错误代码而导致客户端应用程序故障的风险 — 导致错误消息不明确、用户指导不正确或回退行为不正确。

区分处理HTTP错误响应（例如，400、401、403、404、405、500）和包含增强错误代码有效负载的成功响应（例如，200、201），如上所述。

只有有限数量的HTTP错误代码需要重试，而大多数需要替代解决方案。

如果在启动应用程序之前的开发阶段处理得当，大部分HTTP错误响应都可以完全阻止。

存在系统资源过载的风险，会增加延迟，并可能触发HTTP 429“请求过多”错误响应。

由于缺少处理增强的错误代码而导致客户端应用程序故障的风险 — 导致错误消息不明确、用户指导不正确或回退行为不正确。

要求

风险

使用官方的Adobe Pass身份验证非生产环境开发和测试应用程序：

• 前期生产
• Release-Staging

在启动到发布生产环境之前，在这些环境中执行彻底的质量保证(QA)。

客户端应用程序必须首先在非生产环境中完成端到端验证，才能进入发布生产环境。

带有严重和主要缺陷的风险启动。

缺少简短而有效的调试路径可能会阻碍Adobe支持和工程部门快速干预。

实践

风险

主动检查访问令牌的有效性，以在过期时刷新令牌。

在重试原始请求之前，请确保用于处理HTTP 401“未授权”错误的任何重试机制首先刷新访问令牌。

可能会触发HTTP 401“未授权”错误响应，导致系统资源过载并增加延迟。

实践

风险

将配置响应存储在内存或永久存储中较短时间（例如3-5分钟）以提高性能并最大程度地减少不必要的REST API v2调用。

存在系统资源过载和延迟增加的风险。

实践

风险

在以下条件下，在调用/api/v2/authenticate API之前，验证通过辅助(2)应用程序（屏幕）上的用户输入提交的身份验证代码：

在辅助（屏幕）应用程序内使用预先选择的mvpd执行的身份验证

• 使用恢复身份验证会话 - POST /api/v2/{serviceProvider}/sessions/{code}

在辅助（屏幕）应用程序中执行的身份验证，但未预先选择mvpd

• 使用检索身份验证会话 - GET /api/v2/{serviceProvider}/sessions/{code}

如果键入的身份验证代码错误或身份验证会话过期，客户端应用程序将收到错误。

在身份验证期间可能会出现各种错误响应和工作流问题。

通过提示用户选择配置文件或应用自定义逻辑（例如自动选择有效期最长的配置文件），确保客户端应用程序可以处理多个配置文件。

由于缺少对客户端应用程序端的支持，导致客户端应用程序出现故障的风险。

支持非基本流程，以防客户应用程序业务需要：

• 降级访问流（高级功能）
• 临时访问流程（高级功能）
• 单点登录访问流程（标准功能）

存在造成用户体验不理想的风险。

实践

风险

使用MVPD或Adobe通过增强错误代码提供的消息传递功能，在预授权决策被拒绝时显示清晰的用户反馈。

存在造成用户体验不理想的风险。

实践

风险

使用媒体令牌验证器库验证媒体令牌。

冒着串流欺诈等欺诈方案的风险。

使用MVPD或Adobe通过增强错误代码提供的消息传送功能，在授权决策被拒绝时显示清晰的用户反馈。

存在造成用户体验不理想的风险。

实践

风险

避免在预授权或授权被拒绝等情况下自动（以编程方式）调用注销API，因为注销API只应在响应直接用户请求时调用。

风险使用户误认为身份验证失败。

实践

风险

重用REST API v1中的代码计算设备标识符和设备信息，但请确保只发送REST API v2预期的参数和标头。

重用REST API v1中的代码来调用DCR API以检索访问令牌。

-

实践

风险

确保跨设备和平台测试以下基本流：

身份验证流

• 主应用程序（屏幕）身份验证方案
• 辅助应用程序（屏幕）身份验证方案

（可选）预授权流程

• 测试允许决策方案
• 测试拒绝决策方案

授权流

• 测试允许决策方案
• 测试拒绝决策方案

注销流

此外，测试其他访问流（如果适用）：

• 降级访问流（高级功能）
• 临时访问流程（高级功能）
• 单点登录访问流程（标准功能）

涵盖MVPD的顶部集成（涵盖最广泛使用的提供程序）。

在生产过程中存在无法预见的故障风险，尤其是在测试不太频繁的平台上或极少数流量出现负值情况时。

使用Adobe Developer网站。

-

阶段

必需

（强烈）推荐

缓存客户端凭据

缓存访问令牌

验证和刷新访问令牌

最大程度地减少配置响应检索

缓存配置响应

轮询机制微调

缓存部分配置文件

支持多个配置文件

支持降级功能（如果业务需要）

支持TempPass功能（如果业务需要）

支持单点登录功能（如果业务需要）

缓存允许预授权决定

重试机制微调

增强用户体验，为被拒绝的预授权决策使用错误代码

当用户请求播放

重试机制微调时检索授权决策

使用被拒绝的授权决定

媒体令牌验证的错误代码增强用户体验

实施注销API以允许用户手动注销

避免自动调用注销API

必需

（强烈）推荐

遵循必需的标头规范

重用REST API v1中的代码

实施增强的错误处理

实施HTTP错误处理

-