API do SSRS

API do SSRS to interfejs umożliwiający programowe zarządzanie raportami w usłudze SQL Server Reporting Services.

Rola API w architekturze SQL Server Reporting Services

API do SQL Server Reporting Services (SSRS) umożliwia wykonywanie operacji na raportach bez korzystania z graficznego portalu raportów. Program może łączyć się z serwerem raportów, wyszukiwać elementy katalogu, odczytywać właściwości raportów, zarządzać folderami oraz uruchamiać eksport wyników do obsługiwanych formatów. Interfejs jest używany przez aplikacje administracyjne, narzędzia wdrożeniowe, systemy integracyjne i skrypty automatyzujące pracę z katalogiem SSRS.

W SSRS występują dwa główne sposoby komunikacji programowej. Nowszy interfejs REST API udostępnia zasoby HTTP i operuje na adresach URL serwera raportów. Starszy, szeroko stosowany interfejs SOAP korzysta z usług sieciowych opisanych dokumentem WSDL. Oba rozwiązania służą do pracy z obiektami SSRS, ale różnią się formatem żądań, sposobem reprezentowania danych oraz zakresem operacji dostępnym w konkretnej wersji i trybie wdrożenia.

REST API, SOAP i obiekty katalogu raportów

REST API SSRS wykorzystuje żądania HTTP do pracy z elementami przechowywanymi w katalogu raportów. W zależności od wersji serwera oraz konfiguracji mogą być dostępne operacje związane z raportami, folderami, źródłami danych, zestawami danych, subskrypcjami i parametrami. Odpowiedź jest zwykle zwracana w formacie JSON, dzięki czemu aplikacja może przetwarzać właściwości obiektu bez generowania klienta SOAP.

SOAP Web Service SSRS udostępnia operacje opisane w kontrakcie usługi. W klasycznym trybie pracy administracyjnej wykorzystywany jest punkt końcowy związany z usługą raportowania, a klient wysyła komunikaty XML zgodne z WSDL. Wśród typowych operacji znajdują się pobieranie definicji raportu, publikowanie raportu, tworzenie folderu, ustawianie właściwości, odczytywanie uprawnień oraz zarządzanie subskrypcjami. Nazwy metod i ich parametry należy sprawdzić dla konkretnej wersji SSRS, ponieważ nie każdy element dostępny w portalu musi mieć identyczny odpowiednik w każdym interfejsie.

Uwierzytelnianie, adresowanie i wykonanie żądania

Żądanie do API musi wskazywać właściwy adres serwera raportów oraz zawierać uwierzytelnienie akceptowane przez daną instalację SSRS. W środowisku Windows często stosuje się uwierzytelnianie zintegrowane, natomiast sposób logowania może zależeć od trybu instalacji, konfiguracji usług oraz używanej wersji produktu. Sam fakt, że portal raportów otwiera się w przeglądarce, nie oznacza jeszcze, że dowolny klient HTTP będzie miał uprawnienia do tych samych operacji.

Istotne jest odróżnienie adresu portalu raportów od adresu usługi sieciowej lub interfejsu REST. Aplikacja powinna korzystać z punktu końcowego właściwego dla konkretnej instalacji, a ścieżkę raportu traktować jako identyfikator elementu katalogu, nie jako zwykłą nazwę pliku na dysku. Operacje zapisu, takie jak publikowanie definicji raportu albo modyfikowanie zabezpieczeń, wymagają odpowiednich uprawnień. Błąd HTTP 401 oznacza problem z uwierzytelnieniem, 403 z brakiem uprawnień, a 404 może wskazywać nieprawidłową ścieżkę, niewłaściwy punkt końcowy albo brak danego zasobu.

Przy integracji należy również obsłużyć kod odpowiedzi, limit czasu, przerwanie połączenia i błędy zwracane w treści komunikatu. Program nie powinien uznawać każdej odpowiedzi HTTP za sukces ani ponawiać bez ograniczeń operacji zmieniających stan katalogu. Bezpieczniejszy przepływ obejmuje odczyt istniejącego zasobu, sprawdzenie jego właściwości, wykonanie jednej operacji oraz ponowną kontrolę wyniku.

Automatyzacja publikowania i diagnostyka integracji SSRS

API do SSRS może służyć do powtarzalnego wdrażania raportów. Proces może pobrać definicję raportu, wybrać docelowy folder, przesłać plik definicji raportu, skonfigurować źródła danych i zweryfikować obecność obiektu w katalogu. Raport może zawierać parametry, odwołania do współdzielonych źródeł danych oraz zależności od innych elementów SSRS, dlatego samo pomyślne przesłanie definicji nie zawsze oznacza, że raport będzie wykonywał zapytania poprawnie.

Podczas diagnozowania integracji należy sprawdzić kolejno adres serwera, tryb SSRS, używany interfejs, metodę uwierzytelniania, ścieżkę katalogową i uprawnienia konta. Następnie warto przeanalizować status HTTP, nagłówki, treść odpowiedzi oraz logi serwera raportów. Dla raportu, który nie generuje wyniku, trzeba dodatkowo zweryfikować parametry, połączenie ze źródłem danych, uprawnienia do bazy SQL Server i zgodność definicji raportu z wersją środowiska docelowego.

Problemy mogą wynikać także z pomieszania różnych usług Microsoft. SQL Server Reporting Services jest platformą raportową, a jego API nie jest ogólnym interfejsem administracyjnym dla aparatu bazy danych SQL Server. Żądania dotyczące raportów, katalogu i subskrypcji należy kierować do punktów końcowych SSRS, natomiast operacje na danych wykonuje sam raport za pośrednictwem skonfigurowanego źródła danych. Takie rozdzielenie ułatwia ustalenie, czy błąd znajduje się w komunikacji z usługą raportową, w definicji raportu, czy w zapytaniu wykonywanym przez raport.