• »
  • EODATA »
  • Subskrypcje pull dla katalogu NSIS EODATA

Subskrypcje pull 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 pull subscriptions. Dla każdej z tych subskrypcji tworzona jest oparta na chmurze kolejka do przechowywania powiadomień przychodzących. Użytkownicy mogą przeglądać, zapisywać i usuwać powiadomienia z tej kolejki.

Istnieją również tak zwane subskrypcje push, które są metodą otrzymywania powiadomień z katalogu NSIS Cloud EODATA bezpośrednio do punktu końcowego zarządzanego przez użytkownika. Są one opisane w artykule 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

Powinno ono również zainstalować interpreter Pythona, 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 na ten temat zawierają artykuły:

Wprowadzenie

Co powinno zawierać żądanie HTTP?

Subskrypcje pull 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 żądania HTTP muszą również zawierać treść JSON.

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.

Podstawowe informacje o subskrypcjach pull

Subskrypcja Pull tworzy kolejkę, w której będą pojawiać się powiadomienia. Każde z tych powiadomień będzie informować o zdarzeniu występującym w katalogu, które spełnia kryteria określone podczas tworzenia tej subskrypcji. Ta kolejka jest przechowywana na serwerach API.

Pełną lub częściową zawartość tej kolejki (w zależności od okoliczności) można wyświetlić, wysyłając żądanie HTTP - odpowiedź zostanie zwrócone jako JSON.

Aby usunąć powiadomienie z kolejki, należy je potwierdzić (ACK), wysyłając żądanie HTTP. To żądanie wyczyści również wszystkie powiadomienia, które zostały otrzymane chronologicznie przed nim.

Kolejka przechowuje do 100000 takich powiadomień. Jeśli będzie ich więcej, najstarsze powiadomienia zostaną usunięte, aby zrobić miejsce dla nowszych. Dlatego należy regularnie przeglądać powiadomienia i odpowiadać na nie.

Opis jednostki subskrypcji pull

Opis jednostki subskrypcji pull table
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
The default value set to SubscriptionEvent, if not provided by the user, is "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 produkt
  • Produkt przestarzały lub innyr

Przykład
created
FilterParam String Parametry filtrowania subskrypcji.

Jeśli "SubscriptionEvent" = "created" lub "modified", to zapytanie odnosi się do parametru $filter= w dowolnym zapytaniu typu Products.

Jeśli "SubscriptionEvent" = "deleted", to zapytanie odnosi się do parametru $filter= w dowolnym zapytaniu DeletedProducts.

Dostępne są te same parametry filtrowania, które zostały opisane dla EOData Catalogue – patrz 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.

Przykład
1


Ograniczenia subskrypcji

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

  • dwie subskrypcje pull (opisane w tym artykule) lub

  • dwie subskrypcje push (które są opisane w artykule /eodata/Push-subscriptions- to-NSIS-EODATA-catalogue), lub

  • jedna subskrypcja pull i jedna subskrypcja push.

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 pull

Typowa zawartość żądania utworzenia subskrypcji pull 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"
    ]
}

Ustaw własne wartości dla następujących trzech 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 3.

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.

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ć postać 201 Created. Odpowiedź powinna zawierać następujące dane JSON:

{
    "Id": "991c4730-cf6f-432a-9f6c-47be0230ff45",
    "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": true,
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created"
    ],
    "SubmissionDate": "2024-03-13T09:39:49.404Z",
    "@odata.context": "$metadata#Subscriptions/$entity"
}

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

Oto kod w języku Python, 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"
    ]
}

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 4 do zmiennej access_token.

Zapisz plik jako http_request_test_create.py.

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

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 odpowiedź jak poniżej:

{
    "@odata.context": "$metadata#OData.CSC.Subscription",
    "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')",
    "Id": "3de3bcf4-4990-4e7f-8d89-67d80deb378c",
    "Priority": 1,
    "StageOrder": false,
    "Status": "running",
    "SubmissionDate": "2025-03-18T17:46:01.709952Z",
    "SubscriptionEvent": [
        "created",
        "modified"
    ]
}

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

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.

Wyświetlanie kolejki

