Subskrypcje push do katalogu EODATA na NSIS Cloud

Subskrypcje push i pull umożliwiają otrzymywanie powiadomień, gdy produkty w katalogu EODATA (lub podzbiór takich produktów) są dodawane, modyfikowane lub usuwane.

W tym artykule omówimy subskrypcje push, czyli subskrypcje dostarczające powiadomienia bezpośrednio do punktu końcowego zarządzanego przez użytkownika.

Istnieją również tak zwane subskrypcje pull, które są metodą otrzymywania powiadomień z katalogu EODATA poprzez okresowe pobieranie ich z dedykowanej kolejki w chmurze. Zostały one opisane w Subskrypcje pull do katalogu EODATA na NSIS Cloud.

Co zostanie omówione?

Wymagania wstępne

Nr 1 Konto

Potrzebujesz aktywnego konta NSIS Cloud https://tm.nsiscloud.polsa.gov.pl/login.

Nr 2 Możliwość wysyłania żądań HTTP

Aby wykonać kroki opisane w tym artykule, potrzebujesz metody wysyłania żądań GET, POST, PATCH i DELETE, wraz z nagłówkami oraz — tam, gdzie to wymagane — treścią JSON. Musisz także być w stanie odczytywać odpowiedzi na te żądania.

Poniżej znajduje się niewyczerpująca lista metod, których możesz użyć do wykonania przykładów z tego artykułu:

Wysyłanie żądań HTTP przez przeglądarkę

Najprostszym sposobem wysłania żądania HTTP jest otwarcie adresu internetowego w przeglądarce. Większość przeglądarek rozpozna dane wyjściowe ze strony i przedstawi je w użytecznej formie. Zobacz Jak wysyłać żądania do katalogu API NSIS Cloud EODATA za pomocą Firefox
Wysyłanie żądań HTTP za pomocą curl lub wget

Możesz używać samodzielnych programów curl i wget z wiersza poleceń do wysyłania żądań HTTP. Więcej informacji znajdziesz w Użycie curl i wget do pobierania produktów EODATA z NSIS Cloud
Wysyłanie żądań HTTP za pomocą kodu Python

Możesz użyć języka programowania, takiego jak Python, aby napisać kod wysyłający żądania HTTP do serwera. Zobacz Używanie Pythona do wysyłania żądań do katalogu EODATA na NSIS Cloud. Inne języki programowania również powinny umożliwiać wysyłanie żądań HTTP.

Powinieneś mieć pewne doświadczenie w korzystaniu z Pythona, zanim spróbujesz uruchamiać kod Python z tego artykułu. Będziesz potrzebować zainstalowanego Pythona oraz modułu requests.

Jeśli używasz Ubuntu 24.04, wykonaj:
```
sudo apt install python3-requests
```
aby zainstalować wymagany moduł requests. Powinno to również zainstalować interpreter Pythona, jeśli jeszcze go nie masz.

W systemie Windows możesz skorzystać z tego artykułu: Jak zainstalować środowisko Python w Windows na NSIS. Następnie zainstaluj moduł requests.

Inne systemy operacyjne również mogą działać, ale mogą być wymagane pewne dostosowania.

Nr 3 Wiedza, jak filtrować produkty

Jeśli chcesz otrzymywać powiadomienia o zmianach tylko dla podzbioru produktów (zamiast otrzymywać dane o wszystkich produktach), musisz użyć odpowiedniego filtra.

Filtry używane w tym artykule są opisane w Podręcznik API katalogu EOData na NSIS Cloud (są one takie same jak filtry używane dla parametru $filter w OData).

W przypadku filtrów dotyczących produktów created i/lub modified, sprawdź sekcję dotyczącą punktu końcowego OData Products w artykule EODATA Catalogue API Manual.

W przypadku filtrów dotyczących produktów deleted, sprawdź sekcję dotyczącą punktu końcowego OData DeletedProducts w artykule EODATA Catalogue API Manual.

Punkty końcowe Products i DeletedProducts różnią się pod względem dostępnych opcji, na przykład DeletedProducts pozwala wyszukiwać według przyczyny usunięcia produktów EODATA, podczas gdy dla punktu końcowego Products nie ma równoważnej opcji.

Nr 4 Wygenerowany token Keycloak

