Najlepsze praktyki dotyczące interfejsu API REST do wykonywania zapytań DAX

Postępuj zgodnie z tymi zaleceniami, aby jak najlepiej wykorzystać interfejs API REST wykonywania zapytań języka DAX w obciążeniach produkcyjnych.

Wybieranie odpowiedniego punktu końcowego

Uwaga / Notatka

Interfejs API wykonywania zapytań języka DAX jest dostępny tylko dla modeli semantycznych znajdujących się w pojemności Power BI (Premium, Fabric lub Embedded). Modele semantyczne bez przypisania pojemności nie są obsługiwane.

Power BI oferuje dwa interfejsy API REST do wykonywania zapytań języka DAX. Wybierz tę, która jest zgodna z możliwościami klienta:

  • Wykonywanie zapytań języka DAX (Arrow) — używaj, gdy aplikacja kliencka może korzystać ze strumieni binarnych IPC Arrow. Arrow dostarcza mniejsze obciążenia danych, zapewniając bezstratną wierność typów oraz deserializację bezpośrednią w strukturach kolumnowych, takich jak pandas, Polars i Apache Spark. Ten interfejs API obsługuje również zaawansowane parametry, takie jak queryTimeout i resultsetRowcountLimit. Wymaga pojemności Premium lub Fabric.
  • Execute Queries (JSON) — Użyj, gdy konsumentem jest platforma niskokodowa/bez kodu, przepływ Power Automate lub dowolne narzędzie, które może analizować tylko JSON. Ten interfejs API działa w pojemnościach Pro, PPU i Premium/Fabric, ale ma twardy limit 100 000 wierszy i 1000 000 wartości na zapytanie.

Ogólnie rzecz biorąc, jeśli zestaw wyników przekracza kilkaset wierszy, jest zasilany do potoku analitycznego lub wymaga dokładnej zgodności typów, użyj API wykonywania zapytań DAX z Apache Arrow.

Optymalizacja zapytań DAX dla punktu końcowego Arrow

Wydajny język DAX skraca czas wykonywania zapytania i rozmiar ładunku odpowiedzi:

  • Zwróć tylko potrzebne kolumny. Użyj SELECTCOLUMNS lub jawnych list kolumn zamiast zwracać całe tabele. Każda dodatkowa kolumna zwiększa schemat i rozmiar partii rekordu.
  • Preferuj SUMMARIZECOLUMNS zamiast ADDCOLUMNS z FILTER. SUMMARIZECOLUMNS tworzy bardziej wydajne plany zapytań w aparacie VertiPaq.
  • Użyj polecenia TOPN , aby ograniczyć wiersze. Kiedy potrzebujesz tylko najlepszych wyników, TOPN przesuwa limit do silnika, zamiast przesyłać wszystkie wiersze i filtrować po stronie klienta.
  • Unikaj złożonych kolumn obliczeniowych w zapytaniach. Miary i agregacje są poprawne, ale obliczenia na poziomie wiersza w dużych tabelach mogą znacznie spowalniać wykonywanie.
  • Łączenie wielu EVALUATE wyrażeń w jednym żądaniu. Interfejs API wykonywania zapytań języka DAX obsługuje wiele EVALUATE instrukcji wewnątrz jednego query ciągu, z których każdy zwraca oddzielny zestaw wyników. Pozwala to uniknąć narzutu wynikającego z oddzielnych transakcji HTTP.

Efektywne zarządzanie uwierzytelnianiem

  • Buforowanie i ponowne używanie tokenów. Użyj wbudowanej pamięci podręcznej tokenów biblioteki MSAL, aby uniknąć wywoływania Microsoft Entra ID na każdym żądaniu. W przypadku poufnych przepływów klienckich, tokeny MSAL są buforowane automatycznie podczas ponownego użycia tego samego ConfidentialClientApplication wystąpienia.
  • Użyj poufnych poświadczeń klienta dla usług. W przypadku nienadzorowanych usług warstwy środkowej należy użyć poświadczeń klienta (klucza tajnego lub certyfikatu klienta) zamiast delegowanych tokenów użytkownika. Pozwala to uniknąć zależności od sesji zalogowanego użytkownika.
  • Zaleca się preferowanie tożsamości zarządzanych na platformie Azure. Gdy usługa działa w Azure (App Service, Functions, AKS), użyj tożsamości zarządzanej, aby całkowicie wyeliminować zarządzanie poświadczeniami.
  • Bezproblemowa obsługa wygasania tokenu. Tokeny dostępu zwykle wygasają po godzinie. 401 Unauthorized Przed ponowieniu próby sprawdź odpowiedzi i odśwież token.

Obsługa błędów i ponownych prób