Aby wyświetlić najstarsze powiadomienia w kolejce, wyślij żądanie GET na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(<<subscription_id>>)/Read$top=20

Zastąp <<subscription_id>> identyfikatorem subskrypcji.

Parametr $top określa liczbę najstarszych powiadomień, które mają być wyświetlone, przy czym maksymalny limit to 20. Jeśli nie zostanie podany, domyślnie przyjmuje się wartość 1.

Jeśli liczba powiadomień w kolejce jest mniejsza lub taka sama jak wartość parametru $top, otrzymasz wszystkie powiadomienia.

Przykładowym żądaniem może być żądanie GET dla następującego adresu URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(991c4730-cf6f-432a-9f6c-47be0230ff45)/Read?$top=2

W zależności od okoliczności odpowiedź będzie różna.

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

Subskrypcja została anulowana

Proces anulowania subskrypcji faktycznie ją usuwa. Dlatego też, jeśli spróbujesz wyświetlić kolejkę powiadomień takiej subskrypcji, otrzymasz kod odpowiedzi 404 Not Found z następującymi danymi JSON:

{
    "detail": {
        "message": "Subscription with id 991c4730-cf6f-432a-9f6c-47be0230ff45 not found.",
        "request_id": "aed89ead-b495-4f76-b6e9-51870973a44e"
    }
}

Subskrypcja jest aktywna lub wstrzymana

Jeśli subskrypcja jest w stanie**Active** lub Paused, otrzymasz tablicę obiektów JSON, z których każdy reprezentuje powiadomienie. Kod odpowiedzi powinien wtedy mieć postać 200 OK.

Każdy z tych obiektów zawiera następujące informacje:

  • powiadomienie,

  • produkt, jak również

  • subskrypcję.

Pełna treść powiadomienia jest przechowywana w kolejce użytkowników przez trzy dni. Po tym czasie klucze value i ProductName są usuwane.

Przykład 1

Poniższy plik JSON do pobrania

example-notification.json

zawiera pomyślną odpowiedź dla SubscriptionEvent ustawioną na created (status 200 OK).

Pełna odpowiedź jest zbyt długa, aby opublikować ją dosłownie w tym artykule.

../_images/pull-subscriptions-01_creodias1.png

Oto jak wygląda tablica value -> Attributes. Zaczyna się ona w wierszu 67 i kończy w wierszu 248, podczas gdy cały plik ma 293 linie; czerwony prostokąt po prawej stronie ilustracji pokazuje pozycję tablicy Attributes proporcjonalnie do długości całego tekstu.

Przykład 2

