REST API V2 クックブック（サーバー間） rest-api-v2-cookbook-server-to-server

ストリーミングアプリに代わってAdobe Pass サービスと通信します。

AP-Device-Identifier ヘッダーで要求されるストリーミングデバイスの一意のデバイス識別子を収集して渡します。

X-Device-Info ヘッダーの要求に応じて、ソースポートやデバイス固有の詳細など、正確なストリーミングデバイス情報を収集して渡します。

X-Forwarded-For ヘッダーで必要とされるストリーミングデバイスの IP アドレスを収集して渡します。

デバイス ID、クライアント ID、クライアントシークレットなどのパラメーターは、ストリーミングアプリまたはプログラマーサービスのいずれかに安全に保存されます。

デバイス IP、ソース ポート、デバイス固有情報、MRSS、ECID などのオプション識別子など、MVPD および統合アプリケーションに準拠した形式でデータを送信します。

暗号化されたユーザーメタデータの送信のために、Adobeで共有される証明書を維持し、安全に管理します。

キャッシュ時に認証プロファイルと承認決定の有効性を考慮し、通知時に認証状態と承認状態が無効化されるようにします。

認証の決定と関連する指示をストリーミングアプリに返します。

Adobe Pass サービスは、米国全土に分散した複数のデータセンターで動作し、パフォーマンスを最適化し、待ち時間を最小限に抑えます。

• プログラマーサービスは、Adobe Passから低遅延の応答時間を確保するために、同様のインフラストラクチャ戦略を採用する必要があります。

プログラマーは、実稼動環境の公開 IP 範囲を指定する必要があります。

• これらの IP は、Adobe Pass インフラストラクチャ内の許可リストに追加されます。

プログラマーサービスは、データセンターが利用できなくなったことにより、Adobeでトラフィックのリダイレクトが必要になった場合に、動的な再ルーティングを可能にするために、DNS キャッシングを最大 30 秒に制限する必要があります。

実稼動環境にデプロイする前に、リリースのテストを許可する必要があります。

実際のテストが可能な限り、実稼動環境と同様の操作性を維持する必要があります。

ステージング環境は、次の目的でAdobe Pass テスト環境に接続するのが理想的です。

• プログラマーがAdobe インフラストラクチャに対してテストできるようにします。

• 必要に応じて、Adobeを有効にして、テストとトラブルシューティングを支援します。

クライアント資格情報の取得：プログラマーサービスは、/o/client/register エンドポイントを呼び出して、クライアント資格情報を取得します。

• プログラマーサービスまたはプログラマーアプリは、アクセストークンを取得する必要がある場合、クライアント資格情報を保存し、無期限に使用する必要があります。

アクセストークンの取得：プログラマーサービスは、/o/client/token エンドポイントを呼び出して、アクセストークンを取得します。

• プログラマーサービスまたはプログラマーアプリは、アクセストークンを期限切れになるまで保存して使用し、破棄して新しいアクセストークンを取得する必要があります。

プロファイルの取得： プログラマーサービスは、/api/v2/{serviceProvider}/profiles エンドポイントを呼び出すことにより、ストリーミングアプリの代わりに既存のプロファイルを確認します。

シナリオ 1: 既存のプロファイルがあり、プログラマーサービスが 事前認証フェーズまたは 認証フェーズに進む場合があります。

シナリオ 2: 既存のプロファイルがありません。プログラマーサービスは、次の手順に進んで ユーザーの認証を行う場合があります。

シナリオ 3: 既存のプロファイルがありません。プログラマーサービスは、TempPass 機能を通じてユーザーに一時的なアクセスを提供する場合があります。

• このシナリオはこのドキュメントの範囲外です。詳しくは、 一時的なアクセスフローのドキュメントを参照してください。

設定の取得： プログラマーサービスは、/api/v2/{serviceProvider}/configuration エンドポイントを呼び出して、使用可能な MVPD のリストを取得します。

