• »
• EODATA »
• Subskrypcje push dla katalogu NSIS EODATA

---

Subskrypcje push dla katalogu NSIS EODATA

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, które wysyłając powiadomienia bezpośrednio do punktu końcowego zarządzanego przez użytkownika.

There are also the so-called pull subscriptions, which are a method of receiving notifications from the NSIS Cloud EODATA catalogue by periodically retrieving them from a dedicated cloud-based queue. They are covered in Subskrypcje push dla katalogu NSIS EODATA.

Co będziemy omawiać

Wymagania wstępne

Nr 1 Konto

Jest wymagane aktywne konto NSIS https://nsis-cloud-innovation.cloudferro.com/login.

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

Aby postępować zgodnie z instrukcjami w tym artykule, musisz mieć metodę wysyłania następujących typów żądań HTTP:

• GET

• POST

• PATCH

• DELETE

w tym odpowiednie nagłówki i treści. Musisz także być w stanie odczytywać odpowiedzi na te żądania.

Ten artykuł będzie zawierał kod w języku Python w dwóch opcjonalnych przykładach. Poza nimi treść pozostaje „neutralna programowo”. Artykuł nie skupia się na samym środowisku Python, ale na żądaniach HTTP, które można wysyłać za pomocą dowolnego oprogramowania:

curl, wget, httpie, JavaScript Fetch API, Axios (Node.js), Netcat/nc, PowerShell Invoke-RestMethod, Go (net/http), Java (HttpClient) itp.

Nr 3 Uruchamianie kodu Python (opcjonalnie).

Aby uruchomić powyższe przykłady. musisz mieć pewne doświadczenie w korzystaniu z języka Python, Podstawy języka Python są poza zakresem tego artykułu.

Oprócz tego musisz mieć zainstalowane środowisko Python i moduł requests.

Jeśli używasz Ubuntu 24.04, aby zainstalować ten moduł, wykonaj polecenie:

sudo apt install python3-requests

aby zainstalować wymagany moduł requests. Powinno ono również zainstalować interpreter języka Python, jeśli jeszcze go nie masz.

Mogą również działać być używane inne systemy operacyjne, ale może być konieczne ich dostosowanie.

Nr 4 Wiedza, jak filtrować produkty

Jeśli chcesz otrzymywać powiadomienia o zmianach tylko dla podzbioru produktów (w przeciwieństwie do otrzymywania danych dla wszystkich produktów), musisz użyć odpowiedniego filtra.

Filtry używane w tym artykule są opisane w artykule /eodata/EOData-Catalog-API- Manual-on-NSIS-Cloud (są one takie same jak filtry używane dla parametru $filter dla OData).

• W przypadku filtrów dotyczących utworzonych i/lub zmodyfikowanych produktów, sprawdź sekcję dotyczącą punktu końcowego OData Products w artykule Podręcznik API katalogu EOData na NSIS.

• W przypadku filtrów dotyczących usuniętych produktów, sprawdź sekcję dotyczącą punktu końcowego OData DeletedProducts w artykule Podręcznik API katalogu EOData na NSIS.

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

Nr 5 Wygenerowany token Keycloak

Aby potwierdzić swoją tożsamość podczas korzystania z subskrypcji pull, wymagany jest token Keycloak. Sposób jego generowania opisuje artykuł Użycie curl i wget do pobierania produktów EODATA z NSIS

Token Keycloak jest ważny tylko przez ograniczony czas; możesz wygenerować nowy token, jeśli obecny wygaśnie i chcesz nadal korzystać z interfejsu API subskrypcji.

Jeśli korzystasz z języka Python lub powłoki Bash i na Twoim koncie włączone jest uwierzytelnianie dwuskładnikowe, możesz również automatycznie wygenerować token Keycloak bez konieczności podawania sześciocyfrowego kodu TOTP. Więcej informacji zawierają artykuły:

• 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.

• 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

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

Musisz mieć fizyczną lub wirtualną maszynę, która będzie służyć jako punkt końcowy. Musi ona mieć publiczny adres IP i dołączoną domenę. Potrzebny jest również otwarty port, na który będą wysyłane powiadomienia.

Do odczytywania przychodzących powiadomień wymagane jest oprogramowanie serwera HTTP z obsługą uwierzytelniania podstawowego. Musi on być zabezpieczony protokołem HTTPS z certyfikatem dostarczonym przez zaufany podmiot. Podmiotem tym może być na przykład jeden z komercyjnych dostawców lub Let’s Encrypt (który zapewnia bezpłatne certyfikaty).