Oto przykład pomyślnej odpowiedzi (status 200 OK) dla SubscriptionEvent ustawionego na modified. Pominięte wartości to:

  • value -> GeoFootprint -> coordinates

  • value -> Attributes

  • value -> Locations

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "modified",
        "ProductId": "b6801a5d-0e66-43d7-afac-1280f0895bf1",
        "ProductName": "S1A_IW_SLC__1SDV_20241123T044906_20241123T044930_056677_06F42F_97B3.SAFE",
        "SubscriptionId": "991c4730-cf6f-432a-9f6c-47be0230ff45",
        "NotificationDate": "2025-02-10T08:30:48.905365Z",
        "AckId": "MTcxMDc1NjcwNjUzMi0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==",
        "value": {
            "@odata.context": "$metadata#Products(Attributes(),Assets(),Locations())/$entity",
            "@odata.mediaContentType": "application/octet-stream",
            "Id": "b6801a5d-0e66-43d7-afac-1280f0895bf1",
            "Name": "S1A_IW_SLC__1SDV_20241123T044906_20241123T044930_056677_06F42F_97B3.SAFE",
            "ContentType": "application/octet-stream",
            "ContentLength": 8217756705,
            "OriginDate": "2024-11-23T06:28:41.550000Z",
            "Checksum": [
                {
                    "Value": "40fbe8ddd886f24a323906af1e442155",
                    "Algorithm": "MD5",
                    "ChecksumDate": "2024-11-23T06:37:33.947488Z"
                },
                {
                    "Value": "5c128944c135faefd8eb15b28f776541c1e4d0b21fa5064906b1882ca590527e",
                    "Algorithm": "BLAKE3",
                    "ChecksumDate": "2024-11-23T06:37:43.810075Z"
                }
            ],
            "ContentDate": {
                "Start": "2024-11-23T04:49:06.776458Z",
                "End": "2024-11-23T04:49:30.129633Z"
            },
            "Footprint": "geography'SRID=4326;POLYGON ((15.389621 5.429769, 15.680731 6.842505, 13.45454 7.296846, 13.16956 5.8881, 15.389621 5.429769))'",
            "GeoFootprint": {
                "type": "Polygon",
                "coordinates": []
            },
            "Attributes": [],
            "ModificationDate": "2025-02-10T08:30:48.665109Z",
            "PublicationDate": "2024-11-23T06:36:54.654519Z",
            "Online": true,
            "EvictionDate": "2025-03-12T08:28:16.409489Z",
            "S3Path": "/eodata/Sentinel-1/SAR/IW_SLC__1S/2024/11/23/S1A_IW_SLC__1SDV_20241123T044906_20241123T044930_056677_06F42F_97B3.SAFE",
            "Assets": [
                {
                    "Type": "QUICKLOOK",
                    "Id": "b43f60cb-3869-4c1d-b1e5-336e0d057f43",
                    "DownloadLink": "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Assets(f4cfe4c9-5b56-47c2-87ce-05b090c7a4ba)/$value",
                    "S3Path": "/eodata/Sentinel-1/SAR/IW_SLC__1S/2024/03/13/S1A_IW_SLC__1SDV_20240313T054626_20240313T054653_052959_066921_3759.SAFE"
                }
            ],
            "Locations": []
        }
    }
]

Przykład 3

To jest przykład pomyślnej odpowiedzi (status 200 OK) dla SubscriptionEvent ustawionego na deleted.

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "deleted",
        "ProductId": "232d796a-0552-4679-a1ed-b8cd3d002db2",
        "ProductName": "S1A_IW_SLC__1SDV_20241111T044907_20241111T044931_056502_06ED2E_7F0A",
        "SubscriptionId": "991c4730-cf6f-432a-9f6c-47be0230ff45",
        "NotificationDate": "2025-02-10T08:30:04.127132Z",
        "AckId": "MTcxMDc1NjcwNjUzMi0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==",
        "value": {
            "@odata.context": "$metadata#DeletedProducts(Attributes())/$entity",
            "@odata.mediaContentType": "application/image-tiff",
            "Id": "232d796a-0552-4679-a1ed-b8cd3d002db2",
            "Name": "S1A_IW_SLC__1SDV_20241111T044907_20241111T044931_056502_06ED2E_7F0A",
            "ContentType": "application/image-tiff",
            "ContentLength": 999999,
            "OriginDate": "2025-02-10T08:28:16.409494Z",
            "Checksum": [
                {
                    "Value": "1efb9cf89aa30086e114705c20831606",
                    "Algorithm": "MD5",
                    "ChecksumDate": "2025-02-10T08:28:16.409494Z"
                },
                {
                    "Value": "7a8e7280a1b37f14ecf6cf9216ec3f9e3824e5a7098d266168b8ce6b32598551",
                    "Algorithm": "BLAKE3",
                    "ChecksumDate": "2025-02-10T08:28:16.409494Z"
                }
            ],
            "Footprint": "geography'SRID=4326;POLYGON ((14.412463 5.424546, 15.703652 6.837446, 13.453771 7.296696, 13.168763 5.887819, 14.412463 5.424546))'",
            "GeoFootprint": {
                "type": "Polygon",
                "coordinates": []
                },
                "ContentDate": {
                    "Start": "2025-02-09T08:28:16.409468Z",
                    "End": "2025-02-10T08:28:16.409494Z"
                },
                "Attributes": [],
                "DeletionDate": "2025-02-10T08:30:03.907283Z",
                "DeletionCause": "Corrupted product"
            }
        }
    }
]

Przykład 4