• プログラマーサービスは、カスタムフィルタリングメカニズムを実装して、設定応答から MVPD のリストを絞り込むことができます。これにより、ストリーミングアプリは対象のプロバイダーのみを表示し、それ以外のプロバイダー（開発中の MVPD、テスト MVPD、TempPass など）は非表示にします。 これにより、テレビプロバイダーを選択する際に、厳選された選択肢がユーザーに表示されます。

認証セッションの作成： プログラマーサービスは、/api/v2/{serviceProvider}/sessions エンドポイントを呼び出して認証セッションを開始します。

• プログラマーサービスは、code と url をストリーミングアプリに返す必要があります。

シナリオ 1: ストリーミングアプリは、ブラウザーまたは web ビューを開くことができるので、認証 url ールを読み込む必要があります。

• ユーザーは、MVPDのログインページ内でユーザー名とパスワードを送信します。 認証が成功すると、最終的なリダイレクトに成功ページが表示されます。

シナリオ 2: ストリーミングアプリはブラウザーを開くことができないので、認証 code ールを表示する必要があります。 ユーザーに code を入力し、認証 url を作成して /api/v2/authenticate/{serviceProvider}/{code} を開くよう促すには、別の web アプリケーションが必要です。

• ユーザーは、MVPDのログインページ内でユーザー名とパスワードを送信します。 認証が成功すると、最終的なリダイレクトに成功ページが表示されます。

特定のコードのプロファイルを取得： プログラマーサービスは、code を使用してポーリングメカニズムを実装し、/api/v2/{serviceProvider}/profiles/code/{code} エンドポイントを呼び出して、プロファイルが正常に生成され保存されたかどうかを確認する必要があります。

• プログラマーサービスは、次の条件下で ポーリングを開始 する必要があります。

  • プライマリ（画面）アプリケーション内で実行される認証： ブラウザーコンポーネントが セッションエンドポイントリクエストの redirectUrl パラメーターに指定された URL を読み込んだ後、ユーザーが最終的な宛先ページに到達すると、プログラマーサービスはポーリングを開始する必要があります。

  • セカンダリ（画面）アプリケーション内で実行される認証： プログラマーサービスアプリケーションは、ユーザーが認証プロセスを開始するとすぐに（ セッションエンドポイント応答を受信し、認証コードをユーザーに表示した直後に）、ポーリングを開始する必要があります。

• プログラマーサービスは、次の条件下で ポーリングを停止 する必要があります。

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

  • 認証セッションとコードの有効期限： 認証セッションとコードの有効期限が切れます。これは、 セッションエンドポイント応答の notAfter タイムスタンプ （例：30 分）に示されています。 この場合、ユーザーは認証プロセスを再起動する必要があり、以前の認証コードを使用したポーリングは直ちに停止する必要があります。

  • 生成された新しい認証コード： ユーザーがプライマリ（画面）デバイスで新しい認証コードを要求すると、既存のセッションは無効になり、以前の認証コードを使用したポーリングを直ちに停止する必要があります。

• プログラマーサービスは、次の条件下で ポーリングを設定 メカニズムの頻度を設定する必要があります。

  • プライマリ（画面）アプリケーション内で実行される認証： プログラマーサービスは、3 ～ 5 秒ごとにポーリングする必要があります。

  • セカンダリ（画面）アプリケーション内で実行される認証： プログラマーサービスは、3 ～ 5 秒ごとにポーリングする必要があります。

• プログラマーサービスは、不要なリクエストを避け、ユーザーエクスペリエンスを向上させるために、ユーザーのプロファイル情報の一部を永続的なストレージにキャッシュする必要があります。

事前認証決定の取得： プログラマーサービスは、/api/v2/{serviceProvider}/decisions/preauthorize/{mvpd} エンドポイントを呼び出して、リソースのリストの事前認証決定を取得します。

• プログラマーサービスは、許可および拒否の事前承認決定のリストをストリーミングアプリに渡す必要があります。

