REST API V2 チェックリスト

最終更新日： 2025年4月8日
重要
このページのコンテンツは情報提供のみを目的としています。 この API を使用するには、Adobeの最新ライセンスが必要です。 無許可の使用は許可されていません。

このドキュメントでは、Adobe Pass認証 REST API V2 を使用するクライアントアプリケーションを実装するプログラマー向けの必須要件と推奨事項を 1 か所にまとめています。

このドキュメントに従う必要があるのは、REST API V2 を実装する際に、受け入れ基準の一部と見なす必要があります。また、統合を成功させるために必要なすべての手順を実行するためのチェックリストとして使用する必要があります。

必須の要件

1.登録段階

要件危険
登録済みアプリケーションスコーピングREST API v2 スコープで登録済みアプリケーションを使用します。HTTP 401 「未認証」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスクがあります。
クライアント資格情報のキャッシュクライアント資格情報を永続ストレージに保存し、アクセストークン要求ごとに再利用します。クライアント資格情報を再生成する際に、認証が失われるリスクがあります。
アクセストークンのキャッシュアクセストークンを永続的なストレージに保存し、期限が切れるまで再利用します。

REST API v2 呼び出しごとに新しいトークンをリクエストしないでください。アクセストークンは期限切れになった場合にのみ更新します。		システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。

2.設定フェーズ

要件危険
設定の取得

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

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

  • ユーザーは既に認証済みです。
  • ユーザーには一時的なアクセスが提供されます。
  • ユーザー認証の有効期限が切れているが、以前に選択したMVPDの購読者であることを確認するプロンプトをユーザーに表示できます。
システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。
TV プロバイダー選択のキャッシュ

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

  • 設定応答ストアから、ユーザーが選択したMVPD「id」を保存します。
  • configuration response store から、ユーザーが選択したMVPD「displayName」を保存します。
  • Configuration response store から、ユーザーが選択したMVPD「logoUrl」を保存します。
システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。

3.認証フェーズ

要件危険
ポーリングメカニズムの開始

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

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

  • プライマリ（ストリーミング）アプリケーションでは、ブラウザーコンポーネントがセッションエンドポイントリクエストの「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」エラー応答がトリガーされる可能性があるリスクがあります。

4. （オプション）事前認証フェーズ

要件危険
事前承認決定の取得コンテンツのフィルタリングには事前認証の決定を使用し、再生の決定には使用しません。プログラマー、MVPD およびAdobe間の契約上の合意に違反するリスク。

監視および警告システムをバイパスするリスク。
事前承認決定の取得の再試行拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な是正手順を決定します。

再試行が必要な拡張エラーコードは限られていますが、ほとんどの場合、アクションフィールドで指定された代替解決策が必要です。

事前認証決定を取得するために実装された再試行メカニズムが無限ループを引き起こさず、再試行が適切な数（2-3 など）に制限されていることを確認します。		システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。
事前承認決定のキャッシュアプリケーション実行中のサブスクリプション更新の頻度が低いため、成功した許可決定をメモリにキャッシュして、パフォーマンスを向上させ、不要な REST API v2 呼び出しを最小限に抑えます。システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。

5.認証フェーズ

要件危険
承認決定の取得再生前に認証決定を取得 – 事前認証の決定が存在するかどうかに関係なく。

メディアトークンが再生中に期限切れになり、ユーザーが次の再生リクエストを行うときに（新規）メディアトークンを含む新しい認証決定をリクエストした場合でも、同じリソースまたは異なるリソースに対するものであっても、ストリームが中断されることなく続行することを許可します。

長時間実行されるライブストリームでは、コンテンツの一時停止、コマーシャルブレークの開始、MRSS の変更に伴うアセットレベルの設定の変更など、ビデオ操作に続いて、新しい承認決定をリクエストする場合があります。		プログラマー、MVPD およびAdobe間の契約上の合意に違反するリスク。

監視および警告システムをバイパスするリスク。
承認決定の取得の再試行拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な是正手順を決定します。

再試行が必要な拡張エラーコードは限られていますが、ほとんどの場合、アクションフィールドで指定された代替解決策が必要です。