Przykład pomyślnej odpowiedzi (status 200 OK) lub powiadomień starszych niż 3 dni:

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "d2ff986b-9454-43d6-95e0-1a0ae27019d7",
        "SubscriptionId": "991c4730-cf6f-432a-9f6c-47be0230ff45",
        "NotificationDate": "2024-03-13T13:39:59.000Z",
        "AckId": "MTcxMDc1NjcwNjUzMi0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ=="
    },
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "33ad5694-9208-4001-ae4f-6d7cd0579ce0",
        "SubscriptionId": "991c4730-cf6f-432a-9f6c-47be0230ff45",
        "NotificationDate": "2024-03-13T13:39:59.000Z",
        "AckId": "MTcxMDc1NjcwNjY2NC0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ=="
    }
]

Przykład 5

Jeśli nie masz żadnych powiadomień w kolejce, powinien zostać zgłoszony status 200 OK z pustą tablicą:

[]

Objaśnienie kluczy w powiadomieniu

Pull notification entity description table
Nazwa właściwości Typ Opis
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
Domyślna wartość ustawiona dla SubscriptionEvent, jeśli użytkownik jej nie określi, to "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.sssZZ

Przykład
2024-01-29T10:59:08.698Z
AckId String Id potwierdzenia (Acknowledge Id) przypisany do każdej notyfikacji produktu. Wymagany do potwierdzania komunikatów notyfikacyjnych z kolejki klienta.

Ponieważ AckId jest długi, jego przykład znajduje się poniżej tej tabeli.
value 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

Przykład AckID

MTcxMDc1NjcwNjUzMi0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==

Potwierdzanie powiadomień

Potwierdzenie (acking) powiadomienia usuwa (z kolejki) zarówno to powiadomienie, jak i wszystkie powiadomienia, które pojawiły się chronologicznie przed nim.

Aby to zrobić, wyślij żądanie POST na poniższy adres URL. Zastąp:

  • <<subscription_id>> identyfikatorem twojej subskrypcji

  • <<AckId>> z wartością klucza AckId dla powiadomienia znalezionego w kolejce powiadomień

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(<<subscription_id>>)/Ack?$ackid=<<AckID>>

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

Może to być na przykład żądanie POST na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(991c4730-cf6f-432a-9f6c-47be0230ff45)/Ack?$ackid=MTcxMDc1NjcwNjY2NC0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==

Powinna zostać zwrócona odpowiedź 200 OK. Odpowiedź powinna również zawierać dane JSON jak poniżej:

{
     "@odata.context": "$metadata#Notification/$entity",
     "AckMessagesNum": 2,
     "CurrentQueueLength": 2115,
     "MaxQueueLength": 100000
}

który zawiera następujące informacje:

Pull subscription ack confirmation
Klucz Typ Opis
AckMessagesNum Int64 To liczba powiadomień które zostały odebrane przez twoje zapytanie.
CurrentQueueLength Int64 To Liczba powiadomien obecnie znajdujących się w twojej kolejce.
MaxQueueLength Int64 To maksymalna liczba powiadomień jakie mogą być przechowywane w twojej kolejce.


Jeśli subskrypcja została wcześniej anulowana, powinien zostać zwrócony kod odpowiedzi 404 Not Found i dane JSON jak poniżej:

{
    "detail": {
        "message": "Subscription with id 991c4730-cf6f-432a-9f6c-47be0230ff4 not found.",
        "request_id": "ae19864a-5bda-4893-9f02-a62eba95fd7a"
    }
}

Używanie ack do odczytywania dalszych powiadomień

Żądanie używane do przeglądania kolejki może zwrócić tylko do 20 najstarszych powiadomień. Maksymalna liczba powiadomień, które mogą znajdować się w kolejce, wynosi 100000. Dlatego to żądanie może być niewystarczające do pobrania wszystkich powiadomień.

Aby przeczytać pozostałe wiadomości, można użyć ack:

  • Wyświetl aktualną listę powiadomień - ustaw parametr $top na 20.

  • W razie potrzeby zapisz te powiadomienia.

  • Potwierdź (Ack) ostatnie z nich.

Ponownie popatrz na aktualną listę powiadomień - powinna ona teraz zawierać powiadomienia, które pojawiły się po powiadomieniu, które zostało potwierdzone poleceniem ack. Jeśli w kolejce znajduje się więcej niż 20 powiadomień, powinny teraz zostać wyświetlone powiadomienia, których wcześniej tam nie było.