• プログラマーサービスは、永続的なストレージに事前認証の決定を保存する必要はありません。 ただし、ユーザーエクスペリエンスを向上させるために、許可決定をメモリにキャッシュすることをお勧めします。 これにより、事前に承認されたリソースに対する不要な呼び出しを回避し、待ち時間を短縮し、パフォーマンスを向上させることができます。

• プログラマーサービスは、決定の事前承認エンドポイントからの応答に含まれる エラーコードとメッセージを調べることで、拒否された事前承認の決定の理由を判断できます。 これらの詳細は、事前認証リクエストが拒否された具体的な理由に関するインサイトを提供し、アプリケーションでの必要な処理をユーザーエクスペリエンスやトリガーに知らせるのに役立ちます。 事前認証の決定を取得するために実装された再試行メカニズムが、事前認証の決定が拒否された場合に無限ループが発生しないことを確認します。 再試行を適切な数に制限し、ユーザーに明確なフィードバックを表示して、拒否を適切に処理することを検討してください。

• プログラマーサービスは、MVPD によって課された条件により、1 回の API リクエストで、通常は 5 回まで、限られた数のリソースに対して事前認証の決定を取得できます。 この最大数のリソースは、組織の管理者の 1 人がAdobe Pass TVE ダッシュボードを通じて、またはお客様に代わってAdobe Pass認証担当者が MVPD に同意した後に表示および変更できます。

認証決定の取得： プログラマーサービスは、/api/v2/{serviceProvider}/decision/authorize/{mvpd} エンドポイントを呼び出して、ストリーミングアプリによって渡される特定のリソースの認証決定を取得します。

• プログラマーサービスは、認証決定を永続的なストレージに保存する必要はありません。

• プログラマーサービスは、決定を承認エンドポイントからの応答に含まれている エラーコードとメッセージを調べることで、拒否された承認決定の理由を判断できます。 これらの詳細は、認証リクエストが拒否された具体的な理由をinsightに提供し、ストリーミングアプリでの必要な処理をユーザーエクスペリエンスやトリガーに伝えるのに役立ちます。 認証決定を取得するために実装された再試行メカニズムが、認証決定が拒否された場合に無限ループが発生しないことを確認します。 再試行を適切な数に制限し、ユーザーに明確なフィードバックを表示して、拒否を適切に処理することを検討してください。

• プログラマーサービスは、他のビジネスルールを評価し、ストリーミングアプリに適切な承認決定を返す場合があります。

• ストリームのアクティブ再生中に期限切れのメディアトークンを更新する場合、プログラマーサービスは必要ありません。 再生中にメディアトークンの有効期限が切れた場合、ストリームが中断されることなく続行されるようにしてください。 ただし、次回ユーザーがリソースを再生しようとすると、クライアントは新しい認証決定をリクエストし、新しいメディアトークンを取得する必要があります。

• プログラマーサービスは、MVPD によって課された条件により、1 回の API リクエストで限られた数のリソースに対して、通常は 1 つまでの承認決定を取得できます。

Adobe Pass ログアウトの開始：プログラマーサービスは、/api/v2/{serviceProvider}/logout/{mvpd} エンドポイントを呼び出して、ストリーミングアプリからリクエストされたログアウトフローを開始します。

• プログラマーサービスは、認証済みユーザーに関する情報を保存している場合、その情報をクリーンアップすることができます。

• プログラマーサービスは、ログアウトプロセスが正しく完了するように、ログアウトエンドポイント応答の actionName 属性と actionType 属性に記載されている手順に従う必要があります。

  • 応答の actionType 属性が「interactive」に設定されている場合、プログラマーサービスは url 属性値をストリーミングアプリに返す必要があります。

    • シナリオ 1: ストリーミングアプリは、ブラウザーまたは web ビューを開くことができるので、ログアウト url を読み込む必要があります。

    • シナリオ 2: ストリーミングアプリでブラウザーを開くことができないので、MVPD セッションがストリーミングデバイスブラウザーのキャッシュに保持されていなかったので、ログアウトプロセスを停止できます。