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を作成して開くように求めるには、別の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 リクエストで限られた数のリソースに対して承認決定を取得できます（1件まで）。

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

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

  • 応答のactionType属性が「インタラクティブ」に設定されている場合：

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

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