W razie potrzeby ponownie zapisz powiadomienia i potwierdź (ack) ostatnie z nich.

Rób to, aż kolejka będzie pusta.

Zmiana status subskrypcji pull

W przypadku subskrypcji pull można jedynie zmienić jej status.

Subskrypcja może mieć jeden z następujących statusów:

  • running - subskrypcja otrzymuje nowe powiadomienia

  • paused - subskrypcja tymczasowo nie otrzymuje nowych powiadomień.

  • cancelled - ustawienie tego statusu zawiesza i usuwa subskrypcję.

Aby edytować status subskrypcji, wyślij żądanie HTTP PATCH z następującą treścią (zastąp <<new_status>> statusem, który chcesz ustawić dla subskrypcji):

{
    "Status": "<<new_status>>"
}

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

Wyślij to żądanie na poniższy adres URL (zastąp <<subscription_id>> identyfikatorem subskrypcji, którą chcesz edytować).

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

Powinna zostać zwrócona odpowiedź z zaktualizowanymi informacjami o subskrypcji, wraz z kodem odpowiedzi 200 OK. Wyjątkiem jest ustawienie statusu na cancelled - powinno to dać kod odpowiedzi 204 No content.

Przykład: Nieniszcząca zmiana statusu subskrypcji pull

Jeśli identyfikator subskrypcji to 7ca682c3-7b21-4e9b-952e-874798181340 i chcesz ustawić jej status na wstrzymany, użyj następującej treści żądania HTTP POST:

{
    "Status": "paused"
}

Adres URL jest następujący:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(7ca682c3-7b21-4e9b-952e-874798181340)

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

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(7ca682c3-7b21-4e9b-952e-874798181340)

Otrzymujemy kod odpowiedzi 204 No Content. 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 pull, a także

  • subskrypcje push.

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 NotificationEndpoint, który wskazuje adres URL punktu końcowego, do którego mają być dostarczane powiadomienia. Więcej informacji na temat tego typu subskrypcji zawiera artykuł: Subskrypcje push dla katalogu NSIS EODATA

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

[]

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 4 do zmiennej access_token.

Zapisz plik jako http_request_test_list.py.

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 status subskrypcji pull niniejszego artykułu.

Subskrypcja pull - przykładowy przepływ pracy

W tej sekcji omówimy przykładowy przepływ pracy z subskrypcją pull.

Tworzenie subskrypcji

Zacznijmy od listy subskrypcji powiązanych z naszym kontem.

Robimy to, wysyłając żą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.

To żądanie zwraca kod statusu 200 OK i pustą tablicę. Oznacza to, że nasze konto nie ma jeszcze żadnych subskrypcji:

[]

Teraz tworzymy naszą pierwszą subskrypcję. Będzie ona śledzić produkty dodawane do katalogu. Użyjemy następującego filtra:

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') and Online eq true and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value gt 0) and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value lt 100000) and OData.CSC.Intersects(area=geography'SRID=4326;POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000))')

To zapytanie śledzi produkty, które:

  • należy do kolekcji SENTINEL-2

  • mają następujący typ produktu: IW_SLC__1S

  • mają parametr Online ustawiony na true.

  • mają parametr orbitNumber większy niż 0

  • mają parametr orbitNumber mniejszy niż 100000

  • przecinają następujący wielokąt: POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000)).

Treść żądania, które wysyłamy, aby osiągnąć ten cel, jest następująca:

{
    "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') and Online eq true and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value gt 0) and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value lt 100000) and OData.CSC.Intersects(area=geography'SRID=4326;POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000))')",
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
        "created"
    ]
}

Organ ten zawiera informacje o naszej subskrypcji, takie jak:

FilterParam

Zapytanie do katalogu, które filtruje produkty.

Status

Status tworzonej subskrypcji (chcemy, aby subskrypcja zaczęła działać natychmiast po jej utworzeniu, więc ustawiamy ją na running).

SubscriptionEvent

