Udostępnij za pośrednictwem

Generowanie tokenu osadzania

  • Artykuł

DOTYCZY: Aplikacja jest właścicielem danych Użytkownik jest właścicielem danych

Generowanie tokenu to interfejs API REST, który umożliwia wygenerowanie tokenu na potrzeby osadzania raportu usługi Power BI lub modelu semantycznego w aplikacji internetowej lub portalu. Może wygenerować token dla jednego elementu lub wielu raportów lub modeli semantycznych. Token jest używany do autoryzowania żądania względem usługa Power BI.

Interfejs API generowania tokenu używa jednej tożsamości (użytkownika głównego lub jednostki usługi) do wygenerowania tokenu dla pojedynczego użytkownika, w zależności od poświadczeń tego użytkownika w aplikacji (obowiązująca tożsamość).

Po pomyślnym uwierzytelnieniu zostanie udzielony dostęp do odpowiednich danych.

Uwaga

Generowanie tokenu to nowszy interfejs API w wersji 2, który działa zarówno dla raportów, jak i modeli semantycznych oraz pojedynczych lub wielu elementów. Preferowane jest interfejsy API starszej wersji 1. W przypadku pulpitów nawigacyjnych i kafelków użyj pulpitów nawigacyjnych w wersji 1 GenerateTokenInGroup i kafelków GenerateTokenInGroup.

Zabezpieczanie danych

Jeśli obsługujesz dane od wielu klientów, istnieją dwa główne podejścia do zabezpieczania danych: izolacja oparta na obszarze roboczym i izolacja oparta na zabezpieczeniach na poziomie wiersza. Szczegółowe porównanie między nimi można znaleźć w profilach jednostki usługi i zabezpieczeniach na poziomie wiersza.

Zalecamy używanie izolacji opartej na obszarze roboczym z profilami, ale jeśli chcesz użyć podejścia zabezpieczeń na poziomie wiersza, zapoznaj się z sekcją Zabezpieczenia na poziomie wiersza na końcu tego artykułu.

Uprawnienia i zabezpieczenia tokenów

W sekcji GenerateTokenRequest w interfejsach API generowania tokenu opisano uprawnienia tokenu.

Poziom dostępu

  • Użyj parametru allowEdit , aby udzielić użytkownikowi uprawnień do wyświetlania lub edytowania.

  • Dodaj identyfikator obszaru roboczego do tokenu osadzania, aby umożliwić użytkownikowi tworzenie nowych raportów ( SaveAs lub CreateNew) w tym obszarze roboczym.

Zabezpieczenia na poziomie wiersza

W przypadku zabezpieczeń na poziomie wiersza (RLS) używana tożsamość może różnić się od tożsamości jednostki usługi lub użytkownika głównego używanego do generowania tokenu. Korzystając z różnych tożsamości, można wyświetlić informacje osadzone według docelowego użytkownika. Na przykład w aplikacji możesz poprosić użytkowników o zalogowanie się, a następnie wyświetlić raport zawierający tylko informacje o sprzedaży, jeśli zalogowany użytkownik jest pracownikiem sprzedaży.

Jeśli używasz zabezpieczeń na poziomie wiersza, czasami możesz pominąć tożsamość użytkownika ( parametr EffectiveIdentity ). Jeśli nie używasz parametru EffectiveIdentity , token ma dostęp do całej bazy danych. Ta metoda może służyć do udzielania dostępu użytkownikom, takim jak administratorzy i menedżerowie, którzy mają uprawnienia do wyświetlania całego modelu semantycznego. Jednak nie można użyć tej metody w każdym scenariuszu. Poniższa tabela zawiera listę różnych typów zabezpieczeń na poziomie wiersza i pokazuje, której metody uwierzytelniania można użyć bez określania tożsamości użytkownika.

W tabeli przedstawiono również zagadnienia i ograniczenia dotyczące poszczególnych typów zabezpieczeń na poziomie wiersza.