Aby potwierdzić swoją tożsamość podczas korzystania z subskrypcji push, potrzebujesz tokenu Keycloak. Oto jak go wygenerować: Użycie curl i wget do pobierania produktów EODATA z NSIS Cloud

Token Keycloak jest ważny tylko przez ograniczony czas; możesz wygenerować nowy token, jeśli bieżący wygaśnie, a ty chcesz nadal korzystać z API subskrypcji.

Jeśli używasz Pythona lub Bash i na twoim koncie jest włączone uwierzytelnianie dwuskładnikowe, możesz również automatycznie generować token Keycloak bez konieczności podawania sześciocyfrowego kodu TOTP. Więcej informacji:

Użycie powłoki Bash, do zautomatyzowania generowania tokenów API do uzyskiwania dostępu i pobierania EODATA, gdy uwierzytelnianie 2FA jest włączone w NSIS Cloud

Użycie języka Python, do zautomatyzowania generowania tokenów API do uzyskiwania dostępu i pobierania EODATA, gdy uwierzytelnianie 2FA jest włączone w NSIS Cloud

Nr 5 Punkt końcowy, który będzie otrzymywać powiadomienia

Potrzebujesz fizycznej lub wirtualnej maszyny, która będzie pełnić rolę twojego punktu końcowego. Musi ona mieć publiczny adres IP oraz przypisaną do niego domenę. Potrzebny jest również otwarty port, na który będą wysyłane powiadomienia.

Aby odczytywać przychodzące powiadomienia, potrzebujesz oprogramowania serwera HTTP z obsługą Basic Authentication. Musi ono być zabezpieczone za pomocą HTTPS, z certyfikatem wystawionym przez zaufany podmiot. Może to być na przykład jeden z komercyjnych dostawców albo Let’s Encrypt (który zapewnia bezpłatne certyfikaty).

Taki serwer możesz skonfigurować między innymi na maszynie wirtualnej z systemem Linux działającej w chmurze NSIS Cloud, do której przypisano Floating IP.

Ostrzeżenie

Certyfikat musi być publicznie zaufany (bez self-signed).

Port musi być osiągalny z Internetu.

Dane Basic Auth muszą być dokładnie zgodne.

Przed utworzeniem subskrypcji sprawdź, czy twój punkt końcowy zwraca 200 OK na żądanie testowe, na przykład

GET https://example.com:8000/

przy użyciu tego samego adresu HTTPS URL i tych samych danych Basic Auth.

Wprowadzenie

Co powinno zawierać żądanie HTTP?

Subskrypcje push możesz tworzyć i nimi zarządzać, wysyłając żądania HTTP.

Podczas wysyłania żądań HTTP opisanych w tym artykule zawsze używaj:

Typu żądania (GET, POST, PATCH lub DELETE)

Nagłówków

URL

Wszystkie te trzy części żądania HTTP muszą występować razem. Niektóre typy żądań HTTP muszą również zawierać treść.

Nagłówki

Żądania opisane w tym artykule powinny zawierać następujące nagłówki:

