埋め込みトークンを生成する
適用対象:
アプリ所有データ 
ユーザー所有データ
トークンの生成は、Web アプリまたはポータルに Power BI レポートまたはセマンティック モデルを埋め込むためのトークンを生成できる REST API です。 1 つの項目または複数のレポートやセマンティック モデルのトークンを生成できます。 トークンは、Power BI サービスに対する要求を承認するために使用されます。
トークンの生成 API は、単一の ID (マスター ユーザーまたはサービス プリンシパル) を使用して、アプリ内のユーザーの資格情報 (有効な ID) に応じて、個々のユーザーのトークンを生成します。
認証が成功すると、関連データへのアクセスが許可されます。
Note
トークンの生成は、レポートとセマンティック モデルの両方、および単一または複数の項目に対して機能する、新しいバージョン 2 の API です。 ダッシュボードとタイルの場合は、V1 ダッシュボード 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) のオンプレミス ライブ接続 | ✔ マスター ユーザー ✖ サービス プリンシパル |
埋め込みトークンを生成するユーザーには、次のいずれかのアクセス許可も必要です。 |
| Analysis Services (AS) の Azure ライブ接続 | ✔ マスター ユーザー ✖ サービス プリンシパル |
埋め込みトークンを生成するユーザーの ID を、オーバーライドすることはできません。 カスタム データを使用して、動的な RLS またはセキュリティで保護されたフィルター処理を実装できます。 注: サービス プリンシパルは、有効な ID (RLS ユーザー名) としてそのオブジェクト ID を提供する必要があります。 |
| シングル サインオン (SSO) | ✔ マスター ユーザー ✖ サービス プリンシパル |
明示的な (SSO) ID を、有効な ID オブジェクトの ID BLOB プロパティを使用して提供できます |
| SSO とクラウド RLS | ✔ マスター ユーザー ✖ サービス プリンシパル |
以下を指定する必要があります。 |
Note
サービス プリンシパルは常に次の情報を提供する必要があります。
- RLS セマンティック モデルを持つ項目の ID
- コンテキスト (SSO) ID が定義された有効な RLS ID (SSO セマンティック モデルの場合)
Power BI セマンティック モデルの DirectQuery
別の Power BI セマンティック モデルへの直接クエリ接続を持つセマンティック モデルを持つ Power BI レポートを埋め込むには、
Power BI ポータルで、「Premium 容量の読み取り/書き込みを有効にするには」の説明に従って、[XMLA エンドポイント] を [読み取り専用] または [読み取り/書き込み] に設定します。 これは容量ごとに 1 回のみ行います。
複数リソースの埋め込みトークンを生成する
- 要求内のすべてのデータセット ID を指定します。
- 要求内の各セマンティック モデルの
XmlaPermissionsを読み取り専用に設定します。 - シングル サインオン (SSO) が有効なデータ ソースごとに、データ ソースの ID BLOB を
DatasourceIdentityに指定します。
有効期限が切れる前にトークンを更新する
トークンには時間制限があります。 そのため、Power BI 項目を埋め込んだ後、操作する時間は限られます。 ユーザーがエクスペリエンスを継続できるようにするには、有効期限が切れる前にトークンを更新します。
ダッシュボードとタイル
トークンの生成は、レポートとセマンティック モデルに対して機能します。 ダッシュボードまたはタイルの埋め込みトークンを生成するには、バージョン 1 の Dashboards GenerateTokenInGroup または Tiles GenerateTokenInGroup API を使用します。 これらの API は、一度に 1 つの項目に対してのみトークンを生成します。 複数の項目に対してトークンを生成することはできません。
これらの API では:
ユーザーのアクセス レベルを決定するには、accessLevel パラメーターを使用します。
View - ユーザーに表示アクセス許可を付与します。
Edit - ユーザーに表示と編集のアクセス許可を付与します (レポート用の埋め込みトークンを生成する場合にのみ適用されます)。
Create - ユーザーに新しいレポートを作成するためのアクセス許可を付与します (レポートを作成するための埋め込みトークンを生成する場合にのみ適用されます)。 レポートを作成するには、datasetId パラメーターも指定する必要があります。
ユーザーがレポートを新しいレポートとして保存できるようにするには、allowSaveAs ブール値を使用します。 この設定は既定で false に設定され、レポートの埋め込みトークンを生成する場合にのみ適用されます。
考慮事項と制限事項
セキュリティ上の理由から、埋め込みトークンの有効期間は、
GenerateTokenAPI の呼び出しに使用された Microsoft Entra トークンの残りの有効期間に設定されます。 そのため、同じ Microsoft Entra トークンを使用して複数の埋め込みトークンを生成する場合、生成された埋め込みトークンの有効期間は呼び出しごとに短くなります。埋め込むセマンティック モデルと項目が 2 つの異なるワークスペースにある場合、サービス プリンシパルまたはマスター ユーザーは、少なくとも両方のワークスペースのメンバーである必要があります。
Data Lake Storage (DLS) を使用して項目を埋め込むには、Generate token APIの V2 が必要です。
マイ ワークスペースに対する埋め込みトークンを作成することはできません。