Typ zabezpieczeń na poziomie wiersza Czy mogę wygenerować token osadzania bez określania obowiązującego identyfikatora użytkownika? Rozważania i ograniczenia
Zabezpieczenia na poziomie wiersza chmury (zabezpieczenia na poziomie chmury) ✔ Użytkownik główny
✖ Jednostka usługi
RDL (raporty podzielone na strony) ✖ Użytkownik główny
✔ Jednostka usługi		 Nie można użyć użytkownika głównego do wygenerowania tokenu osadzania dla języka RDL.
Lokalne połączenie na żywo usług Analysis Services (AS) ✔ Użytkownik główny
✖ Jednostka usługi		 Użytkownik generujący token osadzania wymaga również jednego z następujących uprawnień:
  • Uprawnienia administratora bramy
  • Uprawnienie personifikacji źródła danych (ReadOverrideEffectiveIdentity)
    		•
    Połączenie na żywo z usługami Analysis Services (AS) na platformie Azure ✔ Użytkownik główny
    ✖ Jednostka usługi    		 Nie można zastąpić tożsamości użytkownika generującego token osadzania. Dane niestandardowe mogą służyć do implementowania dynamicznego zabezpieczeń na poziomie wiersza lub bezpiecznego filtrowania.

    Uwaga: jednostka usługi musi podać identyfikator obiektu jako obowiązującą tożsamość (nazwa użytkownika zabezpieczeń na poziomie wiersza).
    Logowanie jednokrotne (SSO) ✔ Użytkownik główny
    ✖ Jednostka usługi    		 Tożsamość jawna (SSO) może być udostępniana przy użyciu właściwości obiektu blob tożsamości w efektywnym obiekcie tożsamości
    Logowanie jednokrotne i zabezpieczenia na poziomie wiersza w chmurze ✔ Użytkownik główny
    ✖ Jednostka usługi    		 Musisz podać następujące informacje:
  • Tożsamość jawna (SSO) we właściwości obiektu blob tożsamości w efektywnym obiekcie tożsamości
  • Obowiązująca tożsamość (nazwa użytkownika)
    		•

    Uwaga

    Jednostki usługi muszą zawsze podać następujące informacje:

    • Tożsamość dla dowolnego elementu z semantycznym modelem zabezpieczeń na poziomie wiersza.
    • W przypadku modelu semantycznego logowania jednokrotnego obowiązująca tożsamość zabezpieczeń na poziomie wiersza z zdefiniowaną tożsamością kontekstową (SSO).

    Tryb DirectQuery dla modeli semantycznych usługi Power BI

    Aby osadzić raport usługi Power BI, który ma model semantyczny z połączeniem Direct Query z innym modelem semantycznym usługi Power BI, wykonaj następujące czynności:

    • W portalu usługi Power BI ustaw punkt końcowy XMLA na Tylko do odczytu lub Odczyt zapisu zgodnie z opisem w artykule Włączanie odczytu i zapisu dla pojemności Premium. Należy to zrobić tylko raz na pojemność.
    • Generowanie tokenu osadzania z wieloma zasobami
      • Określ wszystkie identyfikatory zestawów danych w żądaniu.
      • XmlaPermissions Dla każdego modelu semantycznego w żądaniu ustaw wartość Tylko do odczytu.
      • Dla każdego źródła danych z obsługą logowania jednokrotnego (SSO) podaj obiekt blob tożsamości dla źródła danych w pliku DatasourceIdentity.

    Odnawianie tokenów przed wygaśnięciem

    Tokeny mają limit czasu. Oznacza to, że po osadzeniu elementu usługi Power BI masz ograniczony czas na interakcję z nim. Aby zapewnić użytkownikom ciągłe środowisko, odnów (lub odśwież) token przed jego wygaśnięciem.

    Pulpity nawigacyjne i kafelki

    Generowanie tokenu działa dla raportów i modeli semantycznych. Aby wygenerować token osadzania dla pulpitu nawigacyjnego lub kafelka, użyj interfejsów API GenerateTokenInGroup lub GenerateTokenInGroup w wersji 1. Te interfejsy API generują tokeny tylko dla jednego elementu naraz. Nie można wygenerować tokenu dla wielu elementów.

    Dla tych interfejsów API:

    • Użyj parametru accessLevel , aby określić poziom dostępu użytkownika.

      • Widok — przyznaj użytkownikowi uprawnienia do wyświetlania.

      • Edytuj — udziel użytkownikowi uprawnień do wyświetlania i edytowania (dotyczy tylko generowania tokenu osadzania dla raportu).

      • Utwórz — przyznaj użytkownikowi uprawnienia do tworzenia nowego raportu (ma zastosowanie tylko podczas generowania tokenu osadzania do tworzenia raportu). W przypadku tworzenia raportu należy również podać parametr datasetId .

    • Użyj wartości logicznej allowSaveAs , aby umożliwić użytkownikom zapisywanie raportu jako nowego raportu. To ustawienie jest domyślnie ustawione na wartość false i ma zastosowanie tylko podczas generowania tokenu osadzania dla raportu.

    Rozważania i ograniczenia

    • Ze względów bezpieczeństwa okres istnienia tokenu osadzania jest ustawiony na pozostały okres istnienia tokenu Entra firmy Microsoft używanego do wywoływania interfejsu GenerateToken API. W związku z tym jeśli używasz tego samego tokenu firmy Microsoft Entra do generowania kilku tokenów osadzania, okres istnienia wygenerowanych tokenów osadzania będzie krótszy przy każdym wywołaniu.

    • Jeśli semantyczny model i element do osadzeni znajdują się w dwóch różnych obszarach roboczych, jednostka usługi lub użytkownik główny musi być co najmniej członkiem obu obszarów roboczych.

    • Nie można utworzyć tokenu osadzania dla obszaru Mój obszar roboczy.

    Powiązana zawartość