{
   "Content-Type": "application/json",
   "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}

gdzie YOUR_ACCESS_TOKEN_HERE należy zastąpić tokenem Keycloak z Wymagania wstępnego nr 4. Ten token będzie używany do potwierdzenia twojej tożsamości.

Będziemy je nazywać „obowiązkowymi nagłówkami” i w ten sposób odnosić się do nich w całym artykule.

W przypadku żądań GET nagłówek Content-Type nie jest bezwzględnie wymagany, ale jego dołączenie nie powoduje problemów.

Dane JSON w odpowiedziach

Niektóre żądania opisane w tym artykule zwracają dane JSON. Na potrzeby tego artykułu sformatowaliśmy je w wielu wierszach, aby były bardziej czytelne.

Opis jednostki subskrypcji push

Push subscription entity description table

Nazwa właściwości	Typ	Opis
Id	Guid	Jest to uniwersalny unikalny identyfikator (UUID). Id jest lokalnym identyfikatorem instancji Subscription w obrębie Katalogu, przypisywanym podczas tworzenia subskrypcji. Przykład 9249dde5-4838-4a34-8925-bac8c1d53f09c
SubscriptionType	Subscription Type enumeration	Typ utworzonej subskrypcji: pull push Wartość musi być wpisana małymi literami. Przykład push
Status	Subscription Status enumeration	Dozwolone wartości statusu subskrypcji to: running (subskrypcja jest aktywna i wysyła powiadomienia do punktu końcowego) paused (subskrypcja nie wysyła powiadomień do punktu końcowego) cancelled (ustawienie tego statusu zawiesza i usuwa subskrypcję) Subskrypcja w stanie running jest automatycznie ustawiana na paused po 60 dniach nieaktywności. Po 365 dniach od ostatniego powiadomienia status subskrypcji zmienia się na cancelled, a subskrypcja jest trwale usuwana. Domyślną wartością pola Status, jeśli użytkownik go nie poda, jest 'running'. Przykład running
SubscriptionEvent	Subscription Event enumeration	Zdarzenie subskrypcji, które ma być monitorowane i dla którego dostarczane jest powiadomienie. Może mieć następujące wartości: created modified created and modified. Aby śledzić oba, wyślij SubscriptionEvent jako tablicę typu `["created","modified"]`. deleted Domyślną wartością ustawioną dla SubscriptionEvent, jeśli użytkownik jej nie poda, jest created. Dla "SubscriptionEvent" = "created" będą wysyłane powiadomienia o nowo dodanych produktach do katalogu EOData. Dla "SubscriptionEvent" = "modified" będą wysyłane powiadomienia o zaktualizowanych produktach w katalogu EOData. Dla "SubscriptionEvent" = "deleted" będą wysyłane powiadomienia o usuniętych produktach z katalogu EOData. Zdarzy się to, jeśli zostanie spełniona jedna z następujących wartości parametru "DeletionCause": Duplicated product Missing checksum Corrupted product Obsolete product or Other Przykład created
FilterParam	String	Parametry filtrowania subskrypcji. Jeśli "SubscriptionEvent" = "created" lub "modified", to zapytanie odnosi się do parametru $filter= dowolnego zapytania typu Products?. Jeśli "SubscriptionEvent" = "deleted", to zapytanie odnosi się do parametru $filter= dowolnego zapytania typu DeletedProducts. Dostępne są te same parametry filtrowania, które opisano dla katalogu EOData — więcej szczegółów znajdziesz w Wymaganiu wstępnym nr 3. Przykład Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any (att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')
SubmissionDate	DateTimeOffset	Data i godzina, w której subskrypcja została odebrana przez Katalog. Czas jest w formacie ISO 8601 (UTC+0): YYYY-MM-DDThh:mm:ss.sssZ Przykład 2024-01-17T09:13:04.654Z
LastNotificationDate	DateTimeOffset	Data i godzina odpowiadająca ostatniemu momentowi, w którym usługa Subscription Service pomyślnie wysłała powiadomienie do punktu końcowego użytkownika. Czas jest w formacie ISO 8601 (UTC+0): YYYY-MM-DDThh:mm:ss.sssZ Przykład 2024-01-17T09:50:10.654Z
StageOrder	Boolean	Automatycznie zleca staging produktów spełniających warunki subskrypcji. Używane wyłącznie wtedy, gdy wartość SubscriptionEvent to created. Obecnie zlecanie stagingu produktów nie ma praktycznego zastosowania, ponieważ wszystkie produkty w katalogu EOData mają status Online i są dostępne natychmiast, bez konieczności składania zamówienia. Przykład true
Priority	Int64	Priorytet utworzonych zleceń wynikających z subskrypcji. Obecnie ustawiany automatycznie na wartość 1 bez możliwości zmiany. Przykład 1
NotificationEndpoint	String	Punkt końcowy użytkownika, do którego będą wysyłane powiadomienia. Przykład https://notification-endpoint.example.com:4000
NotificationEpUsername	String	Nazwa użytkownika używana do uwierzytelniania w punkcie końcowym powiadomień. Jest obowiązkowa, jeśli NotificationEndpoint wymaga uwierzytelnienia. Przykład mylocalusername
NotificationEpPassword	String	Hasło używane do uwierzytelniania w punkcie końcowym powiadomień. Jest obowiązkowe, jeśli NotificationEndpoint wymaga uwierzytelnienia. Przykład My%Password#789

Ograniczenia subskrypcji

Twoje konto może mieć maksymalnie 2 (dwie) subskrypcje w stanie running jednocześnie. Mogą to być

dwie subskrypcje push (opisane w tym artykule), lub

dwie subskrypcje pull (opisane w Subskrypcje pull do katalogu EODATA na NSIS Cloud), lub

jedna subskrypcja push i jedna subskrypcja pull.

Maksymalna łączna liczba subskrypcji powiązanych z kontem NSIS Cloud wynosi 10. Obejmuje to subskrypcje wszystkich typów:

running i paused

push i pull

Tworzenie subskrypcji push

Informacja

Subskrypcje push muszą zawierać SubscriptionType, a jego wartość musi być ustawiona na push (małymi literami).

Jeśli masz już dwie subskrypcje w stanie running, utwórz nową najpierw jako paused, następnie wstrzymaj istniejącą i przełącz nową na running.

Typowa treść żądania tworzącego subskrypcję push wygląda tak:

{
    "SubscriptionType": "push",
    "StageOrder": true,
    "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created"
    ],
    "NotificationEndpoint": "https://example.com:8000/",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

Ustaw własne wartości dla następujących kluczy w tej treści JSON:

SubscriptionType

Typ tworzonej subskrypcji. W przypadku subskrypcji push ustaw go na push (małymi literami).

SubscriptionEvent

Wartością tego klucza jest tablica zawierająca jeden lub więcej ciągów znaków. Za pomocą tych ciągów wybierasz, o jakich typach zdarzeń chcesz otrzymywać powiadomienia. Może mieć następujące wartości:

created

modified

deleted

Aby śledzić wiele zdarzeń, umieść wiele wartości w tablicy (na przykład: [„created”, „modified”]).

FilterParam

Zastąp wartość FilterParam zapytaniem definiującym podzbiór produktów, o których chcesz otrzymywać powiadomienia. Więcej informacji znajdziesz w Wymaganiu wstępnym nr 3.

Aby uzyskać informacje

o produktach utworzonych i/lub zmodyfikowanych, użyj tego samego zapytania, jakie wysłałbyś do punktu końcowego Products

o produktach usuniętych, użyj tego samego zapytania, jakie wysłałbyś do punktu końcowego DeletedProducts

Możesz również otrzymywać powiadomienia o wybranych typach zdarzeń dotyczących wszystkich produktów z katalogu, a nie tylko ich podzbioru. W tym celu możesz

pozostawić wartość klucza FilterParam pustą, lub

w ogóle nie dołączać tego klucza do żądania.

Status

Jeśli ustawisz wartość tego klucza na running, utworzona subskrypcja natychmiast zacznie otrzymywać powiadomienia. Jeśli jednak chcesz utworzyć subskrypcję wstrzymaną (nieaktywną) i aktywować ją później, ustaw tę wartość na paused.

Jeśli nie dodasz tego klucza do żądania, utworzona subskrypcja będzie miała status running.

Jeśli masz już 2 subskrypcje w stanie running i spróbujesz utworzyć kolejną subskrypcję z tym samym statusem, operacja zakończy się niepowodzeniem. Więcej informacji znajdziesz w sekcji Ograniczenia subskrypcji powyżej.

Aby rozwiązać ten problem, możesz

wstrzymać jedną z bieżących subskrypcji, a następnie utworzyć nową subskrypcję, lub

utworzyć nową subskrypcję ze statusem paused.

NotificationEndpoint

Adres URL twojego punktu końcowego wraz z portem, pod którym jest dostępny.

NotificationEpUsername

Nazwa użytkownika używana do uwierzytelniania w twoim punkcie końcowym powiadomień.

NotificationEpPassword

Hasło używane do uwierzytelniania w twoim punkcie końcowym powiadomień.

NotificationEpUsername oraz NotificationEpPassword powinny być bezpieczne i nie powinny być takie same jak dane logowania do twojego konta NSIS Cloud.

Zapytanie podane w powyższym przykładzie jako wartość klucza FilterParam powinno być poprawne, więc możesz go użyć do testowania powiadomień push.

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

To jest adres URL, na który należy wysłać to żądanie:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions

Kod odpowiedzi na to żądanie powinien mieć wartość 201 Created. Powinieneś również otrzymać dane JSON zawierające informacje o twojej nowej subskrypcji, na przykład:

{
  "Id": "0b5aaa72-922f-4b69-ad7f-1ccebc3e824e",
  "SubscriptionType": "push",
  "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
  "StageOrder": false,
  "Priority": 1,
  "Status": "running",
  "NotificationEndpoint": "https://example.com:8000/",
  "SubscriptionEvent": [
    "created"
  ],
  "SubmissionDate": "2025-04-10T10:35:51.299345Z",
  "@odata.context": "$metadata#OData.CSC.Subscription"
}

Subskrypcja powinna zostać teraz utworzona. Aby potwierdzić, że istnieje, wyślij żądanie GET do https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions/Info i poszukaj identyfikatora Id swojej subskrypcji w odpowiedzi.

Przykład: Tworzenie subskrypcji push przy użyciu Pythona

Oto kod w Pythonie, który wyśle żądanie z parametrami opisanymi powyżej:

import requests
import json

access_token = "" # paste token here

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {access_token}",
}

body = {
    "SubscriptionType": "push",
    "StageOrder": True,
    "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created"
    ],
    "NotificationEndpoint": "https://example.com:8000/catalogue-notifications",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

url = "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions"

response = requests.post(url=url, headers=headers, json=body)

print(f"{response.status_code} {response.reason}\n")
try:
    print(json.dumps(json.loads(response.text), indent=4))
except Exception:
    print(response.text)

Ten skrypt:

Wysyła żądanie HTTP na wskazany adres URL.

Pobiera i wyświetla wynik, który składa się z:

Kodu odpowiedzi (np. 200) i powodu (np. OK).

Pustego wiersza (dla czytelności).

Treści odpowiedzi, jeśli występuje. (Jeśli jest to poprawny JSON, zostanie sformatowany tak, aby był bardziej czytelny.)

Zwróć uwagę, że w tym skrypcie treść żądania jest przekazywana do modułu requests przy użyciu parametru json.

Przypisz token Keycloak uzyskany zgodnie z Wymaganiem wstępnym nr 4 do zmiennej access_token.

W słowniku body wpisz informacje o powiadomieniu jako wartości odpowiednich kluczy:

NotificationEndpoint - adres URL punktu końcowego powiadomień, wraz z portem, jeśli nie jest to 443

NotificationEpUsername - nazwę użytkownika dla twojego punktu końcowego

NotificationEpPassword - hasło do twojego punktu końcowego

Zapisz plik jako http_request_test_create.py

Aby uruchomić ten skrypt, wykonaj następujące polecenie (zakładając, że znajdujesz się w tym samym katalogu co skrypt):

python3 http_request_test_create.py

python http_request_test_create.py

Przykład: Tworzenie subskrypcji do śledzenia utworzonych i zmodyfikowanych produktów

W tym przykładzie utworzymy subskrypcję, która śledzi zarówno produkty utworzone, jak i zmodyfikowane, spełniające następujące kryteria (FilterParam):

Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')

Aby to zrobić, wyślij żądanie HTTP POST z następującą treścią:

{
    "SubscriptionType": "push",
    "StageOrder": true,
    "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created",
        "modified"
    ],
    "NotificationEndpoint": "https://example.com:8000/catalogue-notifications",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

na ten adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

Powinieneś otrzymać kod 201 Created oraz następujący obiekt JSON:

{
  "Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
  "SubscriptionType": "push",
  "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
  "StageOrder": false,
  "Priority": 1,
  "Status": "running",
  "NotificationEndpoint": "https://example.com:8000/catalogue-notifications",
  "SubscriptionEvent": [
    "created",
    "modified"
  ],
  "SubmissionDate": "2025-04-10T12:01:29.231216Z",
  "@odata.context": "$metadata#OData.CSC.Subscription"
}

Przykład: Próba utworzenia subskrypcji przy użyciu niepoprawnego FilterParam

Załóżmy, że przez pomyłkę próbowaliśmy utworzyć subskrypcję z niepoprawnym zapytaniem, na przykład używając Colection/Name zamiast Collection/Name:

Colection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')

Treść żądania, które wyślemy, zawiera to niepoprawne zapytanie:

{
    "SubscriptionType": "push",
    "StageOrder": true,
    "FilterParam": "Colection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created"
    ],
    "NotificationEndpoint": "https://example.com:8000/catalogue-notifications",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

Tak jak poprzednio, wysyłamy to żądanie na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions

W odpowiedzi otrzymujemy kod 400 Bad Request oraz następujące dane JSON:

{
    "detail": "Your filter is incorrect. We suggest to verify it with catalogue API. Detailed error message -> Invalid field: Colection"
}

Ta odpowiedź będzie się różnić w zależności od rodzaju błędu popełnionego w zapytaniu.

Co dzieje się po utworzeniu subskrypcji push?

Jeśli twoje żądanie HTTP zakończyło się powodzeniem, subskrypcja powinna zostać utworzona.

Jeśli ta subskrypcja jest aktywna, twój punkt końcowy powiadomień (zobacz Wymaganie wstępne nr 5) będzie otrzymywał powiadomienie za każdym razem, gdy wystąpi odpowiednie zdarzenie. Powiadomienie to będzie zawierało szczegóły dotyczące produktu powiązanego ze zdarzeniem.

Przykładowe powiadomienie jest zbyt długie, aby opublikować je w całości w tym artykule. Dlatego udostępniliśmy je jako plik JSON do pobrania:

example-notification-push.json

Tak wygląda tablica value -> Attributes:

Zaczyna się ona w wierszu 67 i kończy w wierszu 193, podczas gdy cały plik ma 221 wierszy; czerwony prostokąt po prawej stronie ilustracji pokazuje pozycję tablicy Attributes proporcjonalnie do długości całego tekstu.

Objaśnienie kluczy w powiadomieniu

Push notification entity description table

Nazwa właściwości	Typ	Opis
AckId	Guid	Identyfikator potwierdzenia powiadomienia. Może być użyty do jednoznacznej identyfikacji (i potwierdzenia) konkretnego dostarczonego powiadomienia. Przykład 2f93b9d0-39f3-4c59-9a2a-5e3d7b2a5a61
ProductId	Guid	Jest to uniwersalny unikalny identyfikator (UUID) produktu, którego dotyczy powiadomienie. Przykład 8d654e59-d7b6-4a53-b086-c9de764e506b
ProductName	String	Jest to nazwa produktu, którego dotyczy powiadomienie, przypisana w Katalogu. Wartość ProductName może być długa i zwykle nie mieści się w jednej komórce tabeli; konkretny przykład znajduje się pod tabelą.
SubscriptionId	Guid	Jest to uniwersalny unikalny identyfikator (UUID). Id jest lokalnym identyfikatorem instancji Subscription w obrębie Katalogu, przypisywanym podczas tworzenia subskrypcji. Przykład 991c4730-cf6f-432a-9f6c-47be0230ff4
SubscriptionEvent	Subscription Event enumeration	Zdarzenie subskrypcji, które jest monitorowane i dla którego dostarczane jest powiadomienie: created modified created and modified. Aby śledzić oba, wyślij SubscriptionEvent jako tablicę typu `["created","modified"]`. deleted Domyślną wartością ustawioną dla SubscriptionEvent, jeśli użytkownik jej nie poda, jest "created". Dla "SubscriptionEvent" = "created" będą wysyłane powiadomienia o nowo dodanych produktach do katalogu EOData. Dla "SubscriptionEvent" = "modified" będą wysyłane powiadomienia o zaktualizowanych produktach w katalogu EOData. Dla "SubscriptionEvent" = "deleted" będą wysyłane powiadomienia o usuniętych produktach z katalogu EOData. Przykład created
NotificationDate	DateTimeOffset	Data i godzina wygenerowania powiadomienia. Czas jest w formacie ISO 8601 (UTC+0): YYYYMM-DDThh:mm:ss.sssZ Przykład 2024-01-29T10:59:08.698Z
value	JSON object	Zawiera standardową odpowiedź API katalogu ze wszystkimi metadanymi i szczegółami dotyczącymi zawartości produktu.

Przykład ProductName

S2A_MSIL2A_20240129T062121_N0510_R034_T44VMN_20240129T093752.SAFE

Zmiana statusu subskrypcji push i punktu końcowego

W tej sekcji dowiesz się, jak edytować istniejącą subskrypcję push. Może to być potrzebne na przykład wtedy, gdy chcesz wstrzymać lub wznowić taką subskrypcję albo wiesz, że wkrótce utracisz dostęp do obecnego punktu końcowego powiadomień.

W przypadku subskrypcji push możesz edytować następujące właściwości:

Status: Status subskrypcji — running, paused lub cancelled. Ustawienie statusu subskrypcji na cancelled usuwa tę subskrypcję.
NotificationEndpoint: Adres URL twojego punktu końcowego wraz z portem, pod którym jest dostępny.
NotificationEpUsername: Nazwa użytkownika skonfigurowana w twoim punkcie końcowym, używana do wysyłania do niego powiadomień.
NotificationEpPassword: Hasło skonfigurowane w twoim punkcie końcowym, używane do wysyłania do niego powiadomień.

Aby wykonać taką edycję, wyślij żądanie HTTP PATCH z treścią będącą obiektem JSON zawierającym wszystkie parametry, które chcesz zmienić.

Informacja

Nie musisz uwzględniać wszystkich parametrów; wystarczą tylko te, które chcesz zmienić.

To jest adres URL, na który należy wysłać żądanie. Zastąp w nim <<subscription_id>> identyfikatorem swojej subskrypcji.

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(<<subscription_id>>)

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

Odpowiedź będzie się różnić w zależności od wybranych opcji.

Jeśli:

edytujesz właściwości, takie jak punkt końcowy powiadomienia lub status, oraz

nie ustawiasz statusu na cancelled,

powinieneś otrzymać odpowiedź 200 OK oraz obiekt JSON zawierający zaktualizowane informacje o twojej subskrypcji.

Jeśli ustawisz status subskrypcji na cancelled, twoja subskrypcja powinna zostać usunięta i powinieneś otrzymać kod 204 No Content.

Przykład: Edycja nieniszcząca

Załóżmy, że mamy subskrypcję push o identyfikatorze 6d73b84b-93c6-42aa-8c87-036585cfce04 i chcemy zmienić punkt końcowy, do którego wysyłane są powiadomienia. Dokładniej:

zmienić punkt końcowy powiadomień na https://example.org,

zmienić nazwę użytkownika używaną do uwierzytelniania w tym punkcie końcowym na John, a także

zmienić hasło używane do uwierzytelniania w tym punkcie końcowym na MyTestPassword321,

To jest obiekt JSON, który dołączymy jako treść naszego żądania HTTP PATCH, aby osiągnąć ten cel:

{
    "NotificationEndpoint": "https://example.org",
    "NotificationEpUsername": "John",
    "NotificationEpPassword": "MyTestPassword321"
}

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

Wysyłamy to żądanie na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(6d73b84b-93c6-42aa-8c87-036585cfce04)

Otrzymujemy kod 200 OK, a także następujący obiekt JSON:

{
  "Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
  "SubscriptionType": "push",
  "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
  "StageOrder": false,
  "Priority": 1,
  "Status": "paused",
  "NotificationEndpoint": "https://example.org",
  "SubscriptionEvent": [
    "created",
    "modified"
  ],
  "SubmissionDate": "2025-04-10T12:01:29.231216Z",
  "@odata.context": "$metadata#OData.CSC.Subscription"
}

Chociaż nie zawiera on nowych danych uwierzytelniających, możemy w nim zobaczyć nowy punkt końcowy.

Przykład: Ustawienie statusu subskrypcji na cancelled

Załóżmy, że chcemy usunąć subskrypcję z powyższego przykładu, ustawiając jej status na cancelled.

W tym celu użyjemy następującego obiektu JSON jako treści żądania HTTP PATCH:

{
   "Status": "cancelled"
}

Adres URL pozostaje taki sam:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(6d73b84b-93c6-42aa-8c87-036585cfce04)

Otrzymujemy kod 204 No Content. Nasza subskrypcja powinna zostać teraz usunięta.

Wyświetlanie bieżących subskrypcji

Aby wyświetlić listę wszystkich subskrypcji aktualnie powiązanych z twoim kontem, wyślij żądanie GET na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions/Info

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

Status odpowiedzi powinien mieć wartość 200 OK. Powinieneś otrzymać listę bieżących subskrypcji. Obejmuje ona:

subskrypcje push, a także

subskrypcje pull.

Oto przykład:

[
  {
    "Id": "0a449cc9-d6d4-4db7-af6a-d10105bedd2b",
    "SubscriptionType": "push",
    "FilterParam": "Collection/Name eq 'SENTINEL-2' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'S2MSI2A')",
    "StageOrder": false,
    "Priority": 1,
    "Status": "paused",
    "NotificationEndpoint": "https://example.com/notification",
    "SubscriptionEvent": [
      "created"
    ],
    "SubmissionDate": "2025-04-10T13:11:11.203179Z",
    "@odata.context": "$metadata#OData.CSC.Subscription"
  },
  {
    "Id": "e9d0b04b-cb58-4963-814c-e6d81be4219e",
    "SubscriptionType": "pull",
    "FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
    "StageOrder": false,
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
      "created",
      "modified"
    ],
    "SubmissionDate": "2025-04-10T13:13:51.988546Z",
    "@odata.context": "$metadata#OData.CSC.Subscription"
  }
]