Interfejs API wykonywania zapytań języka DAX może zwracać błędy na dwa sposoby:

  1. Błędy na poziomie HTTP — standardowe kody stanu HTTP z treścią błędu JSON. Typowe kody:

    Kod stanu Meaning Akcja
    400 Nieprawidłowe żądanie (błędny DAX, brakujące parametry) Popraw żądanie — nie wznawiaj.
    401 Brak autoryzacji (wygasł lub nieprawidłowy token) Odśwież token i spróbuj ponownie raz.
    403 Zabronione (niewystarczające uprawnienia) Sprawdź, czy obiekt wywołujący ma uprawnienia kompilacji i odczytu w modelu semantycznym.
    429 Zbyt wiele żądań (limitowane) Poczekaj na czas określony w nagłówku Retry-After, po czym ponów próbę.
    500 / 502 / 503 Przejściowe błędy serwera Ponów próbę z wycofywaniem wykładniczym.

  2. Błędy na poziomie strumienia — HTTP 200 z zestawem wierszy błędów osadzonym w odpowiedzi strzałki. Sprawdź metadane schematu Arrow dotyczące IsError=true i odczytaj wartości metadanych z FaultCode oraz wiersze błędów z FaultString, aby uzyskać szczegółowe informacje o lokalizacji.

W przypadku błędów przejściowych zaimplementuj wycofywanie wykładnicze z zakłóceniami. Rozpocznij od jednej sekundy, podwajaj czas przy każdej kolejnej próbie i ogranicz do 30 sekund. Ogranicz ponawianie prób do trzech lub czterech prób.

Kontrolowanie rozmiaru zestawu wyników

Duże zestawy wyników zużywają pamięć zarówno w pojemności usługi, jak i klienta wywołującego. Każde żądanie jest ograniczone limitem pamięci zasobów systemowych.

Aby zachować możliwość zarządzania zestawami wyników:

  • Ustaw resultsetRowcountLimit w treści żądania. Wymusza to limit wierszy po stronie serwera dla zestawu wyników. Jeśli wiesz, że użytkownik potrzebuje tylko 10 000 wierszy, ustaw jawnie limit.
  • Użyj TOPN w zapytaniu języka DAX. TOPN ogranicza wiersze na poziomie silnika, co jest bardziej wydajne niż skracanie po stronie klienta.
  • Przetwarzaj partie rekordów przyrostowo. Odpowiedzi Arrow są podzielone na partie rekordów z maksymalnie 100 000 wierszy. W Pythonie iteruj po paczkach przy użyciu reader.read_next_batch() zamiast wywoływania reader.read_all() podczas operowania na dużych wynikach, aby utrzymać stałe zużycie pamięci.

Zabezpiecz usługę warstwy średniej

Jeśli tworzysz usługę warstwy średniej, która pośredniczy w przetwarzaniu zapytań języka DAX dla końcowych odbiorców:

  • Zweryfikuj tożsamość wywołującego. Uwierzytelnij przychodzące żądania za pomocą Microsoft Entra ID lub innego dostawcy tożsamości, zanim przekażesz zapytania do Power BI. Nigdy nie udostępniaj punktu końcowego zapytań DAX jako otwartego serwera proxy.
  • Egzekwowanie zasady najmniejszych uprawnień. Przyznaj jednostce usługi tylko wymagane uprawnienia (Kompiluj i odczyt dla określonych modeli semantycznych). Nie używaj ról administratora obszaru roboczego ani administratora dzierżawy na potrzeby dostępu do interfejsu API.
  • Nie osadzaj poświadczeń w kodzie. Przechowuj tajemnice klienta w Azure Key Vault lub używaj tożsamości zarządzanych. Obracaj tajne dane w regularnym harmonogramie.
  • Wyczyść dane wejściowe DAX. Jeśli warstwa środkowa akceptuje tekst zapytania języka DAX od osób wywołujących, zweryfikuj dane wejściowe, aby zapobiec wstrzyknięciu nieoczekiwanych operacji.
  • Użyj parametru effectiveUsername z ostrożnością. Ten parametr stosuje zabezpieczenie na poziomie wiersza w imieniu określonego użytkownika. Upewnij się, że tożsamość wywołująca jest autoryzowana do personifikacji określonego użytkownika.

Monitorowanie i rejestrowanie

Śledź kondycję i wydajność użycia interfejsu API:

  • Metadane zapytania dziennika — rejestruj tekst zapytania, rozmiar odpowiedzi, stan HTTP i czas trwania każdego żądania. Pomaga to zidentyfikować powolne zapytania i nieoczekiwane skoki błędów.
  • Monitorowanie szybkości ograniczania przepływności — śledzenie 429 odpowiedzi jako procent całkowitych żądań. Rosnący trend wskazuje, że musisz zmniejszyć częstotliwość żądań lub rozłożyć obciążenie w czasie.
  • Mierzenie czasu deserializacji — w przypadku odpowiedzi w formacie Arrow zarejestruj czas spędzony na odczytywaniu i materializowaniu pakietów rekordów niezależnie od czasu trwania rundy HTTP. Ułatwia to odróżnienie opóźnienia sieci od przetwarzania po stronie klienta.
  • Użyj usługi Application Insights lub równoważnej — jeśli w Azure działa warstwa środkowa, włącz usługę Application Insights, aby uzyskać śledzenie zależności, alerty o błędach i kompleksowe śledzenie rozproszone.
  • Śledź liczby trafień pamięci podręcznej tokenu — niska liczba trafień pamięci podręcznej oznacza częste wywołania pozyskiwania tokenów, które dodają opóźnienie i są oznaką błędnie skonfigurowanego buforowania MSAL.

Treści powiązane

  • Last updated on