Typ zmian w katalogu chcesz śledzić. Aby uzyskać więcej informacji, zobacz tabelę w sekcji Opis jednostki subskrypcji pull tego artykułu. W tym przykładzie wybraliśmy created, ponieważ chcemy otrzymywać powiadomienia o tworzonych produktach.

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

Wysyłamy to żądanie na ten adres URL:

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

Po wysłaniu żądania otrzymujemy kod statusu 201 Created i następujący obiekt JSON:

{
    "Id": "32ee6df9-3008-4279-92e6-200828e532d1",
    "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') and Online eq true and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value gt 0) and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value lt 100000) and OData.CSC.Intersects(area=geography'SRID=4326;POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000))')",
    "StageOrder": false,
    "Priority": 1,
    "Status": "running",
    "SubscriptionEvent": [
      "created"
    ],
    "SubmissionDate": "2025-03-26T12:19:03.492271Z",
    "@odata.context": "$metadata#OData.CSC.Subscription"
}

Ten obiekt JSON potwierdza szczegóły dotyczące naszej nowej subskrypcji, takie jak zapytanie używane do filtrowania produktów i typ śledzonych zdarzeń.

Do interakcji z tą subskrypcją będziemy później potrzebować jej identyfikatora, któryn w tym przykładzie jest 32ee6df9-3008-4279-92e6-200828e532d1.

Dane wyjściowe zawierają również potwierdzenie, że Status naszej subskrypcji to running, co oznacza, że powinna ona już być w stanie odbierać powiadomienia.

Aby dokładnie sprawdzić, czy subskrypcja została utworzona, ponownie wyświetlamy listę subskrypcji powiązanych z kontem, wysyłając następujące żą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.

Kod odpowiedzi to ponownie 200 OK. Otrzymane dane to tablica z obiektami, z których każdy reprezentuje jedną subskrypcję.

[
    {
        "Id": "32ee6df9-3008-4279-92e6-200828e532d1",
        "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') and Online eq true and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value gt 0) and Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value lt 100000) and OData.CSC.Intersects(area=geography'SRID=4326;POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000))')",
        "StageOrder": false,
        "Priority": 1,
        "Status": "running",
        "SubscriptionEvent": [
            "created"
        ],
        "SubmissionDate": "2025-03-26T12:19:03.492271Z",
        "@odata.context": "$metadata#OData.CSC.Subscription"
    }
]

Ponieważ mamy teraz jedną subskrypcję, istnieje jeden obiekt. Zawiera on szczegółowe informacje o naszej subskrypcji, które są identyczne z danymi wyjściowymi podczas jej tworzenia.

Jeśli kiedykolwiek zapomnimy jakichś danych o subskrypcji (takich jak jej identyfikator lub użyte zapytanie), możemy wykonać to polecenie, aby ją odzyskać.

Oczywiście, choć można mieć tylko jedną aktywną subskrypcję, można mieć wiele wstrzymanych subskrypcji. To żądanie powinno wyświetlić je wszystkie, jeśli istnieją.

Potwierdzanie jednego powiadomienia

Sprawdźmy teraz kolejkę powiadomień powiązaną z tą subskrypcją. W tym celu wysyłamy żądanie GET na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read$top=20

Ten adres URL zawiera takie dane jak:

  • ID subskrypcji (32ee6df9-3008-4279-92e6-200828e532d1)

  • maksymalna liczba powiadomień, które chcemy zobaczyć (20, ta wartość nie może być wyższa)

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

To żądanie zwraca kod odpowiedzi 200 OK i pustą tablicę jako dane:

[]

Oznacza to, że w kolejce nie ma jeszcze żadnych powiadomień.

Czekamy jakiś czas, aż pojawi się pierwsze powiadomienie.

Następnie ponownie wysyłamy to samo żądanie HTTP. Tym razem również otrzymujemy kod odpowiedzi 200 OK. Tablica, którą otrzymujemy jako odpowiedź, zawiera teraz jedno powiadomienie.

