埋め込みトークンを生成する
適用対象:
アプリ所有データ 
ユーザー所有データ
トークンの生成は、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) のオンプレミス ライブ接続 | ✔ マスター ユーザー ✖ サービス プリンシパル |
埋め込みトークンを生成するユーザーには、次のいずれかのアクセス許可も必要です。 |
| Analysis Services (AS) の Azure ライブ接続 | ✔ マスター ユーザー ✖ サービス プリンシパル |
埋め込みトークンを生成するユーザーの ID を、オーバーライドすることはできません。 カスタム データを使用して、動的な RLS またはセキュリティで保護されたフィルター処理を実装できます。 注: サービス プリンシパルは、有効な ID (RLS ユーザー名) としてそのオブジェクト ID を提供する必要があります。 |
| シングル サインオン (SSO) | ✔ マスター ユーザー ✖ サービス プリンシパル |
明示的な (SSO) ID を、有効な ID オブジェクトの ID BLOB プロパティを使用して提供できます |
| SSO とクラウド RLS | ✔ マスター ユーザー ✖ サービス プリンシパル |
次のものを指定する必要があります。 |
注意
サービス プリンシパルでは常に次の情報を提供する必要があります。
- RLS セマンティック モデルでの任意の項目に対する ID。
- SSO セマンティック モデルの場合、コンテキスト (SSO) ID が定義されている有効な RLS ID。
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 つの異なるワークスペースにある場合、サービス プリンシパルまたはマスター ユーザーは、少なくとも両方のワークスペースのメンバーである必要があります。
マイ ワークスペースに対する埋め込みトークンを作成することはできません。