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

要件

危険

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

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

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

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

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

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

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

要件

危険

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

次の場合、設定応答を取得する必要はありません。

• ユーザーは既に認証済みです。
• ユーザーには一時的なアクセスが提供されます。
• ユーザー認証の有効期限が切れているが、以前に選択した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 を生成して保持します。

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

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 エラー処理を実装

-