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

ストリーミングアプリの代理でAdobe Pass サービスと通信します。

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

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を作成して開くように求めるには、別のweb アプリケーションが必要です：/api/v2/authenticate/{serviceProvider}/{code}。

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

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

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

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

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

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

  • 認証に成功しました： ユーザーのプロファイル情報が正常に取得され、認証状態が確認されました。 この時点では、投票はもう必要ありません。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• プログラマーサービスは、認証済みユーザーに関する保存されている情報をクリーンアップする場合があります。

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

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

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

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