認証決定を取得するために実装された再試行メカニズムが無限ループを引き起こさず、再試行が適切な数（2-3 など）に制限されていることを確認します。		システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。

6. ログアウトフェーズ

要件危険
ログアウトのサポート

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

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

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 のホームベース認証などの機能に必須です。
安定したデバイス識別子AP-Device-Identifier ヘッダーの更新やリブートを経ても変化しない、安定したデバイス識別子を計算して保存します。

ハードウェア ID のないプラットフォームの場合、アプリケーション属性から一意の ID を生成して保持します。		デバイス識別子が変更されると、認証が失われるリスクがあります。
API リファレンスに従うREST API v2 で想定されるパラメーターとヘッダーのみを送信していることを確認します。HTTP 400 「無効なリクエスト」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスク。

8. エラー処理

要件危険
エラーコード処理のサポートの強化拡張エラーコードを適切に処理し、アクションフィールドを利用して、必要な是正手順を決定します。

再試行が必要な拡張エラーコードは限られていますが、ほとんどの場合、アクションフィールドで指定された代替解決策が必要です。

拡張エラーコード - REST API V2 ドキュメントにリストされているほとんどの拡張エラーコードは、アプリケーションを起動する前の開発段階で正しく処理すれば、完全に防止できます。		システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。

拡張エラーコードの処理が欠落しているために、クライアントアプリケーションが誤動作するリスクがあります。その結果、不明なエラーメッセージが表示されたり、誤ったユーザーガイダンスが表示されたり、誤ったフォールバック動作が発生したりします。
HTTP エラー処理のサポート上記のように、HTTP エラー応答（400、401、403、404、405、500 など）の処理と、拡張エラーコードペイロードを含む成功応答（200、201 など）の処理を区別します。

再試行を保証するのは HTTP エラーコードの数が限られていますが、ほとんどの場合、別の解決策が必要です。

ほとんどの HTTP エラー応答は、アプリケーションを起動する前の開発フェーズで正しく処理すれば、完全に防ぐことができます。		システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。

拡張エラーコードの処理が欠落しているために、クライアントアプリケーションが誤動作するリスクがあります。その結果、不明なエラーメッセージが表示されたり、誤ったユーザーガイダンスが表示されたり、誤ったフォールバック動作が発生したりします。

9. テスト

要件危険
ライフサイクルテスト

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

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

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

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

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

短く効率的なデバッグパスがないと、Adobe サポートおよびエンジニアリングがすぐに介入できなくなる可能性があります。
プラクティス危険
アクセストークンの検証アクセストークンの有効期限が切れたときに、プロアクティブに有効性を確認して更新します。

HTTP 401 「未認証」エラーを処理する再試行メカニズムでは、最初にアクセストークンを更新してから元のリクエストを再試行するようにしてください。		HTTP 401 「未認証」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスクがあります。
プラクティス危険
設定のキャッシュパフォーマンスを向上させ、不要な REST API v2 呼び出しを最小限に抑えるために、設定応答をメモリまたは永続的なストレージに短期間（例：3～5 分）保存します。システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。
プラクティス危険
認証コードの検証（2 画面目の認証）

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

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

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

指定された認証コードが正しく入力されなかった場合、または認証セッションが期限切れになった場合、クライアントアプリケーションにエラーが発生します。

認証中に様々なエラー応答やワークフローの問題が発生するリスクがあります。
複数のプロファイルのサポートユーザーにプロファイルを選択するように促すか、有効期間が最も長いプロファイルを自動的に選択するなどのカスタムロジックを適用して、クライアントアプリケーションが複数のプロファイルを処理できるようにします。クライアントアプリケーション側のサポートが不足しているため、クライアントアプリケーションが誤動作するリスクがあります。
（任意）非基本フローのサポート

クライアントアプリケーションビジネスで必要とされる次のような場合に、非基本フローをサポートします。

  • アクセス・フローの低下（プレミアム機能）
  • 一時的なアクセスフロー（プレミアム機能）
  • シングルサインオンアクセスフロー（標準機能）
理想的でないユーザーエクスペリエンスを作成するリスクがあります。