W tym przykładzie widzimy, że użytkownik ma dwie subskrypcje:

subskrypcję push śledzącą produkty created

subskrypcję pull śledzącą zarówno produkty created, jak i modified

Subskrypcja push, w przeciwieństwie do subskrypcji pull, zawiera klucz NotificationEndpoint, który pokazuje adres URL punktu końcowego, do którego mają być dostarczane powiadomienia.

Więcej informacji o subskrypcjach pull znajdziesz tutaj Subskrypcje pull do katalogu EODATA na NSIS Cloud

Jeśli obecnie nie masz żadnych subskrypcji, zapytanie powinno zwrócić pustą listę:

[]

Przykład: Wyświetlanie subskrypcji przy użyciu Pythona

Oto kompletny kod Pythona służący do wyświetlania subskrypcji:

import requests
import json

access_token = "" # paste token here

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {access_token}",
}

url = "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions/Info"

response = requests.get(url=url, headers=headers)

print(f"{response.status_code} {response.reason}\n")
try:
    print(json.dumps(json.loads(response.text), indent=4))
except Exception as e:
    print(e)
    print(response.text)

Ten skrypt:

Wysyła żądanie HTTP na wskazany adres URL.

Pobiera i wyświetla wynik, który składa się z:

Kodu odpowiedzi (np. 200) i powodu (np. OK).