(Wartość klucza JSON value została przycięta - pusta - w celu zwiększenia czytelności).

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "f2587c70-1104-4e92-960b-640495331d2e",
        "ProductName": "S1A_IW_SLC__1SDV_20250326T101553_20250326T101621_058474_073BCB_A673.SAFE",
        "SubscriptionId": "32ee6df9-3008-4279-92e6-200828e532d1",
        "NotificationDate": "2025-03-26T12:20:43.000000Z",
        "AckId": "MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==",
        "value": {
        }
    }
]

Niniejsze powiadomienie ogłasza publikację nazwy produktu:

S1A_IW_SLC__1SDV_20250326T101553_20250326T101621_058474_073BCB_A673.SAFE

Do wykorzystania w przyszłości (np. do przetwarzania) zapisujemy informacje z tego powiadomienia, które nas interesują.

Kiedy już to zrobimy, to powiadomienie nie jest już potrzebne i chcemy je usunąć poprzez acking (potwierdzenie).

W tym celu potrzebujemy identyfikatora AckId powiadomienia, który w tym przykładzie jest następujący:

MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Aby potwierdzić (Ack) to powiadomienie, wysyłamy żądanie POST na poniższy adres URL. W tym adresie URL używamy identyfikatora subskrypcji wraz z AckId:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

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

Zwrócony kod odpowiedzi to 200 OK. Dane JSON pobrane przez to żądanie zawierają informacje o wynikach tej operacji:

{
    "@odata.context": "$metadata#Notification/$entity",
    "AckMessagesNum": 1,
    "CurrentQueueLength": 0,
    "MaxQueueLength": 100000
}

Z tego obiektu JSON dowiadujemy się, że

  • wykonanie tego Ack usunęło 1 powiadomienie (AckMessagesNum)

  • W kolejce pozostaje 0 powiadomień (CurrentQueueLength)

Zawiera on również przypomnienie, że maksymalna liczba powiadomień przechowywanych w kolejce wynosi 100000 (wartość klucza MaxQueueLength).

Ponownie sprawdzamy bieżącą kolejkę powiadomień, wysyłając żądanie GET na poniższy adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read$top=20

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

Żądanie zwraca kod odpowiedzi 200 OK i pustą tablicę JSON jako dane:

[]

Wcześniej mieliśmy jedno powiadomienie. Usunęliśmy to powiadomienie przez jego potwierdzenie (ack) i teraz lista powiadomień jest pusta.

Odbieranie wielu powiadomień jednocześnie

Teraz czekamy, aż nasza kolejka zostanie zapełniona większą liczbą powiadomień.

Następnie sprawdzamy kolejkę powiadomień, wysyłając żądanie GET pod ten sam adres URL, co poprzednio:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read$top=20

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

Otrzymujemy kod odpowiedzi 200 OK i trzy powiadomienia. Zauważ, że wartość klucza value została przycięta w celu zwiększenia czytelności.

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "ea5e8c98-a3bd-4cab-86c9-7ea48f21f356",
        "ProductName": "S1A_IW_SLC__1SDV_20250326T101258_20250326T101325_058474_073BCA_A4FE.SAFE",
        "SubscriptionId": "32ee6df9-3008-4279-92e6-200828e532d1",
        "NotificationDate": "2025-03-26T12:21:27.000000Z",
        "AckId": "MTc0Mjk5MTY4NzE1MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==",
        "value": {
        }
    },
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "9ab913a7-0445-4466-9825-90a36c9541e7",
        "ProductName": "S1A_IW_SLC__1SDV_20250326T101323_20250326T101350_058474_073BCA_EAEE.SAFE",
        "SubscriptionId": "32ee6df9-3008-4279-92e6-200828e532d1",
        "NotificationDate": "2025-03-26T12:21:41.000000Z",
        "AckId": "MTc0Mjk5MTcwMTQ5OC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==",
        "value": {
        }
    },
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "a05f5274-cad5-451c-b1d3-b86017251c57",
        "ProductName": "S1A_IW_SLC__1SDV_20250326T101348_20250326T101415_058474_073BCA_6916.SAFE",
        "SubscriptionId": "32ee6df9-3008-4279-92e6-200828e532d1",
        "NotificationDate": "2025-03-26T12:21:59.000000Z",
        "AckId": "MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==",
        "value": {
        }
    }
]

Każde z tych trzech powiadomień reprezentuje jeden produkt. Są one uporządkowane chronologicznie, od najwcześniejszego znacznika czasu, w którym otrzymano powiadomienie (NotificationDate) do najnowszego.

Powiedzmy, że chcemy potwierdzić (Ack) drugie powiadomienie, które zostało wysłane ze znacznikiem czasu: 2025-03-26T12:21:41.000000Z

Jego identyfkator AckId jest następujący:

MTc0Mjk5MTcwMTQ5OC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Aby wykonać tę operację, wysyłamy żądanie POST na ten adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

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

Żądanie zwraca kod odpowiedzi 200 OK i dane JSON, które podsumowują, co stało się w wyniku tego żądania:

{
    "@odata.context": "$metadata#Notification/$entity",
    "AckMessagesNum": 2,
    "CurrentQueueLength": 1,
    "MaxQueueLength": 100000
}

Potwierdzenie Ack powiadomienia usuwa zarówno to powiadomienie, jak i wszystkie powiadomienia, które były przed nim. W tym przypadku było jedno starsze powiadomienie niż to, które zostało potwierdzone (Ack), więc oba powiadomienia zostały usunięte. W sumie usunięto dwa powiadomienia - taką wartość pokazuje klucz AckMessagesNum.

W kolejce znajdowało się również trzecie powiadomienie, które nie zostało usunięte przez ten proces, ponieważ pojawiło się chronologicznie później niż powiadomienie, które zostało potwierdzone (Ack). Powiadomienie to jest liczone w wartości klucza CurrentQueueLength.

Możemy wyświetlić pozostałe powiadomienie, ponownie sprawdzając kolejkę powiadomień. Wysyłamy żądanie GET na ten adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read$top=20

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

Otrzymujemy kod odpowiedzi 200 OK i tablicę z naszym jednym pozostałym powiadomieniem (ponownie, dla zwiększenia czytelności, wartość klucza value została przycięta):

[
    {
        "@odata.context": "$metadata#Notification/$entity",
        "SubscriptionEvent": "created",
        "ProductId": "a05f5274-cad5-451c-b1d3-b86017251c57",
        "ProductName": "S1A_IW_SLC__1SDV_20250326T101348_20250326T101415_058474_073BCA_6916.SAFE",
        "SubscriptionId": "32ee6df9-3008-4279-92e6-200828e532d1",
        "NotificationDate": "2025-03-26T12:21:59.000000Z",
        "AckId": "MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==",
        "value": {
        }
    }
]

Jego identyfkator AckId jest następujący:

MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Aby potwierdzić również to powiadomienie, wysyłamy żądanie POST na ten adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

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

Żądanie ponownie zwraca kod odpowiedzi 200 OK i wyniki tej operacji jako dane JSON:

{
    "@odata.context": "$metadata#Notification/$entity",
    "AckMessagesNum": 1,
    "CurrentQueueLength": 0,
    "MaxQueueLength": 100000
}

Z tego obiektu JSON możemy dowiedzieć się, że było to ostatnie powiadomienie z kolejki. Aby potwierdzić, że jest ona pusta, ponownie sprawdzamy kolejkę powiadomień. Wysyłamy żądanie GET na ten adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read$top=20

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

Jest zwracany kod odpowiedzi 200 OK wraz z pustym plikiem JSON:

[]

Ponieważ usunęliśmy jedyne powiadomienie z tej kolejki, jest ona rzeczywiście pusta.

Usuwanie subskrypcji

Załóżmy teraz, że po pewnym czasie nie potrzebujemy już naszej subskrypcji i chcemy ją usunąć.

Aby to zrobić, wysyłamy żądanie DELETE na następujący adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)

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

Zwracany jest kod odpowiedzi 204 No Content (bez danych JSON).

Aby sprawdzić aktualną listę subskrypcji, wysyłamy żądanie GET na ten adres URL:

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

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

Otrzymujemy kod odpowiedzi 200 OK i pustą tablicę:

[]

Potwierdza to, że na naszym koncie nie pozostały żadne subskrypcje.

Co można zrobić dalej?

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

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