Taki serwer można skonfigurować m.in. na maszynie wirtualnej z systemem Linux działającej w chmurze NSIS, do której dołączony jest floating IP.

Wprowadzenie

Co powinno zawierać żądanie HTTP?

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

Podczas wysyłania żądań HTTP opisanych w tym artykule muszą być zawsze używane następujące elementy:

• Typ żądania (GET, POST, PATCH lub DELETE)

• Nagłówki

• 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 w tym artykule powinny zawierać następujące nagłówki:

{
   "Content-Type": "application/json",
   "Authorization": "Bearer <<access_token>>"
}

gdzie <<access_token>> należy zastąpić tokenem Keycloak z wymagania wstępnego nr 5. Ten token będzie używany do potwierdzenia tożsamości użytkownika.

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

Dane JSON w odpowiedziach

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

Opis jednostki subskrypcji push

Nazwa właściwości	Typ	Opis
Id	Guid	To jest uniwersalny i unikalny identyfikator(UUID). Id to lokalny identyfikator dla instancji subskrypcji w katalogu przypisanym podczas tworzenia subskrypcji Przykład 9249dde5-4838-4a34-8925-bac8c1d53f09c
Status	Subscription Status enumeration	Dozwolone wartości statusu subskrypcji to: running (subksrypcja jest aktywna I wysyła powiadomienia do punktu końcowego) paused (subksrypcja nie wysyła powiadomień do punktu końcowego) cancelled (ustalenie tego statusu wstrzymuje oraz usuwa subskrypcję) Podstawowa wartość ‘Statusu’ jeśli nie podana przez użytkownika to ‘running’. Przykład running
SubscriptionEvent	Subscription Event enumeration	Zdarzenie subskrypcji, które ma być monitorowane i dla którego zostanie wysłane powiadomienie. Może przyjmować następujące wartości: created modified created, modified deleted Domyślna wartość ustawiona dla SubscriptionEvent, jeśli użytkownik jej nie określi, to "created”. Dla wartości "SubscriptionEvent" = "created" będą wysyłane powiadomienia o nowo dodanych produktach do katalogu EOData Catalogue.. Dla wartości "SubscriptionEvent" = "modified" będą wysyłane powiadomienia o zaktualizowanych produktach w katalogu EOData Catalogue. Dla wartości "SubscriptionEvent" = "deleted" będą wysyłane powiadomienia o usuniętych produktach z katalogu EOData Catalogue. Zdarzenie to wystąpi, jeśli zostanie spełniona jedna z poniższych wartości parametru "DeletionCause": Duplikat produktu Brak sumy kontrolnej Uszkodzony product Produkt przestarzały lub inny Przykład created
FilterParam	String	Parametry filtrowania subskrypcji Jeśli"SubscriptionEvent" = "created" lub "modified", to zapytanie odnosi się do parametru $filter= w dowolnym miejscu zapytaniaProducts?. Jeśli "SubscriptionEvent" = "deleted", to zapytanie odnosi się do parametru $filter= w dowolnym miejscu zapytania DeletedProducts. Dostępne są te same parametry filtrowania, które zostały opisane dla EOData Catalogue – zobacz Wymaganie wstępne nr 3 po więcej szczegółów. 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 otrzymania subskrypcji przez katalog.Czas jest podany 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 ostatniego pomyślnego wysłania powiadomienia przez usługę subskrypcji do punktu końcowego użytkownika. Czas jest podany w formacie ISO 8601 (UTC+0): YYYY-MM-DDThh:mm:ss.sssZ Przykład 2024-01-17T09:50:10.654Z
StageOrder	Boolean	Automatyczne zlecanie przygotowania produktów spełniających kryteria subskrypcji. Używane wyłącznie wtedy, gdy wartość parametru SubscriptionEvent to created. Obecnie zamawianie przygotowania produktów nie jest możliwe, ponieważ wszystkie produkty w katalogu EOData Catalogue mają status ustawiony na Online i są dostępne natychmiast, bez konieczności składania zamówienia. Przykład true
Priority	Int64	Priorytet zamówień utworzonych w wyniku subskrypcji Obecnie ustawiany automatycznie na wartość 1, bez możliwości jej zmiany wartości. Przykład 1
Punkt końcowy powiadomień	String	Punkt końcowy użytkownika na który będą wysyłane powiadomienia. Przykład https://notification-endpoint.example.com:4000
NotificationEpUsername	String	Nazwa użytkownika używana do uwierzytelnienia w końcowym adresie powiadomień. Pole obowiązkowe jeśli Punkt końcowy powiadomień wymaga uwierzytelnienia. Przykład mylocalusername
NotificationEpPassword	String	Hasło używane do uwierzytelnienia w końcowym punkcie powiadomień. Pole obowiązkowe jeśli Punkt końcowy powiadomień wymaga uwierzytelnienia. Przykład My%Password#789