Pustego wiersza (dla czytelności).

Treści odpowiedzi, jeśli występuje. (Jeśli jest to poprawny JSON, zostanie sformatowany tak, aby był bardziej czytelny.)

Przypisz token Keycloak uzyskany zgodnie z Wymaganiem wstępnym nr 4 do zmiennej access_token.

Zapisz plik jako http_request_test_list.py

Aby uruchomić ten skrypt, wykonaj następujące polecenie (zakładając, że znajdujesz się w tym samym katalogu co skrypt):

python3 http_request_test_list.py

python http_request_test_list.py

Usuwanie subskrypcji

Metoda 1: Wysłanie żądania HTTP DELETE

Wyślij żądanie DELETE na poniższy adres URL. Zastąp w nim <<subscription_id>> identyfikatorem subskrypcji, którą chcesz usunąć.

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(<<subscription_id>>)

PRZYPOMNIENIE: Dołącz obowiązkowe nagłówki.

Powinieneś otrzymać status odpowiedzi: 204 No Content.

Lista subskrypcji (zgodnie z opisem w sekcji Wyświetlanie bieżących subskrypcji tego artykułu) powinna pokazać, że ta subskrypcja już nie istnieje.

Metoda 2: Zmiana statusu subskrypcji na cancelled

Ten proces opisano w sekcji Zmiana statusu subskrypcji push i punktu końcowego tego artykułu.

Co można zrobić dalej?

Po otrzymaniu powiadomienia możesz chcieć pobrać ten produkt. Sposoby osiągnięcia tego celu obejmują:

Skopiowanie produktu z folderu /eodata na maszynie wirtualnej działającej w chmurze NSIS Cloud: Jak zamontować eodata przy użyciu s3fs w systemie Linux na NSIS Cloud. Wartość klucza S3Path w powiadomieniu zawiera lokalizację tego produktu w repozytorium EODATA.
Pobranie produktu zgodnie z opisem w Użycie curl i wget do pobierania produktów EODATA z NSIS Cloud. Wartość klucza ProductId zawiera identyfikator produktu, którego możesz użyć do pobrania, zgodnie z opisem w tym artykule.

Poniższe artykuły opisują niektóre z dostępnych sposobów przetwarzania EODATA: