埋め込みトークンを生成する

  • [アーティクル]

適用対象: アプリ所有データ ユーザー所有データ

トークンの生成は、Web アプリまたはポータルに Power BI レポートまたはセマンティック モデルを埋め込むためのトークンを生成できる REST API です。 1 つの項目または複数のレポートやセマンティック モデルのトークンを生成できます。 トークンは、Power BI サービスに対する要求を承認するために使用されます。

トークンの生成 API により、アプリでのユーザーの資格情報 (有効な ID) に応じて、1 つの ID (マスター ユーザーまたはサービス プリンシパル) を使用して、個々のユーザーのトークンが生成されます。

認証が成功すると、関連データへのアクセスが許可されます。

Note

トークンの生成は、レポートとセマンティック モデルの両方、および単一または複数の項目に対して機能する、新しいバージョン 2 の API です。 従来のバージョン 1 の API よりも優先されます。 ダッシュボードとタイルの場合は、V1 Dashboards GenerateTokenInGroup と Tiles GenerateTokenInGroup を使用します。

データのセキュリティ保護

複数のお客様のデータを扱っている場合、データをセキュリティで保護する 2 つの主なアプローチ (''ワークスペースベースの分離'' と ''行レベルのセキュリティベースの分離'') があります。 それらの詳細な比較は、サービス プリンシパル プロファイルと行レベルのセキュリティに関する説明で確認できます。

プロファイルではワークスペースベースの分離を使用することをお勧めしますが、RLS アプローチを使用する場合は、この記事の末尾の RLS に関するセクションを確認してください。

トークンの許可とセキュリティ

トークンの生成 API の GenerateTokenRequest セクションで、トークンのアクセス許可を記述します。

アクセス レベル

  • allowEdit パラメーターを使って、ユーザーに表示または編集のアクセス許可を付与します。

  • ワークスペース ID を埋め込みトークンに追加して、ユーザーがそのワークスペースに新しいレポートを作成できるようにします (SaveAs または CreateNew のいずれか)。

行レベルのセキュリティ

行レベル セキュリティ (RLS) では、トークンの生成に使用しているサービス プリンシパルまたはマスター ユーザーの ID とは異なる ID を使用できます。 異なる ID を使用することで、埋め込まれた情報を対象ユーザーに応じて表示できます。 たとえば、アプリケーションでユーザーにサインインを要求し、サインインしているユーザーが販売従業員である場合、販売情報のみが含まれるレポートを表示することができます。

RLS を使用している場合、状況によってはユーザーの ID (EffectiveIdentity パラメーター) を省略することができます。 EffectiveIdentity パラメーターを使用しない場合は、トークンを使用するとデータベース全体にアクセスできます。 この方法を使用すると、セマンティック モデル全体を表示するアクセス許可を持つ管理者やマネージャーなどのユーザーにアクセス権を付与できます。 ただし、すべてのシナリオでこの方法を使用することはできません。 次の表では、さまざまな RLS の種類と、ユーザーの ID を指定せずに使用できる認証方法を示します。

また、表には、各 RLS の種類に適用される考慮事項と制限も示されています。

RLS の種類 有効なユーザー ID を指定せずに埋め込みトークンを生成できるか? 考慮事項と制限事項
クラウド行レベル セキュリティ (クラウド RLS) ✔ マスター ユーザー
✖ サービス プリンシパル
RDL (ページ分割されたレポート) ✖ マスター ユーザー
✔ サービス プリンシパル		 マスター ユーザーを使用して RDL 用の埋め込みトークンを生成することはできません。
Analysis Services (AS) のオンプレミス ライブ接続 ✔ マスター ユーザー
✖ サービス プリンシパル		 埋め込みトークンを生成するユーザーには、次のいずれかのアクセス許可も必要です。
  • ゲートウェイ管理者のアクセス許可
  • データソース借用のアクセス許可 (ReadOverrideEffectiveIdentity)
    		•
    Analysis Services (AS) の Azure ライブ接続 ✔ マスター ユーザー
    ✖ サービス プリンシパル    		 埋め込みトークンを生成するユーザーの ID を、オーバーライドすることはできません。 カスタム データを使用して、動的な RLS またはセキュリティで保護されたフィルター処理を実装できます。

    注: サービス プリンシパルは、有効な ID (RLS ユーザー名) としてそのオブジェクト ID を提供する必要があります。
    シングル サインオン (SSO) ✔ マスター ユーザー
    ✖ サービス プリンシパル    		 明示的な (SSO) ID を、有効な ID オブジェクトの ID BLOB プロパティを使用して提供できます
    SSO とクラウド RLS ✔ マスター ユーザー
    ✖ サービス プリンシパル    		 次のものを指定する必要があります。
  • 有効な ID オブジェクトの ID BLOB プロパティの明示的な (SSO) ID
  • 有効な (RLS) ID (ユーザー名)
    		•

    注意

    サービス プリンシパルでは常に次の情報を提供する必要があります。

    • RLS セマンティック モデルでの任意の項目に対する ID。
    • SSO セマンティック モデルの場合、コンテキスト (SSO) ID が定義されている有効な RLS ID。

    Power BI セマンティック モデルの DirectQuery

    直接クエリ接続が設定されたセマンティック モデルがある Power BI レポートを別の Power BI セマンティック モデルに埋め込むには、次のようにします。

    有効期限が切れる前にトークンを更新する

    トークンには時間制限があります。 これは、Power BI 項目を埋め込んだ後、操作する時間が限られていることを意味します。 ユーザーがエクスペリエンスを継続できるようにするには、有効期限が切れる前にトークンを更新します。

    ダッシュボードとタイル

    トークンの生成は、レポートとセマンティック モデルに対して機能します。 ダッシュボードまたはタイルの埋め込みトークンを生成するには、バージョン 1 の Dashboards GenerateTokenInGroup または Tiles GenerateTokenInGroup API を使用します。 これらの API は、一度に 1 つの項目に対してのみトークンを生成します。 複数の項目に対してトークンを生成することはできません。

    これらの API では:

    • ユーザーのアクセス レベルを決定するには、accessLevel パラメーターを使用します。

      • View - ユーザーに表示アクセス許可を付与します。

      • Edit - ユーザーに表示と編集のアクセス許可を付与します (レポート用の埋め込みトークンを生成する場合にのみ適用されます)。

      • Create - ユーザーに新しいレポートを作成するためのアクセス許可を付与します (レポートを作成するための埋め込みトークンを生成する場合にのみ適用されます)。 レポートを作成するには、datasetId パラメーターも指定する必要があります。

    • ユーザーがレポートを新しいレポートとして保存できるようにするには、allowSaveAs ブール値を使用します。 この設定は既定で false に設定され、レポートの埋め込みトークンを生成する場合にのみ適用されます。

    考慮事項と制限事項

    • セキュリティ上の理由から、埋め込みトークンの有効期間は、GenerateToken API の呼び出しに使用された Microsoft Entra トークンの残りの有効期間に設定されます。 したがって、同じ Microsoft Entra トークンを使用して複数の埋め込みトークンを生成する場合、生成される埋め込みトークンの有効期間は、呼び出しごとに短くなります。

    • 埋め込むセマンティック モデルと項目が 2 つの異なるワークスペースにある場合、サービス プリンシパルまたはマスター ユーザーは、少なくとも両方のワークスペースのメンバーである必要があります。

    • マイ ワークスペースに対する埋め込みトークンを作成することはできません。

    関連するコンテンツ