REST API V2 クックブック（クライアントからサーバー） rest-api-v2-cookbook-client-to-server

クライアント資格情報の取得： ストリーミングアプリケーションは、/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 エンドポイントを呼び出して認証セッションを開始します。

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

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

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

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

特定のコードのプロファイルを取得： ストリーミングアプリケーションは、/api/v2/{serviceProvider}/profiles/code/{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} エンドポイントを呼び出して、特定のリソースの認証決定を取得します。

• ストリーミングアプリケーションは、認証決定を永続ストレージに保存するために必要ではありません。

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

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

• ストリーミングアプリケーションは、MVPD によって課せられる条件により、1 回の API リクエストで限られた数のリソースに対する認証決定を、通常は 1 つまで取得できます。

Adobe Pass ログアウトの開始： ストリーミングアプリケーションは、/api/v2/{serviceProvider}/logout/{mvpd} エンドポイントを呼び出して、ログアウトフローを開始します。

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

  • 応答の actionType 属性が「interactive」に設定されている場合：

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

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