REST API V2 チェックリスト
- トピック:
- 認証
このドキュメントでは、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 プロバイダー)を選択するように促す必要がある場合にのみ、設定応答を取得します。
| システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。 |
TV プロバイダー選択のキャッシュ |
ユーザーの有料テレビプロバイダー(MVPD)の選択内容を永続ストレージに保存して、以降のすべてのフェーズで使用できるようにします。
| システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。 |
3.認証フェーズ
要件 | 危険 | |
---|---|---|
ポーリングメカニズムの開始 |
次の条件でポーリングメカニズムを起動します。
| システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。 |
ポーリングメカニズムの停止 |
次の条件でポーリングメカニズムを停止します。
認証セッションとコードの有効期限
新しい認証コードが生成されました
| システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。 |
ポーリングメカニズムの設定 |
次の条件でポーリングメカニズムの頻度を設定します。
| システムリソースを過負荷にし、待ち時間が増加し、HTTP 429 「Too Many Requests」エラー応答がトリガーされる可能性があるリスクがあります。 |
プロファイルのキャッシュ |
パフォーマンスを向上させ、不要な REST API v2 呼び出しを最小限に抑えるために、ユーザーのプロファイル情報の一部を永続ストレージに保存します。
属性
| システムリソースを過負荷にし、待ち時間が増加し、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 アクション名に従えるようにします。
| クライアントアプリケーション側のサポートが不足しているため、クライアントアプリケーションが誤動作するリスクがあります。 |
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 サポートおよびエンジニアリングがすぐに介入できなくなる可能性があります。 |
推奨プラクティス
1.登録段階
プラクティス | 危険 | |
---|---|---|
アクセストークンの検証 | アクセストークンの有効期限が切れたときに、プロアクティブに有効性を確認して更新します。 HTTP 401 「未認証」エラーを処理する再試行メカニズムでは、最初にアクセストークンを更新してから元のリクエストを再試行するようにしてください。 | HTTP 401 「未認証」エラー応答がトリガーされ、システムリソースが過負荷になり、待ち時間が長くなるリスクがあります。 |
2.設定フェーズ
プラクティス | 危険 | |
---|---|---|
設定のキャッシュ | パフォーマンスを向上させ、不要な REST API v2 呼び出しを最小限に抑えるために、設定応答をメモリまたは永続的なストレージに短期間(例:3~5 分)保存します。 | システムリソースを過負荷にして、待ち時間が長くなるリスクがあります。 |
3.認証フェーズ
プラクティス | 危険 | |
---|---|---|
認証コードの検証(2 画面目の認証) |
セカンダリ(2 番目)アプリケーション(画面)でユーザー入力を通じて送信された認証コードを検証してから、次の条件で/api/v2/authenticate API を呼び出します。
事前に選択された mvpd を使用せずに、セカンダリ(画面)アプリケーション内で認証を実行
指定された認証コードが正しく入力されなかった場合、または認証セッションが期限切れになった場合、クライアントアプリケーションにエラーが発生します。 | 認証中に様々なエラー応答やワークフローの問題が発生するリスクがあります。 |
複数のプロファイルのサポート | ユーザーにプロファイルを選択するように促すか、有効期間が最も長いプロファイルを自動的に選択するなどのカスタムロジックを適用して、クライアントアプリケーションが複数のプロファイルを処理できるようにします。 | クライアントアプリケーション側のサポートが不足しているため、クライアントアプリケーションが誤動作するリスクがあります。 |
(任意)非基本フローのサポート |
クライアントアプリケーションビジネスで必要とされる次のような場合に、非基本フローをサポートします。
| 理想的でないユーザーエクスペリエンスを作成するリスクがあります。 |
4. (オプション)事前認証フェーズ
プラクティス | 危険 | |
---|---|---|
ユーザーエクスペリエンス | MVPD またはAdobeが拡張エラーコードを介して提供するメッセージを使用して、事前認証の決定が拒否された場合に、明確なユーザーフィードバックを表示します。 | 理想的でないユーザーエクスペリエンスを作成するリスクがあります。 |
5.認証フェーズ
プラクティス | 危険 | |
---|---|---|
メディアトークンの検証 | メディアトークン検証ライブラリを使用してメディアトークンを検証します。 | ストリームリッピングなどの不正スキームをリスクにさらします。 |
ユーザーエクスペリエンス | MVPD またはAdobeが拡張エラーコードを介して提供するメッセージを使用して、認証の決定が拒否された場合に明確なユーザーフィードバックを表示します。 | 理想的でないユーザーエクスペリエンスを作成するリスクがあります。 |
6. ログアウトフェーズ
プラクティス | 危険 | |
---|---|---|
ユーザーエクスペリエンス | ログアウト API は直接ユーザーリクエストに応答してのみ呼び出す必要があるので、事前認証や承認が拒否されるなどのシナリオでは、(プログラム的に)ログアウト API の呼び出しを自動的に避けます。 | 認証が失敗すると、ユーザーが混乱するリスクがあります。 |
7. パラメーターとヘッダー
プラクティス | 危険 | |
---|---|---|
コードの再利用 | 軽微な調整を加えたデバイス識別子とデバイス情報の計算には REST API v1 のコードを再利用しますが、送信するのは REST API v2 で想定されるパラメーターとヘッダーのみにしてください。 DCR API を呼び出してアクセストークンを取得するために、REST API v1 のコードを再利用します | - |
8. テスト
プラクティス | 危険 | |
---|---|---|
テスト範囲 |
デバイスとプラットフォームをまたいで、次の基本フローをテストします。
(任意)事前認証フロー
認証フロー
ログアウトフロー
上位のMVPD統合(最も広く使用されているプロバイダーをカバー)について説明します。 | 特にテスト頻度の低いプラットフォームや、ネガティブシナリオのような稀なフローでの実稼動環境で、予期しないエラーが発生するリスクがあります。 |
テストツール | Adobe Developer の Web サイトを使用します。 | - |
概要
フェーズ | 必須 | (強く)推奨 |
---|---|---|
登録 | クライアント資格情報のキャッシュ アクセストークンのキャッシュ | アクセストークンの検証と更新 |
設定 | 設定応答の取得を最小限に抑える | キャッシュ設定応答 |
認証 | ポーリングメカニズムの微調整 プロファイルの一部をキャッシュする | 複数のプロファイルのサポート ビジネス要件の場合はサポートの最適化機能 ビジネス要件の場合はサポートの TempPass 機能 ビジネス要件の場合はシングルサインオン機能のサポート |
事前認証 | キャッシュ許可の事前認証決定 再試行メカニズムの微調整 | 拒否された事前承認の決定に対するエラーコードを使用してユーザーエクスペリエンスを向上 |
認証 | ユーザーが再生 再試行メカニズムの微調整をリクエストした場合に、認証決定を取得します | 拒否された認証決定のエラーコードを使用してユーザーエクスペリエンスを向上 メディアトークンの検証 |
ログアウト | ユーザーが手動でログアウトできるように、ログアウト API を実装します。 | ログアウト API を自動的に呼び出さない |
必須 | (強く)推奨 | |
パラメーターとヘッダー | 必須ヘッダーの仕様に従う | REST API v1 からのコードの再利用 |
エラー処理 | 拡張されたエラー処理を実装 HTTP エラー処理を実装 | - |