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

要件

危険

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

HTTP 401 「未認証」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスクがあります。

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

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

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

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

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

要件

危険

認証段階の前にMVPD （TV プロバイダー）を選択するように促す必要がある場合にのみ、Configuration Response を取得します。

次の場合には、Configuration Response を取得する必要はありません。

• ユーザーは既に認証済みです。
• ユーザーには一時的なアクセスが提供されます。
• ユーザー認証の有効期限が切れているが、以前に選択したMVPDの購読者であることを確認するプロンプトをユーザーに表示できます。

システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。

ユーザーの有料テレビプロバイダー（MVPD）の選択内容を永続ストレージに保存して、以降のすべてのフェーズで使用できるようにします。

• 設定応答ストアから、ユーザーが選択したMVPD「id」を保存します。
• configuration response store から、ユーザーが選択したMVPD「displayName」を保存します。
• Configuration response store から、ユーザーが選択したMVPD「logoUrl」を保存します。

システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。

要件

危険

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

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

• プライマリ（ストリーミング）アプリケーションでは、ブラウザーコンポーネントがセッションエンドポイントリクエストの「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 など）に応じて、特定のメタデータ属性は認証フェーズ中に更新される場合があります。 その結果、最新のユーザーメタデータを取得するために、クライアントアプリケーションが認証後にプロファイル 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 「無効なリクエスト」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスク。

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

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

未知のプラットフォームからのリスクに分類され、安全でないと扱われ、認証 TTL の短縮など、より厳しいルールの対象となります。

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

AP-Device-Identifier ヘッダーに対して、更新やリブート後に変更されない安定したデバイス ID を計算して保存します。

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

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

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

HTTP 400 「無効なリクエスト」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスク。

要件

危険

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

拡張エラーコードの数が限られていれば、再試行が保証されますが、アクションフィールドで指定されている代替解決が必要なエラーコードはほとんどありません。

拡張エラーコード - 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認証非実稼動環境を使用して、アプリケーションを開発およびテストします。

• 前生産
• リリース – ステージング

リリース実稼動環境に移行する前に、これらの環境で徹底的な品質保証（QA）を実行します。

クライアントアプリケーションは、実稼動以外の環境でエンドツーエンドの検証を最初に完了することなく、リリース実稼動に進んではなりません。

重大な欠陥や重大な欠陥が発生するリスクがあります。

短く効率的なデバッグパスが欠けていると、Adobe サポートおよびエンジニアリング部門の迅速な介入が妨げられることがあります。

プラクティス

危険

アクセストークンの有効性をプロアクティブに確認し、有効期限が切れた場合に更新します。

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

HTTP 401 「未認証」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスクがあります。

プラクティス

危険

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

システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。

プラクティス

危険

セカンダリ（2 番目）アプリケーション（画面）でユーザー入力を通じて送信された認証コードを検証してから、次の条件で/api/v2/authenticate API を呼び出します。

セカンダリ（画面）アプリケーション内で実行される認証で、事前に選択された 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 で想定されるパラメーターとヘッダーのみです。

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

-

プラクティス

危険

デバイスとプラットフォームをまたいで、次の基本フローをテストします。

認証フロー

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

（任意）事前認証フロー

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

認証フロー

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

ログアウトフロー

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

• アクセス・フローの低下（プレミアム機能）
• 一時的なアクセスフロー（プレミアム機能）
• シングルサインオンアクセスフロー（標準機能）

上位のMVPD統合（最も広く使用されているプロバイダーをカバー）について説明します。

特にテスト頻度の低いプラットフォームや、ネガティブシナリオのような稀なフローでの実稼動環境で、予期しないエラーが発生するリスクがあります。

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

-

フェーズ

必須

（強く）推奨

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

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

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

設定応答の取得を最小限に抑える

キャッシュ設定応答

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

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

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

ビジネス要件の場合はサポートの最適化機能

ビジネス要件の場合はサポートの TempPass 機能

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

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

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

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

ユーザーが再生

再試行メカニズムの微調整をリクエストした場合に、認証決定を取得します

拒否された認証決定のエラーコードを使用してユーザーエクスペリエンスを向上

メディアトークンの検証

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

ログアウト API を自動的に呼び出さない

必須

（強く）推奨

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

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

拡張されたエラー処理を実装

HTTP エラー処理を実装

-