REST API V2 チェックリスト rest-api-v2-checklist

要件定義

リスク

REST API v2 スコープで登録済みアプリケーションを使用します。

HTTP 401 「不正な」エラー応答をトリガーするリスク、システムリソースの過負荷、および遅延の増加。

クライアント資格情報を永続的なストレージに保存し、アクセストークン要求ごとに再利用します。

クライアント資格情報が再生成されると、認証が失われるリスクがあります。

永続的なストレージにアクセストークンを保存し、有効期限が切れるまで再利用します。

REST API v2呼び出しごとに新しいトークンをリクエストしないでください。アクセストークンは、有効期限が切れた場合にのみ更新してください。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

要件定義

リスク

認証フェーズの前にMVPD （TV プロバイダー）の選択を促す必要がある場合にのみ、コンフィギュレーション応答を取得します。

次の場合は、コンフィギュレーション応答を取得する必要はありません。

• ユーザーは既に認証されています。
• ユーザーには一時的なアクセス権が付与されます。
• ユーザー認証の有効期限が切れましたが、以前に選択したMVPDのサブスクライバーであることを確認するように求められます。

システムリソースが過負荷になり、遅延が増大するリスクがあります。

ユーザーの有料TV プロバイダー（MVPD）の選択内容を永続的なストレージに保存し、その後のすべてのフェーズで使用します。

• 設定レスポンスから、ユーザーが選択したMVPDの「ID」を保存します。
• コンフィギュレーションレスポンスから、ユーザーが選択したMVPDの「displayName」を保存します。
• 設定レスポンスから、ユーザーが選択したMVPDの「logoUrl」を保存します。

システムリソースが過負荷になり、遅延が増大するリスクがあります。

要件定義

リスク

次の条件でポーリングメカニズムを開始します。

プライマリ（画面）アプリケーション内で実行された認証

• プライマリ（ストリーミング）アプリケーションは、ユーザーコンポーネントがSessions エンドポイントリクエストの「redirectUrl」パラメーターに指定されたURLを読み込んだ後、最終宛先ページに到達したときにポーリングを開始する必要があります。

セカンダリ （画面） アプリケーション内で実行された認証

• プライマリ（ストリーミング）アプリケーションは、ユーザーが認証プロセスを開始するとすぐにポーリングを開始する必要があります（セッションエンドポイント応答を受信し、ユーザーに認証コードを表示した直後）。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

次の条件でポーリングメカニズムを停止します。

認証に成功

• ユーザーのプロファイル情報が正常に取得され、認証ステータスが確認されるため、ポーリングは不要になります。

認証セッションとコードの有効期限

• 認証セッションとコードが期限切れになると、ユーザーは認証プロセスを再起動する必要があり、以前の認証コードを使用したポーリングはすぐに停止する必要があります。

新しい認証コードが生成されました

• ユーザーが新しい認証コードを要求した場合、既存のセッションは無効になり、以前の認証コードを使用したポーリングはすぐに停止する必要があります。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

次の条件でポーリングメカニズムの頻度を設定します。

プライマリ（画面）アプリケーション内で実行される認証

• プライマリ（ストリーミング）アプリケーションは、3～5秒以上ごとにポーリングする必要があります。

セカンダリ （画面） アプリケーション内で実行された認証

• プライマリ（ストリーミング）アプリケーションは、3～5秒ごとにポーリングする必要があります。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

ユーザーのプロファイル情報の一部を永続的なストレージに保存し、パフォーマンスを向上させ、不要なREST API v2呼び出しを最小限に抑えます。

キャッシュでは、次のプロファイル応答フィールドに焦点を当てる必要があります：

mvpd

• クライアントアプリケーションはこれを使用して、ユーザーが選択したテレビプロバイダーを追跡し、事前認証フェーズまたは承認フェーズでさらに使用し続けることができます。
• 現在のユーザープロファイルが期限切れになると、クライアントアプリケーションは記憶されたMVPDの選択範囲を使用し、ユーザーに確認を依頼することができます。

属性

• 様々なユーザーメタデータキー（zip、maxRatingなど）に基づいてユーザーエクスペリエンスをパーソナライズするために使用されます。
• 認証フローが完了すると、ユーザーメタデータが使用できるようになります。そのため、クライアントアプリケーションは、プロファイル情報に既に含まれているため、ユーザーメタデータ情報を取得するために別のエンドポイントをクエリする必要はありません。
• 特定のメタデータ属性は、MVPD（Charterなど）および特定のメタデータ属性（householdIDなど）に応じて、承認フェーズ中に更新される場合があります。 その結果、クライアントアプリケーションは、最新のユーザーメタデータを取得するために、認証後にProfiles APIを再度クエリする必要がある場合があります。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

要件定義

リスク

コンテンツのフィルタリングには事前承認決定を使用し、再生決定には絶対に使用しない。

プログラマー、MVPD、Adobe間の契約上の合意に違反するリスク。

監視および警告システムを回避するリスク。

拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な修復手順を決定します。

一部の強化されたエラーコードのみが再試行を許可しますが、ほとんどの場合、アクション フィールドで指定された代替解決策が必要です。

事前認証の決定を取得するために実装された再試行メカニズムが無限ループにならないこと、および再試行を合理的な数（2-3）に制限することを確認します。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

アプリケーションの実行中にサブスクリプションが更新される頻度が低いため、メモリに許可に関する決定をキャッシュして、パフォーマンスを向上させ、不要なREST API v2呼び出しを最小限に抑えます。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

要件定義

リスク

事前認証の決定が存在するかどうかに関係なく、再生前に認証の決定を取得します。

再生中にメディアトークンが期限切れになった場合でも、ストリームを中断せずに続行できるようにし、ユーザーが次の再生リクエストを行う際に、同じリソースまたは別のリソースに関わらず、（新鮮な）メディアトークンを含む新しい承認決定をリクエストします。

長時間のライブストリームを実行している場合、コンテンツの一時停止、商用利用の開始、MRSSの変更時のアセットレベル設定の変更などのビデオ操作に従って、新しい承認決定をリクエストできます。

プログラマー、MVPD、Adobe間の契約上の合意に違反するリスク。

監視および警告システムを回避するリスク。

拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な修復手順を決定します。

一部の強化されたエラーコードのみが再試行を許可しますが、ほとんどの場合、アクション フィールドで指定された代替解決策が必要です。

認証の決定を取得するために実装された再試行メカニズムが無限ループにならないこと、および再試行を合理的な数（2-3）に制限することを確認します。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

要件定義

リスク

ログアウト APIを実装して、ユーザーが手動でログアウトし、認証済みプロファイルを終了し、削除された各プロファイルに指定されたREST API v2 アクション名に従えるようにします。

• ログアウトエンドポイントをサポートするMVPDの場合、クライアントアプリケーションはユーザーエージェントで指定された「URL」に移動する必要があります。
• 「appleSSO」タイプのプロファイルの場合、クライアントアプリケーションは、パートナーレベル（Appleのシステム設定）からもログアウトするようにユーザーをガイドする必要があります。

クライアントアプリケーション側でサポートが欠落しているため、クライアントアプリケーションが誤動作するリスクがあります。

要件定義

リスク

REST API v2 リクエストごとにAuthorization ヘッダーを送信します。

HTTP 401 「不正な」エラー応答をトリガーするリスク、システムリソースの過負荷、および遅延の増加。

REST API v2 リクエストごとにAP-Device-Identifier ヘッダーを送信します。

リクエストがデバイスの代理でサーバーから送信された場合でも、AP-Device-Identifier ヘッダー値は実際のストリーミングデバイス識別子を反映する必要があります。

HTTP 400 「Bad Request」エラー応答のトリガー、システムリソースの過負荷、遅延の増加のリスクがあります。

REST API v2 リクエストごとにX-Device-Info ヘッダーを送信します。

リクエストがデバイスの代理でサーバーから送信された場合でも、X-Device-Info ヘッダー値は実際のストリーミングデバイス情報を反映する必要があります。

未知のプラットフォームから送信されたものとして分類され、安全でない扱いになり、認証TTLの短縮など、より制限の厳しいルールの対象となるリスク。

さらに、ストリーミングデバイス connectionIpやconnectionPortなどの一部のフィールドは、Spectrumのホームベース認証などの機能に必須です。

AP-Device-Identifier ヘッダーの更新または再起動時に変更されない安定したデバイス IDを計算して保存します。

ハードウェア IDのないプラットフォームの場合は、アプリケーション属性から一意のIDを生成して保持します。

デバイス IDが変更されると、認証が失われるリスクがあります。

REST API v2の想定されるパラメーターとヘッダーのみを送信していることを確認します。

HTTP 400 「Bad Request」エラー応答のトリガー、システムリソースの過負荷、遅延の増加のリスクがあります。

要件定義

リスク

拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な修復手順を決定します。

一部の強化されたエラーコードのみが再試行を許可しますが、ほとんどの場合、アクション フィールドで指定された代替解決策が必要です。

拡張エラーコード - REST API V2 ドキュメントに記載されている最も強化されたエラーコードは、アプリケーションを起動する前に開発フェーズで正しく処理された場合、完全に防ぐことができます。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

拡張エラーコードの処理が見つからないため、クライアントアプリケーションが誤動作するリスクがあります。不明確なエラーメッセージ、不適切なユーザーガイダンス、誤ったフォールバック動作が発生します。

HTTP エラー応答（例：400、401、403、404、405、500）の処理と、前述のように、拡張エラーコードペイロードを含む成功レスポンス（例：200、201）の処理を区別します。

再試行が必要なHTTP エラーコードは限られていますが、ほとんどの場合は代替解決策が必要です。

アプリケーションを起動する前に開発段階で正しく処理すれば、ほとんどのHTTP エラー応答を完全に防ぐことができます。

システムリソースが過負荷になり、遅延が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があります。

拡張エラーコードの処理が見つからないため、クライアントアプリケーションが誤動作するリスクがあります。不明確なエラーメッセージ、不適切なユーザーガイダンス、誤ったフォールバック動作が発生します。

要件定義

リスク

Adobe Pass認証の公式な非実稼働環境を使用して、アプリケーションを開発およびテストします。

• Prequal-Production
• リリースステージング

これらの環境で完全な品質保証（QA）を実行してから、Release-Productionに起動してください。

クライアントアプリケーションは、非実稼動環境でエンドツーエンドの検証を最初に完了せずにRelease-Productionに進んではなりません。

重大な欠陥や大きな欠陥によって立ち上がるリスク：

短く効率的なデバッグパスを欠くと、Adobe サポートとエンジニアリングが迅速に介入する妨げになる可能性があります。

慣行

リスク

アクセストークンの有効性を先見的に確認し、有効期限が切れたときに更新します。

HTTP 401 「未承認」エラーを処理するための再試行メカニズムでは、最初に元のリクエストを再試行する前に、アクセストークンが更新されていることを確認します。

HTTP 401 「不正な」エラー応答をトリガーするリスク、システムリソースの過負荷、および遅延の増加。

慣行

リスク

設定レスポンスをメモリまたは永続的なストレージに短期間（3～5分など）保存することで、パフォーマンスを向上させ、不要なREST API v2呼び出しを最小限に抑えます。

システムリソースが過負荷になり、遅延が増大するリスクがあります。

慣行

リスク

次の条件で/api/v2/authenticate APIを呼び出す前に、セカンダリ （2nd） アプリケーション （screen）でユーザー入力を介して送信された認証コードを検証します。

事前選択されたmvpdを使用して、セカンダリ （screen） アプリケーション内で実行された認証

• 認証セッションを再開 - POST /api/v2/{serviceProvider}/sessions/{code}を使用します

事前に選択されたmvpdを使用せずに、セカンダリ（画面）アプリケーション内で認証が実行されました

• 認証セッションを取得 - GET /api/v2/{serviceProvider}/sessions/{code}を使用します

提供された認証コードが間違って入力された場合、または認証セッションが期限切れになった場合、クライアントアプリケーションはエラーを受け取ります。

認証中に様々なエラー応答やワークフローの問題が発生するリスクがあります。