https://github.com/cloudferrodocumentation/nsiscloud/blob/main/source/eodata/Push-subscriptions-to-Eumetsat-Elasticity-EODATA-catalogue/Push-subscriptions-to-Eumetsat-Elasticity-EODATA-catalogue.po

Ograniczenia subskrypcji

Twoje konto może mieć tylko 2 (dwie) uruchomione subskrypcje w tym samym czasie. Mogą to być

• dwie subskrypcje push (opisane w tym artykule) lub

• two pull subscriptions (which are described in Subskrypcje push dla katalogu NSIS EODATA), or

• jedna subskrypcja push i jedna subskrypcja pull.

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

• działające i wstrzymane

• push i pull

Tworzenie subskrypcji push

Typowa zawartość żądania utworzenia subskrypcji push wygląda tak:

{
    "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 sześciu kluczy w treści JSON:

SubscriptionEvent

Wartością tego klucza jest tablica zawierająca tylko jeden ciąg znaków. Za pomocą tego ciągu wybierasz, o jakich typach zdarzeń chcesz być powiadamiany. Może ona mieć jedną z następujących wartości:

• created

• modified

• created, modified

• deleted

FilterParam

Zmień wartość klucza FilterParam na zapytanie, które definiuje podzbiór produktów, o których chcesz być otrzymywać powiadomienia. Aby dowiedzieć się więcej, zobacz Wymaganie wstępne nr 4.

Aby uzyskać informacje

• o utworzonych i/lub zmodyfikowanych produktach, użyj tego samego zapytania jak w przypadku punktu końcowego Products.

• Aby uzyskać informacje o usuniętych produktach, użyj tego samego zapytania jak w przypadku punktu końcowego DeletedProducts.

Możesz także otrzymywać powiadomienia o wybranych typach zdarzeń związanych ze wszystkimi produktami z katalogu, a nie tylko z ich podzbiorem. W tym celu można:

• pozostawić wartość klucza FilterParam pustą, lub

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

Status

Jeśli ustawisz wartość tego klucza na running, utworzona subskrypcja natychmiast zacznie otrzymywać powiadomienia. Jeśli jednak chcesz utworzyć wstrzymaną (nieaktywną) subskrypcję 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 próbujesz utworzyć kolejną subskrypcję o tym samym statusie, operacja ta zakończy się niepowodzeniem. Szczegółowe informacje można znaleźć się w sekcji Ograniczenia subskrypcji powyżej.

Aby rozwiązać problem, możesz:

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

• utworzyć nową subskrypcję ze statusem paused.

Punkt końcowy powiadomień

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

NotificationEpUsername

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

NotificationEpPassword

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

Możesz także otrzymywać powiadomienia o wszystkich produktach opublikowanych w katalogu, a nie tylko o ich podzbiorze. W tym celu można:

• pozostawić wartość klucza FilterParam pustą, lub

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

NotificationEpUsername i NotificationEpPassword powinny być bezpieczne i inne niż dane uwierzytelniające używane dla konta NSIS.

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

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

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

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

Kod odpowiedzi na to żądanie powinien mieć wartość 201 Created. Powinny również przesłane dane JSON, które zawierają informacje o twojej nowej subskrypcji, na przykład:

{
  "Id": "0b5aaa72-922f-4b69-ad7f-1ccebc3e824e",
  "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 teraz zostać utworzona.

Przykład: Tworzenie subskrypcji push przy użyciu języka Python

Oto kod w języku Pythoni, który wyśle żądanie z parametrami opisanymi powyżej:

import requests
import json

access_token = ""

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

body = {
    "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/catalogue-notifications:8000",
    "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 do określonego adresu URL.

• Żądanie pobiera i wyświetla wyniki, które zawierają:

  • Kod statusu odpowiedzi (np. 200) i powód (np. OK).

  • Pusty wiersz (dla lepszej czytelności).

  • Kod odpowiedzi, jeśli istnieje. Jeśli jest to prawidłowy kod JSON, zostanie sformatowany, aby był bardziej czytelny.

Należy zauważyć, że w tym skrypcie treść żądania jest wysyłana do modułu requests przy użyciu parametru json.

Przypisz token Keycloak uzyskany zgodnie z wymaganiem wstępnym nr 5 do zmiennej access_token.

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

• Punkt końcowy powiadomień - adres URL punktu końcowego powiadomienia, w tym port, jeśli nie jest to port 443.

• NotificationEpUsername - nazwa użytkownika dla punktu końcowego

• NotificationEpPassword - hasło do 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):

Ubuntu 24.04Windows

python3 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 utworzone, jak i zmodyfikowane produkty 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 POST HTTP z następującą treścią:

{
    "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/catalogue-notifications:8000",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

na adres URL:

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

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

Powinien zostać zwrócony kod statusu 201 Created i poniższy obiekt JSON:

{
  "Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
  "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/catalogue-notifications:8000",
  "SubscriptionEvent": [
    "created",
    "modified"
  ],
  "SubmissionDate": "2025-04-10T12:01:29.231216Z",

Przykład: Próba utworzenia subskrypcji przy użyciu nieprawidłowego parametru FilterParam

Załóżmy, że przypadkowo próbowaliśmy utworzyć subskrypcję z nieprawidłowym 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 nieprawidłowe zapytanie:

{
    "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/catalogue-notifications:8000",
    "NotificationEpUsername": "NotificationEndpointUser",
    "NotificationEpPassword": "My@!Passw0rd"
}

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

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

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

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

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 żądanie HTTP powiodło się, subskrypcja powinna zostać utworzona.

Jeśli ta subskrypcja jest aktywna, punkt końcowy powiadomień (patrz wymaganie wstępne nr 6) otrzyma powiadomienie za każdym razem, gdy wystąpi odpowiednie zdarzenie. Powiadomienie to będzie zawierać informacje szczegółowe dotyczące produktu powiązanego ze zdarzeniem.

Przykładowe powiadomienie jest zbyt długie, aby opublikować je dosłownie w tym artykule, dlatego udostępniliśmy go jako plik JSON do pobrania:

example-notification-push.json

Tablica value -> Attributes wygląda tak:

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

Objaśnienie kluczy w powiadomieniu

Property name	Type	Description
ProductId	Guid	To jest uniwersalny i unikalny identyfikator(UUID) powiadamianego produktu. Przykład 8d654e59-d7b6-4a53-b086-c9de764e506b
ProductName	String	To jest nazwa powiadamianego produktu dopisanego do tego katalogu. Wartość ProductName może być długa i zazwyczaj nie zmieści się w jednym wierszu tabeli; konkretny przykład jest podany poniżej tabeli.
SubscriptionId	Guid	To jest uniwersalny unikatowy identyfikator (UUID). Id to lokalny identyfikator instancji Subskrypcji w Katalogu, przypisywany w momencie jej utworzenia. Przykład 991c4730-cf6f-432a-9f6c-47be0230ff4
SubscriptionEvent	Subscription Event enumeration	Zdarzenie subskrypcji, które ma być monitorowane i dla którego zostanie wysłane powiadomienie.: created modified created, modified deleted The default value set to SubscriptionEvent, if not provided by the user, is "created". Dla "SubscriptionEvent" = "created" będą wysyłane powiadomienia o nowo dodanych produktach do katalogu EOData Catalogue. Dla "SubscriptionEvent" = "modified" będą wysyłane powiadomienia o zaktualizowanych produktach w katalogu EOData Catalogue. Dla "SubscriptionEvent" = "deleted" będą wysyłane powiadomienia o usuniętych produktach z katalogu EOData Catalogue. Przykład created
NotificationDate	DateTimeOffset	Data i godzina wygenerowania powiadomienia. Czas jest podany w formacie ISO 8601 (UTC+0):YYYY-MM-DDThh:mm:ss.sssZ Przykład 2024-01-29T10:59:08.698Z
Wartość	JSON object	Zawiera standardową odpowiedź interfejsu Catalogue API ze wszystkimi metadanymi i szczegółami dotyczącymi treści produktu..

Przykład ProductName

S2A_MSIL2A_20240129T062121_N0510_R034_T44VMN_20240129T093752.SAFE

Zmiana stanu subskrypcji push i punktu końcowego

W tej sekcji dowiesz się, jak edytować istniejącą subskrypcję push. Może to być konieczne, jeśli na przykład chcesz wstrzymać lub cofnąć wstrzymanie takiej subskrypcji lub wiesz, że wkrótce utracisz dostęp do bieżącego punktu końcowego powiadomień.

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

Status

Status subskrypcji - running, paused lub cancelled. Ustawienie statusu subskrypcji na cancelled powoduje usunięcie tej subskrypcji.

Punkt końcowy powiadomień

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

NotificationEpUsername

Nazwa użytkownika skonfigurowana w punkcie końcowym używana do wysyłania do niego powiadomień.

NotificationEpPassword

Hasło skonfigurowane w punkcie końcowym używane do wysyłania do niego powiadomień.

Aby wykonać taką edycję, należy wysłać żądanie PATCH HTTP z treścią będącą obiektem JSON zawierającym wszystkie parametry, które chcemy zmienić.

Informacja

Nie musisz uwzględniać wszystkich parametrów; potrzebujesz tylko tych, które chcesz zmienić.

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

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

strong: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,

powinna zostać zwrócona odpowiedź 200 OK i obiekt JSON zawierający zaktualizowane informacje dotyczące twojej subskrypcji.

Jeśli ustawisz status subskrypcji na cancelled, subskrypcja powinna zostać usunięta i powinna zostać zwrócona odpowiedź z kodem 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, a mianowicie:

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

• zmienić nazwę użytkownika używaną do uwierzytelniania w tym punkcie końcowym na John, jak również

• 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"
}

strong: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 odpowiedzi 200 OK, a także następujący obiekt JSON:

{
  "Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
  "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 poświadczeń, można w nim zobaczyć nowy punkt końcowy.

Przykład: Ustawienie statusu subskrypcji na anulowany

Powiedzmy, ż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 bez zmian:

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

Otrzymujemy kod odpowiedzi 204 No Conten. Subskrypcja powinna teraz zostać 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

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

Odpowiedź powinna mieć status 200 OK. Powinna zostać wyświetlona lista bieżących subskrypcji. Zawiera ona:

• subskrypcje push, a także

• subskrypcje pull.

Oto przykład:

[
  {
    "Id": "0a449cc9-d6d4-4db7-af6a-d10105bedd2b",
    "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",
    "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 widać, że użytkownik ma dwie subskrypcje:

• subskrypcję push, która śledzi utworzone produkty

• subskrypcję pull, która śledzi zarówno utworzone, jak i zmodyfikowane produkty.

Subskrypcja push, w przeciwieństwie do subskrypcji pull, zawiera klucz Punkt końcowy powiadomień, który wskazuje adres URL punktu końcowego, do którego mają być dostarczane powiadomienia:

Więcej informacji na temat subskrypcji pull można znaleźć w artykule Subskrypcje push dla katalogu NSIS EODATA

Jeśli aktualnie nie masz żadnych subskrypcji, zapytanie powinno zwrócić pustą liste:

[]

Przykład: Wyświetlanie subskrypcji za pomocą języka Python

Oto kompletny kod w języku Python służący do wyświetlania listy subskrypcji:

import requests
import json

access_token = ""

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 do określonego adresu URL.

• Żądanie pobiera i wyświetla wyniki, które zawierają:

  • Kod statusu odpowiedzi (np. 200) i powód (np. OK).

  • Pusty wiersz (dla lepszej czytelności).

  • Kod odpowiedzi, jeśli istnieje. Jeśli jest to prawidłowy kod JSON, zostanie sformatowany, aby był bardziej czytelny.

Przypisz token Keycloak uzyskany zgodnie z wymaganiem wstępnym nr 5 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):

Ubuntu 24.04Windows

python3 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>>)

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

Powinna zostać zwrócona odpowiedź ze statusem 204 No Content.

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

Metoda 2: Zmiana statusu subskrypcji na anulowaną

Ten proces został opisany w sekcji Zmiana stanu subskrypcji push i punktu końcowego niniejszego artykułu.

Co można zrobić dalej?

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

• Skopiowanie produktu z folderu /eodata na maszynie wirtualnej działającej w chmurze NSIS: Jak zamontować eodata przy użyciu s3fs w systemie Linux na NSIS. Wartość klucza S3Path w powiadomieniu zawiera lokalizację tego produktu w repozytorium EODATA.

• Pobranie produktu zgodnie z wyjaśnieniem w artykule Użycie curl i wget do pobierania produktów EODATA z NSIS. Wartość klucza ProductId zawiera identyfikator produktu, którego można użyć do pobrania, jak wyjaśniono w tym artykule.

Artykuły te obejmują niektóre z dostępnych sposobów przetwarzania EODATA:

• Analiza i monitorowanie powodzi przy użyciu języka Python i zdjęć satelitarnych Sentinel-2 na NSIS

• Przykładowy przepływ pracy deep learning przy użyciu vGPU i EO-DATA na NSIS