クライアントアプリケーションが、ユーザーにプロファイルの選択を促したり、最も長い有効期間を持つプロファイルを自動的に選択するなど、カスタムロジックを適用したりすることで、複数のプロファイルを処理できるようにします。

クライアントアプリケーション側でサポートが欠落しているため、クライアントアプリケーションが誤動作するリスクがあります。

クライアントアプリケーションビジネスで必要な場合に備えて、非基本フローをサポートします。

• 劣化したアクセスフロー（プレミアム機能）
• 一時的なアクセスフロー（プレミアム機能）
• シングルサインオンアクセスフロー（標準機能）

理想的でないユーザーエクスペリエンスを生み出すリスクがあります。

慣行

リスク

MVPDまたはAdobeから提供されるメッセージを拡張エラーコードで使用し、事前認証の決定が拒否された場合に、明確なユーザーフィードバックを表示します。

理想的でないユーザーエクスペリエンスを生み出すリスクがあります。

慣行

リスク

Media Token Verifier ライブラリを使用してメディアトークンを検証します。

ストリームリッピングなどの不正行為のリスクを抱える。

MVPDまたはAdobeから提供されたメッセージを拡張エラーコードで使用し、認証の決定が拒否された場合に、明確なユーザーフィードバックを表示します。

理想的でないユーザーエクスペリエンスを生み出すリスクがあります。

慣行

リスク

ログアウト APIは直接のユーザーリクエストに応じてのみ呼び出す必要があるため、拒否された事前認証や認証などのシナリオでは、ログアウト APIを自動的に（プログラムによって）呼び出さないようにします。

認証が失敗していることをユーザーを混乱させるリスクがあります。

慣行

リスク

REST API v1のコードを再利用して、デバイス識別子とデバイス情報を少し調整して計算します。ただし、REST API v2で想定されるパラメーターとヘッダーのみを送信するようにしてください。

REST API v1のコードを再利用して、DCR APIを呼び出し、アクセストークンを取得します。

-

慣行

リスク

デバイスとプラットフォーム間で、次の基本フローがテストされていることを確認します。

認証フロー

• プライマリアプリ（画面）の認証シナリオ
• セカンダリアプリ（画面）認証のシナリオ

（オプション）事前認証フロー

• 許可の決定シナリオのテスト
• テスト拒否の決定シナリオ

承認フロー

• 許可の決定シナリオのテスト
• テスト拒否の決定シナリオ

ログアウトフロー

さらに、他のアクセスフローをテストします（該当する場合）:

• 劣化したアクセスフロー（プレミアム機能）
• 一時的なアクセスフロー（プレミアム機能）
• シングルサインオンアクセスフロー（標準機能）

Adobe MVPDとの主要な統合（最も広く使用されているプロバイダーを含む）について説明します。

頻繁にテストされていないプラットフォームや、ネガティブなシナリオのようなまれなフローにおいて、本番環境で予期せぬ失敗が発生するリスクが高まります。

Adobe Developer web サイトを使用します。

-

フェーズ

必須

（強く）推奨

クライアント資格情報をキャッシュ

アクセス トークンをキャッシュ

アクセストークンの検証と更新

設定応答の取得を最小化

キャッシュ設定の応答

ポーリングメカニズムの微調整

プロファイルの一部をキャッシュ

複数のプロファイルをサポート

サポートのデグラデーション機能（ビジネス要件の場合）

TempPass機能（ビジネス要件の場合）

シングルサインオン機能（ビジネス要件の場合）をサポート

キャッシュ許可の事前承認決定

メカニズムの微調整を再試行する

拒否された事前認証の決定にエラーコードを使用することで、ユーザーエクスペリエンスを向上させます

ユーザーが再生を要求したときに承認決定を取得する

メカニズムの微調整を再試行する

拒否された承認決定にエラーコードを使用して、ユーザーエクスペリエンスを向上させる

メディアトークンの検証

ユーザーが手動でログアウトできるようにログアウト APIを実装する

ログアウト APIの自動呼び出しを避ける

必須

（強く）推奨

必須のヘッダーの仕様に従う

REST API v1からのコードの再利用

強化されたエラー処理の実装

HTTP エラー処理の実装

-