Pull-Abonnements für den EODATA-Katalog auf CODE-DE-Lab

Funktionsweise von Pull-Abonnements

Mit einem Pull-Abonnement können Sie Änderungen im EODATA-Katalog verfolgen, ohne ihn wiederholt durchsuchen zu müssen.

Beim Erstellen eines Abonnements legen Sie zwei Dinge fest:

  • Umfang: welche Produkte überwacht werden sollen, optional über FilterParam.

  • Ereignisse: welche Änderungen relevant sind: created, modified, deleted oder eine Kombination daraus.

Der Dienst erstellt anschließend eine serverseitige Warteschlange für Ihr Konto und legt passende Benachrichtigungen darin ab, sobald die Ereignisse eintreten.

Beachten Sie Folgendes:

  • Die Warteschlange liegt auf der Plattform und ist daher von jedem verwendeten Client aus verfügbar, etwa vom Browser, mit curl oder mit Python.

  • Read verändert die Warteschlange nicht: Die Operation zeigt Benachrichtigungen an, entfernt sie jedoch nicht.

  • Die API liefert Benachrichtigungen von der ältesten zur neuesten, höchstens 20 pro Leseanfrage.

  • Ack entfernt die ausgewählte Benachrichtigung und alle älteren Benachrichtigungen. Siehe Benachrichtigungen mit Ack bestätigen.

  • Die Warteschlange kann höchstens 100000 Benachrichtigungen enthalten. Ist sie voll, können die ältesten Einträge verworfen werden.

  • Die Nutzdaten einer Benachrichtigung sind zeitlich begrenzt verfügbar: Nach 3 Tagen kann die Plattform Felder wie value und ProductName entfernen, auch wenn Sie die Benachrichtigung nie mit Ack bestätigt haben.

Ack löscht Benachrichtigungen

Das Bestätigen einer Benachrichtigung mit Ack entfernt sie aus der Warteschlange und entfernt außerdem alle älteren Benachrichtigungen.

Ack funktioniert wie das Verschieben eines Cursors: Nach dem Bestätigen einer Benachrichtigung sind alle davor liegenden Benachrichtigungen aus dieser Warteschlange entfernt.

Warnung

Wenn Sie Ack ausführen, bevor Sie die benötigten Informationen gespeichert haben, können diese dauerhaft verloren gehen.

Benachrichtigungen sicher mit Ack bestätigen

Dieser Ablauf sorgt für vorhersehbare Ergebnisse:

  1. Lesen Sie einen Stapel von Benachrichtigungen, zum Beispiel mit $top=20.

  2. Speichern Sie die benötigten Informationen: mindestens ProductId, AckId und NotificationDate sowie ProductName, falls vorhanden.

  3. Bestätigen Sie die neueste Benachrichtigung dieses Stapels mit Ack, also das letzte Element der zurückgegebenen Liste.

Damit setzen Sie einen eindeutigen Fortsetzungspunkt und können weiterlesen, ohne Nachrichten zu überspringen.

Wie häufig sollten Sie abfragen und Ack ausführen?

Die Abfragehäufigkeit hängt vom Anwendungsfall ab:

  • Wenn Benachrichtigungen automatisierte Abläufe auslösen, fragen Sie regelmäßig ab und lassen Sie die Warteschlange nicht unkontrolliert anwachsen.

  • Wenn Sie Änderungen nur gelegentlich verfolgen müssen, können Sie seltener abfragen. Vermeiden Sie jedoch lange Pausen, damit die Warteschlange nicht überläuft.

Voraussetzungen

Nr. 1 Konto

Sie benötigen ein aktives Konto auf CODE-DE-Lab: https://tenant-manager.code-de.org.

Nr. 2 HTTP-Anfragen senden können

Für diese Anleitung benötigen Sie eine Möglichkeit, GET-, POST-, PATCH- und DELETE-Anfragen einschließlich Headern und gegebenenfalls eines JSON-Anfragetexts zu senden.

Sie können einen beliebigen Client verwenden, zum Beispiel:

Nr. 3 Produkte filtern können

Wenn Sie nur Benachrichtigungen zu einer Teilmenge der Produkte erhalten möchten, müssen Sie entsprechende Filter erstellen können.

Filter in Abonnements haben denselben Aufbau wie die Filter in Anleitung zur EODATA-Katalog-API auf CODE-DE-Lab.

  • Für Benachrichtigungen zu created und/oder modified verwenden Sie Filter wie für den Endpunkt Products.

  • Für Benachrichtigungen zu deleted verwenden Sie Filter wie für den Endpunkt DeletedProducts.

Products und DeletedProducts stellen nicht dieselben Felder bereit. Ein Filter, der an einem Endpunkt funktioniert, ist daher am anderen möglicherweise ungültig.

Nr. 4 Erstelltes Keycloak-Token

Pull-Abonnements erfordern die Authentifizierung mit einem Keycloak-Token. Die Erstellung des Tokens ist in Verwenden von curl und wget zum Herunterladen von EO-Daten-Produkten von CODE-DE-Lab beschrieben.

Tokens laufen ab. Erstellen Sie ein neues Token, wenn Ihre Anfragen 401 oder 403 zurückgeben.

Wenn Sie Bash oder Python verwenden und 2FA aktiviert ist, können Sie die Token-Erstellung automatisieren:

API für Pull-Abonnements

Mit einem gültigen Keycloak-Token und einer eindeutigen Abonnementdefinition aus Ereignistypen und optional FilterParam können Sie Pull-Abonnements vollständig über die Abonnement-API verwalten.

API-Kurzübersicht

Bemerkung

Basispfad: /odata/v1 (Host: https://catalogue.code-de.org)

  • Abonnement erstellen: POST /Subscriptions

  • Abonnements auflisten: GET /Subscriptions/Info

  • Warteschlange lesen: GET /Subscriptions(<<subscription_id>>)/Read?$top=20

  • Ack: POST /Subscriptions(<<subscription_id>>)/Ack?$ackid=<<ack_id>>

  • Status ändern: PATCH /Subscriptions(<<subscription_id>>)

  • Abonnement löschen: DELETE /Subscriptions(<<subscription_id>>) (alternativ den Status mit PATCH auf cancelled setzen)

Was muss eine HTTP-Anfrage enthalten?

Sie können Pull-Abonnements durch HTTP-Anfragen erstellen und verwalten. Jede Anfrage muss drei Bestandteile enthalten:

  • Anfragetyp (GET, POST, PATCH oder DELETE)

  • Header

  • URL

Einige HTTP-Anfragen müssen außerdem einen JSON-Anfragetext enthalten.

JSON-Daten in Antworten

Einige der in diesem Artikel beschriebenen Anfragen liefern JSON-Daten. Zur besseren Lesbarkeit sind diese im Artikel mehrzeilig formatiert.

Beschreibung der Pull-Abonnement-Entität

Eigenschaftsname Typ Beschreibung
Id Guid Dies ist ein universell eindeutiger Bezeichner (UUID). Die Id ist ein lokaler Bezeichner für eine Abonnementinstanz innerhalb des Katalogs und wird beim Erstellen des Abonnements vergeben.

Beispiel
9249dde5-4838-4a34-8925-bac8c1d53f09c
SubscriptionType Aufzählung der Abonnementtypen Typ des erstellten Abonnements:
  • pull
  • push

Der Wert muss in Kleinbuchstaben eingegeben werden.

Beispiel
pull
Status Aufzählung der Abonnementstatus Zulässige Statuswerte eines Abonnements sind:
  • running (das Abonnement ist aktiv und legt Benachrichtigungen in Ihrer serverseitigen Warteschlange ab)
  • paused (das Abonnement ist inaktiv und legt keine neuen Benachrichtigungen ab)
  • cancelled (dieser Status löscht das Abonnement und seine Warteschlange)

Wenn der Benutzer keinen Wert für Status angibt, wird standardmäßig running verwendet.

Ein laufendes Abonnement kann nach längerer Inaktivität automatisch auf paused gesetzt werden. Nach längerer Inaktivität kann es auf cancelled gesetzt und dauerhaft gelöscht werden.

Beispiel
running
SubscriptionEvent Aufzählung der Abonnementereignisse Ereignistypen, die überwacht werden sollen und für die Sie Benachrichtigungen erhalten möchten. Zulässige Werte sind:
  • created
  • modified
  • deleted
Sie können ein oder mehrere Ereignisse abonnieren, indem Sie ein Array senden, zum Beispiel:
  • "SubscriptionEvent": ["created"]
  • "SubscriptionEvent": ["created","modified"]

Beispiel
created
FilterParam String Die Filterparameter des Abonnements.

Wenn SubscriptionEvent den Wert created oder modified enthält, bezieht sich diese Abfrage auf den Parameter $filter= einer beliebigen Products?-Abfrage.

Wenn SubscriptionEvent den Wert deleted enthält, bezieht sich diese Abfrage auf den Parameter $filter= einer beliebigen DeletedProducts-Abfrage.

Es stehen dieselben Filterparameter wie für den EODATA-Katalog zur Verfügung. Weitere Informationen finden Sie unter Voraussetzung Nr. 3.

Beispiel
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 Datum und Uhrzeit des Eingangs des Abonnements im Katalog. Die Zeit wird im ISO-8601-Format (UTC+0) angegeben: YYYY-MMDDThh:mm:ss.sssZ

Beispiel
2024-01-17T09:13:04.654Z
LastNotificationDate DateTimeOffset Datum und Uhrzeit der letzten Bestätigung einer Benachrichtigung dieses Abonnements mit Ack. Die Zeit wird im ISO-8601-Format (UTC+0) angegeben: YYYY-MMDDThh:mm:ss.sssZ

Beispiel
2024-01-17T09:50:10.654Z
StageOrder Boolean Beauftragt automatisch die Bereitstellung von Produkten, die dem Abonnement entsprechen.

Wird nur verwendet, wenn SubscriptionEvent den Wert created enthält.

Je nach aktuellem Verhalten der Plattform kann diese Einstellung ignoriert werden, wenn die Produkte bereits unmittelbar verfügbar sind.

Beispiel
true
Priority Int64 Priorität der aus dem Abonnement entstehenden Aufträge.

Je nach aktuellem Verhalten der Plattform kann dieser Wert vom System verwaltet und die Angabe ignoriert werden.

Beispiel
1

Beschränkungen für Abonnements

Ihr Konto kann höchstens 2 (zwei) Abonnements mit dem Status running gleichzeitig haben. Möglich sind:

Ein Konto auf CODE-DE-Lab kann insgesamt höchstens 10 Abonnements haben. Dabei werden alle Arten berücksichtigt:

  • running und paused

  • Push und Pull

Regeln bei Inaktivität:

Wichtig

  • Ein Abonnement mit dem Status running wird nach 60 Tagen Inaktivität automatisch auf paused gesetzt.

  • Nach 365 Tagen seit der letzten Benachrichtigung wird das Abonnement auf cancelled gesetzt und dauerhaft gelöscht.

Wenn Sie ein Abonnement für automatisierte Abläufe verwenden, überwachen Sie es und halten Sie den Ablauf zum Abfragen und Bestätigen aktiv.

Pull-Abonnement erstellen

Beim Erstellen eines Abonnements müssen Sie SubscriptionType angeben.

Zulässige Werte in Kleinbuchstaben sind pull und push. Da dieser Artikel Pull-Abonnements behandelt, setzen Sie immer:

  • "SubscriptionType": "pull"

Ein typischer Anfragetext zum Erstellen eines Pull-Abonnements sieht so aus:

{
    "SubscriptionType": "pull",
    "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"
    ]
}

Tragen Sie für folgende Schlüssel im JSON-Anfragetext Ihre eigenen Werte ein:

SubscriptionType

Typ des erstellten Abonnements. Da dieser Artikel Pull-Abonnements behandelt, setzen Sie diesen Wert auf pull. Der Wert muss in Kleinbuchstaben eingegeben werden.

SubscriptionEvent

Der Wert dieses Schlüssels ist ein Array mit einer oder mehreren Zeichenfolgen. Damit wählen Sie aus, über welche Ereignistypen Sie benachrichtigt werden möchten. Das Array kann folgende Werte enthalten:

  • created

  • modified

  • deleted

Sie können Ereignisse kombinieren, indem Sie ein Array senden, zum Beispiel: "SubscriptionEvent": ["created", "modified"].

FilterParam

Setzen Sie FilterParam auf eine Abfrage, die die Teilmenge der Produkte festlegt, über die Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Voraussetzung Nr. 3.

Um Informationen zu erhalten

  • über erstellte und/oder geänderte Produkte, verwenden Sie dieselbe Abfrage wie für den Endpunkt Products.

  • über gelöschte Produkte, verwenden Sie dieselbe Abfrage wie für den Endpunkt DeletedProducts.

Sie können auch Benachrichtigungen zu ausgewählten Ereignistypen für alle Produkte des Katalogs erhalten, statt nur für eine Teilmenge. Dazu können Sie entweder

  • den Wert des Schlüssels FilterParam leer lassen oder

  • diesen Schlüssel vollständig aus der Anfrage weglassen.

Ein fehlender oder leerer Wert für FilterParam bedeutet: Ereignisse der ausgewählten Typen für alle Produkte abonnieren.

Status

Wenn Sie diesen Schlüssel auf running setzen, empfängt das erstellte Abonnement sofort Benachrichtigungen. Wenn Sie ein pausiertes (inaktives) Abonnement erstellen und später aktivieren möchten, setzen Sie den Wert auf paused.

Wenn Sie diesen Schlüssel nicht in der Anfrage angeben, erhält das erstellte Abonnement den Status running.

Wenn Sie bereits zwei Abonnements mit dem Status running haben und ein weiteres mit diesem Status erstellen möchten, schlägt die Operation fehl. Weitere Informationen finden Sie im obigen Abschnitt Beschränkungen für Abonnements.

Sie können entweder

  • eines Ihrer bestehenden Abonnements pausieren und anschließend ein neues erstellen oder

  • ein neues Abonnement mit dem Status paused erstellen.

ERINNERUNG: Geben Sie die obligatorischen Header an.

Senden Sie diese Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions

Der Antwortcode sollte 201 Created sein. Die Antwort sollte JSON-Daten wie diese enthalten:

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

Common mistakes and how to fix them

  • 400 Bad Request — Ihr FilterParam ist ungültig, meist aufgrund eines Tippfehlers.

    Prüfen Sie den Filter zunächst mit derselben Abfrage an die Katalog-API, zum Beispiel am Endpunkt Products oder DeletedProducts, und korrigieren Sie den Feldnamen oder die Syntax.

  • 401 Unauthorized / 403 Forbidden — Problem bei der Authentifizierung.

    Typische Ursachen sind:

    • Ihr Keycloak-Token ist abgelaufen.

    • Sie verwenden ein Token aus dem falschen Realm oder von einem falschen Identitätsanbieter.

    • Der Header Authorization: Bearer <token> fehlt oder ist fehlerhaft.

    Erstellen Sie ein neues Token und stellen Sie sicher, dass die Anfrage die obligatorischen Header enthält.

  • 429 Too Many Requests / limit reached — zu viele Abonnements mit dem Status running.

    Sie können höchstens 2 Abonnements mit dem Status running gleichzeitig haben. Pausieren oder beenden Sie eines davon und versuchen Sie anschließend erneut, ein weiteres Abonnement zu erstellen oder zu aktivieren.

  • 404 Not Found — das Abonnement existiert nicht.

    Dies geschieht meist, wenn das Abonnement auf cancelled gesetzt und dadurch gelöscht wurde oder wenn Sie eine falsche subscription_id verwenden.

  • Leere Warteschlange (200 OK + [] ) — dies ist ein erwartetes Ergebnis.

    Derzeit gibt es keine Benachrichtigungen, die FilterParam und SubscriptionEvent entsprechen. Warten Sie auf neue passende Ereignisse und fragen Sie die Warteschlange anschließend erneut ab.

Pull-Abonnements mit curl

Die folgenden Beispiele enthalten die obligatorischen Header und zeigen minimale funktionsfähige Anfragen.

Bemerkung

Ersetzen Sie:

  • YOUR_ACCESS_TOKEN_HERE durch Ihr Keycloak-Token

  • catalogue.code-de.org durch den Hostnamen Ihrer API

  • <<subscription_id>> und <<AckId>> durch tatsächliche Werte

Abonnement erstellen

curl -sS -X POST "https://catalogue.code-de.org/odata/v1/Subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -d '{"SubscriptionType":"pull","Status":"running","SubscriptionEvent":["created"]}'

Abonnements auflisten

curl -sS -X GET "https://catalogue.code-de.org/odata/v1/Subscriptions/Info" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Warteschlange lesen

curl -sS -X GET "https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)/Read?$top=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Benachrichtigung mit Ack bestätigen

curl -sS -X POST "https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)/Ack?$ackid=<<AckId>>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Status mit PATCH ändern

curl -sS -X PATCH "https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -d '{"Status":"paused"}'

Abonnement löschen

curl -sS -X DELETE "https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Pull-Abonnements mit Python-Code

Pull-Abonnement mit Python erstellen

Der folgende Python-Code sendet eine Anfrage mit den oben beschriebenen Parametern:

import requests
import json

access_token = ""

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

body = {
    "SubscriptionType": "pull",
    "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.code-de.org/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)

Dieses Skript:

  • sendet eine HTTP-Anfrage an die angegebene URL.

  • ruft die Ergebnisse ab und zeigt Folgendes an:

    • den Antwortcode, zum Beispiel 200, und die Statusbeschreibung, zum Beispiel OK.

    • eine Leerzeile zur besseren Lesbarkeit.

    • den Antwortcode, falls vorhanden. Gültiges JSON wird zur besseren Lesbarkeit formatiert.

In diesem Skript wird der Anfragetext über den Parameter json an das Modul requests übergeben.

Weisen Sie das nach Voraussetzung Nr. 4 erstellte Keycloak-Token der Variablen access_token zu.

Speichern Sie die Datei als http_request_test_create.py.

python3 http_request_test_create.py

Abonnement zum Verfolgen erstellter und geänderter Produkte erstellen

In diesem Beispiel erstellen Sie ein Abonnement, das erstellte und geänderte Produkte verfolgt, die folgende Kriterien erfüllen (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')

Senden Sie zum Erstellen dieses Abonnements eine HTTP-POST-Anfrage mit folgendem Anfragetext:

{
    "SubscriptionType": "pull",
    "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"
    ]
}

an diese URL:

https://catalogue.code-de.org/odata/v1/Subscriptions

ERINNERUNG: Geben Sie die obligatorischen Header an.

Sie sollten den Antwortcode 201 Created und eine Antwort wie diese erhalten:

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

Versuch, ein Abonnement mit ungültigem FilterParam zu erstellen

Angenommen, Sie versuchen versehentlich, ein Abonnement mit einer ungültigen Abfrage zu erstellen, etwa mit Colection/Name statt 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')

Der zu sendende Anfragetext enthält die ungültige Abfrage:

{
    "SubscriptionType": "pull",
    "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"
    ]
}

Wie zuvor senden Sie die Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions

Als Antwort erhalten Sie den Code 400 Bad Request und folgende JSON-Daten:

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

Diese Antwort hängt von der Art des Fehlers in Ihrer Abfrage ab.

Sicherheitsregeln und Empfehlungen

  • Read verändert die Warteschlange nicht.

  • Ack löscht die ausgewählte Benachrichtigung und alle älteren Benachrichtigungen aus der Warteschlange. Siehe Benachrichtigungen mit Ack bestätigen.

  • Speichern Sie die Benachrichtigungen oder mindestens ProductId und AckId, bevor Sie Ack ausführen.

  • Rufen Sie vollständige Metadaten innerhalb von 3 Tagen ab, wenn Sie diese benötigen, oder fragen Sie sofort den Endpunkt Products ab.

Warteschlange anzeigen

Senden Sie eine GET-Anfrage an folgende URL, um die ältesten Benachrichtigungen einer Warteschlange anzuzeigen:

https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)/Read?$top=20

Ersetzen Sie <<subscription_id>> durch die ID des Abonnements.

Der Parameter $top legt fest, wie viele der ältesten Benachrichtigungen angezeigt werden, höchstens 20. Ohne Angabe wird der Standardwert 1 verwendet.

Wenn die Anzahl der Benachrichtigungen in Ihrer Warteschlange kleiner oder gleich $top ist, erhalten Sie alle Benachrichtigungen.

Die API liefert Benachrichtigungen von der ältesten zur neuesten.

Bemerkung

Sie legen die Abfragehäufigkeit fest. Für aktive Abläufe sind Abfragen alle paar Minuten bis stündlich üblich. Bei Abonnements mit wenigen Ereignissen kann eine tägliche Abfrage ausreichen. Vermeiden Sie jedoch längere Inaktivität.

Ein Beispiel ist eine GET-Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(991c4730-cf6f-432a-9f6c-47be0230ff45)/Read?$top=2

Die Antwort hängt von den jeweiligen Umständen ab.

ERINNERUNG: Geben Sie die obligatorischen Header an.

Das Abonnement hat den Status cancelled

Das Setzen eines Abonnements auf cancelled löscht es. Wenn Sie versuchen, die Warteschlange eines solchen Abonnements anzuzeigen, erhalten Sie den Antwortcode 404 Not Found und JSON-Daten wie diese:

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

Das Abonnement hat den Status running oder paused

Bei einem Abonnement mit dem Status running (aktiv) oder paused (inaktiv) erhalten Sie ein Array von JSON-Objekten, die jeweils eine Benachrichtigung darstellen.

Jedes dieser Objekte enthält Informationen über

  • die Benachrichtigung,

  • das Produkt und

  • das Abonnement.

Wichtig

Der vollständige Inhalt einer Benachrichtigung bleibt drei Tage lang in der Warteschlange des Benutzers erhalten. Danach werden die Schlüssel value und ProductName entfernt. Wenn Sie vollständige Produktmetadaten benötigen, rufen Sie diese innerhalb von 3 Tagen ab und speichern Sie sie. Alternativ fragen Sie sofort den Endpunkt Products mit ProductId ab.

Beispiel 1

Die folgende herunterladbare JSON-Datei

example-notification.json

enthält eine erfolgreiche Antwort für SubscriptionEvent mit dem Wert created (Status 200 OK).

Die vollständige Antwort ist zu lang, um sie in diesem Artikel vollständig wiederzugeben.

eodata/pull-subscriptions-01_creodias.png

Das Array value -> Attributes sieht wie folgt aus. Es beginnt in Zeile 67 und endet in Zeile 248; die gesamte Datei hat 293 Zeilen. Das rote Rechteck rechts im Bild zeigt die Position des Arrays Attributes im Verhältnis zur Länge des gesamten Texts.

Beispiel 2

Dies ist eine erfolgreiche Antwort (Status 200 OK) für SubscriptionEvent mit dem Wert modified. Folgende Werte wurden ausgelassen:

  • 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.code-de.org/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": []
        }
    }
]

Beispiel 3

Dies ist eine erfolgreiche Antwort (Status 200 OK) für SubscriptionEvent mit dem Wert 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"
            }
        }
    }
]

Beispiel 4

Beispiel einer erfolgreichen Antwort (Status 200 OK) für Benachrichtigungen, die mindestens 3 Tage alt sind:

[
    {
        "@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=="
    }
]

Beispiel 5

Wenn Ihre Warteschlange keine Benachrichtigungen enthält, sollten Sie den Status 200 OK und ein leeres Array erhalten:

[]

Schlüssel einer Benachrichtigung erläutert

Eigenschaftsname Typ Beschreibung
ProductId Guid Dies ist der universell eindeutige Bezeichner (UUID) des Produkts, auf das sich die Benachrichtigung bezieht.

Beispiel
8d654e59-d7b6-4a53-b086-c9de764e506b
ProductName String Dies ist der im Katalog vergebene Name des Produkts, auf das sich die Benachrichtigung bezieht.

Der Wert von ProductName kann lang sein und passt meist nicht in eine einzelne Tabellenzelle. Ein konkretes Beispiel steht unterhalb der Tabelle.
SubscriptionId Guid Dies ist ein universell eindeutiger Bezeichner (UUID). Die Id ist ein lokaler Bezeichner für die Abonnementinstanz innerhalb des Katalogs und wird beim Erstellen des Abonnements vergeben.

Beispiel
991c4730-cf6f-432a-9f6c-47be0230ff4
SubscriptionEvent Aufzählung der Abonnementereignisse Das Abonnementereignis, das überwacht und für das eine Benachrichtigung bereitgestellt wird:
  • created
  • modified
  • deleted
Beispiel
created
NotificationDate DateTimeOffset Datum und Uhrzeit der Erstellung der Benachrichtigung. Die Zeit wird im ISO-8601-Format (UTC+0) angegeben: YYYY-MM-DDThh:mm:ss.sssZ

Beispiel
2024-01-29T10:59:08.698Z
AckId String Bestätigungs-ID, die jeder Produktbenachrichtigung zugewiesen wird. Sie ist zum Bestätigen von Benachrichtigungen aus der Warteschlange des Clients erforderlich.

Da AckId lang ist, steht das Beispiel unterhalb dieser Tabelle.
value JSON-Objekt Enthält eine Standardantwort der Katalog-API mit allen Metadaten und Inhaltsdetails eines Produkts.

Beispiel für ProductName

S2A_MSIL2A_20240129T062121_N0510_R034_T44VMN_20240129T093752.SAFE

Beispiel für AckId

MTcxMDc1NjcwNjUzMi0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==

Benachrichtigungen mit Ack bestätigen

Ack (Bestätigen) ist die Operation, die Benachrichtigungen aus der Warteschlange Ihres Pull-Abonnements löscht.

Ack löscht die ausgewählte Benachrichtigung und alle älteren Benachrichtigungen aus der Warteschlange.

  • Wenn Sie eine Benachrichtigung mit Ack bestätigen, entfernt die API diese Benachrichtigung und jede ältere Benachrichtigung.

  • Neuere Benachrichtigungen mit einem späteren NotificationDate bleiben in der Warteschlange.

Behandeln Sie Ack deshalb wie einen Cursor, den Sie zeitlich vorwärts bewegen.

Sicherer Ablauf für Ack (empfohlen)

  1. Lesen Sie die ältesten Benachrichtigungen, zum Beispiel mit $top=20.

  2. Speichern Sie die benötigten Informationen aus der Antwort dauerhaft: mindestens ProductId, AckId und NotificationDate sowie ProductName, falls vorhanden.

  3. Bestätigen Sie die neueste Benachrichtigung dieser Antwort mit Ack, also das letzte Element der zurückgegebenen Liste.

Damit verschieben Sie den Cursor, ohne Benachrichtigungen zu überspringen, und verhindern, dass Metadaten vor dem Speichern verloren gehen.

URL einer Ack-Anfrage

Senden Sie zum Bestätigen einer Benachrichtigung eine POST-Anfrage an folgenden Endpunkt und geben Sie an:

  • <<subscription_id>> — den Bezeichner des Abonnements

  • <<AckId>> — den AckId-Wert der Benachrichtigung, die als Cursorposition dienen soll

https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)/Ack?$ackid=<<AckId>>

ERINNERUNG: Geben Sie die obligatorischen Header an.

Dies kann beispielsweise eine POST-Anfrage an folgende URL sein:

https://catalogue.code-de.org/odata/v1/Subscriptions(991c4730-cf6f-432a-9f6c-47be0230ff45)/Ack?$ackid=MTcxMDc1NjcwNjY2NC0wOjk5MWM0NzMwLWNmNmYtNDMyYS05ZjZjLTQ3YmUwMjMwZmY0NQ==

Sie sollten die Antwort 200 OK und JSON-Daten wie diese erhalten:

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

Diese enthalten folgende Informationen:

Schlüssel Typ Beschreibung
AckMessagesNum Int64 Anzahl der Benachrichtigungen, die durch Ihre Anfrage bestätigt wurden.
CurrentQueueLength Int64 Anzahl der Benachrichtigungen, die sich derzeit in Ihrer Warteschlange befinden.
MaxQueueLength Int64 Maximale Anzahl von Benachrichtigungen, die in Ihrer Warteschlange gespeichert werden können

Wenn das Abonnement zuvor auf cancelled gesetzt wurde, sollten Sie den Antwortcode 404 Not Found und JSON-Daten wie diese erhalten:

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

Mit Ack weitere Benachrichtigungen lesen

Eine Anfrage zum Anzeigen der Warteschlange liefert höchstens die 20 ältesten Benachrichtigungen. Eine Warteschlange kann jedoch bis zu 100000 Benachrichtigungen enthalten. Eine einzelne Anfrage reicht daher möglicherweise nicht aus, um alle Benachrichtigungen abzurufen.

Ack löscht die ausgewählte Benachrichtigung und alle älteren Benachrichtigungen aus der Warteschlange. Siehe Benachrichtigungen mit Ack bestätigen.

  • Zeigen Sie die aktuelle Liste der Benachrichtigungen an und setzen Sie $top auf 20.

  • Speichern Sie diese Benachrichtigungen bei Bedarf.

  • Bestätigen Sie die letzte Benachrichtigung mit Ack.

Rufen Sie die aktuelle Liste erneut ab. Sie sollte nun Benachrichtigungen enthalten, die nach der mit Ack bestätigten Benachrichtigung eingegangen sind. Wenn mehr als 20 Benachrichtigungen in der Warteschlange waren, sollten jetzt zuvor nicht angezeigte Benachrichtigungen erscheinen.

Speichern Sie die Benachrichtigungen bei Bedarf erneut und bestätigen Sie die letzte mit Ack.

Wiederholen Sie dies, bis die Warteschlange leer ist.

Status eines Pull-Abonnements ändern

Bei einem Pull-Abonnement können Sie nur den Status ändern.

Ein Abonnement kann einen der folgenden Statuswerte haben:

  • running — das Abonnement empfängt neue Benachrichtigungen.

  • paused — das Abonnement empfängt vorübergehend keine neuen Benachrichtigungen.

  • cancelled — dieser Status beendet und löscht das Abonnement.

Senden Sie zum Ändern des Status eine HTTP-PATCH-Anfrage mit folgendem Anfragetext. Ersetzen Sie <<new_status>> durch den gewünschten Status:

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

ERINNERUNG: Geben Sie die obligatorischen Header an.

Senden Sie diese Anfrage an die folgende URL. Ersetzen Sie <<subscription_id>> durch die ID des zu ändernden Abonnements.

https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)

Sie sollten den Antwortcode 200 OK und aktualisierte Informationen über das Abonnement erhalten. Eine Ausnahme ist der Status cancelled: Dabei sollte der Antwortcode 204 No Content zurückgegeben werden.

Status eines Pull-Abonnements ändern, ohne es zu löschen

Wenn Ihr Abonnement die ID 7ca682c3-7b21-4e9b-952e-874798181340 hat und Sie es pausieren möchten, verwenden Sie folgenden Anfragetext für die HTTP-PATCH-Anfrage:

{
    "Status": "paused"
}

Die URL lautet:

https://catalogue.code-de.org/odata/v1/Subscriptions(7ca682c3-7b21-4e9b-952e-874798181340)

ERINNERUNG: Geben Sie die obligatorischen Header an.

Abonnementstatus auf cancelled setzen

Angenommen, Sie möchten das Abonnement aus dem vorherigen Beispiel löschen, indem Sie seinen Status auf cancelled setzen.

Verwenden Sie dazu folgendes JSON-Objekt als Anfragetext Ihrer HTTP-PATCH-Anfrage:

{
   "Status": "cancelled"
}

Die URL bleibt unverändert:

https://catalogue.code-de.org/odata/v1/Subscriptions(7ca682c3-7b21-4e9b-952e-874798181340)

Sie erhalten den Antwortcode 204 No Content. Das Abonnement sollte nun gelöscht sein.

Aktuelle Abonnements auflisten

Senden Sie eine GET-Anfrage an folgende URL, um alle derzeit mit Ihrem Konto verknüpften Abonnements aufzulisten:

https://catalogue.code-de.org/odata/v1/Subscriptions/Info

ERINNERUNG: Geben Sie die obligatorischen Header an.

Der Antwortstatus sollte 200 OK sein. Sie sollten eine Liste Ihrer aktuellen Abonnements erhalten. Dazu gehören:

  • Pull-Abonnements und

  • Push-Abonnements.

Hier ist ein Beispiel:

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

In diesem Beispiel hat der Benutzer zwei Abonnements:

  • ein Push-Abonnement, das created-Produkte verfolgt,

  • ein Pull-Abonnement, das created- und modified-Produkte verfolgt.

Ein Push-Abonnement enthält im Gegensatz zu einem Pull-Abonnement den Schlüssel NotificationEndpoint. Dieser gibt die URL des Endpunkts an, an den Benachrichtigungen gesendet werden. Weitere Informationen finden Sie unter Push-Abonnements für den EODATA-Katalog auf CODE-DE-Lab

Wenn Sie derzeit keine Abonnements haben, sollte die Abfrage ein leeres Array zurückgeben:

[]

Abonnements mit Python auflisten

Der folgende vollständige Python-Code listet Abonnements auf:

import requests
import json

access_token = ""

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

url = "https://catalogue.code-de.org/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)

Dieses Skript:

  • sendet eine HTTP-Anfrage an die angegebene URL.

  • ruft die Ergebnisse ab und zeigt Folgendes an:

    • den Antwortcode, zum Beispiel 200, und die Statusbeschreibung, zum Beispiel OK.

    • eine Leerzeile zur besseren Lesbarkeit.

    • den Antwortcode, falls vorhanden. Gültiges JSON wird zur besseren Lesbarkeit formatiert.

Weisen Sie das nach Voraussetzung Nr. 4 erstellte Keycloak-Token der Variablen access_token zu.

Speichern Sie die Datei als http_request_test_list.py.

python3 http_request_test_list.py

Abonnement löschen

Methode 1: Eine HTTP-DELETE-Anfrage senden

Senden Sie eine DELETE-Anfrage an die folgende URL. Ersetzen Sie <<subscription_id>> durch die ID des zu löschenden Abonnements.

https://catalogue.code-de.org/odata/v1/Subscriptions(<<subscription_id>>)

ERINNERUNG: Geben Sie die obligatorischen Header an.

Sie sollten den Antwortstatus 204 No Content erhalten.

Die im Abschnitt Aktuelle Abonnements auflisten beschriebene Auflistung sollte zeigen, dass dieses Abonnement nicht mehr existiert.

Methode 2: Den Abonnementstatus auf cancelled setzen

Dieser Ablauf ist im Abschnitt Status eines Pull-Abonnements ändern beschrieben.

Pull-Abonnement – Beispielablauf

Dieser Abschnitt zeigt einen Beispielablauf mit einem Pull-Abonnement.

Abonnement erstellen

Listen Sie zunächst die Abonnements Ihres Kontos auf.

Senden Sie dazu eine GET-Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions/Info

ERINNERUNG: Geben Sie die obligatorischen Header an.

Diese Anfrage liefert den Antwortcode 200 OK und ein leeres Array. Das Konto hat somit noch keine Abonnements:

[]

Erstellen Sie nun das erste Abonnement. Es verfolgt Produkte, die dem Katalog hinzugefügt werden. Verwenden Sie folgenden Filter:

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

Diese Abfrage verfolgt Produkte, die:

  • zur Sammlung SENTINEL-1 gehören,

  • den Produkttyp IW_SLC__1S haben,

  • für Online den Wert true haben,

  • einen orbitNumber-Wert größer als 0 haben,

  • einen orbitNumber-Wert kleiner als 100000 haben und

  • folgendes Polygon schneiden: POLYGON((-180.0000 90.0000,180.00 90.00,180 -90,-180.0 -90.0,-180.0000 90.0000))

Senden Sie dazu folgenden Anfragetext:

{
    "SubscriptionType": "pull",
    "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"
    ]
}

Dieser Anfragetext enthält Informationen über das Abonnement:

FilterParam

Abfrage an den Katalog, die die Produkte filtert.

Status

Status des zu erstellenden Abonnements. Damit das Abonnement sofort nach dem Erstellen aktiv ist, wird running verwendet.

SubscriptionEvent

Art der Änderungen im Katalog, die verfolgt werden sollen. Weitere Informationen finden Sie in der Tabelle im Abschnitt Beschreibung der Pull-Abonnement-Entität. In diesem Beispiel wird created verwendet, um Benachrichtigungen über neu erstellte Produkte zu erhalten.

ERINNERUNG: Geben Sie die obligatorischen Header an.

Senden Sie die Anfrage an diese URL:

https://catalogue.code-de.org/odata/v1/Subscriptions

Nach dem Senden der Anfrage erhalten Sie den Antwortcode 201 Created und folgendes JSON-Objekt:

{
    "Id": "32ee6df9-3008-4279-92e6-200828e532d1",
    "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') 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"
}

Dieses JSON-Objekt bestätigt die Angaben zum neuen Abonnement, etwa die Filterabfrage und die Art der verfolgten Ereignisse.

Für spätere Anfragen zu diesem Abonnement benötigen Sie seine ID. In diesem Beispiel lautet sie 32ee6df9-3008-4279-92e6-200828e532d1.

Die Ausgabe bestätigt außerdem, dass Status auf running gesetzt ist. Das Abonnement sollte somit bereits Benachrichtigungen empfangen können.

Um das Erstellen des Abonnements zu prüfen, listen Sie die Abonnements des Kontos erneut auf. Senden Sie dazu eine GET-Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions/Info

ERINNERUNG: Geben Sie die obligatorischen Header an.

Der Antwortcode ist erneut 200 OK.

Die empfangenen Daten bilden ein Array aus Objekten, die jeweils ein Abonnement darstellen.

[
    {
        "Id": "32ee6df9-3008-4279-92e6-200828e532d1",
        "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') 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"
    }
]

Da jetzt ein Abonnement vorhanden ist, enthält das Array ein Objekt. Dessen detaillierte Angaben entsprechen der Ausgabe beim Erstellen des Abonnements.

Wenn Sie Angaben wie die ID oder die verwendete Abfrage später benötigen, können Sie sie mit diesem Befehl erneut abrufen.

Diese Anfrage listet sowohl laufende als auch pausierte Abonnements auf, sofern sie vorhanden sind.

Eine Benachrichtigung mit Ack bestätigen

Prüfen Sie nun die Warteschlange dieses Abonnements. Senden Sie dazu eine GET-Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read?$top=20

Diese URL enthält folgende Angaben:

  • die ID des Abonnements (32ee6df9-3008-4279-92e6-200828e532d1),

  • die maximale Anzahl anzuzeigender Benachrichtigungen: 20. Dieser Wert kann nicht höher sein.

ERINNERUNG: Geben Sie die obligatorischen Header an.

Diese Anfrage liefert den Antwortcode 200 OK und ein leeres Array:

[]

Die Warteschlange enthält somit noch keine Benachrichtigungen.

Warten Sie, bis die erste Benachrichtigung erscheint.

Senden Sie anschließend dieselbe HTTP-Anfrage erneut. Auch diesmal erhalten Sie den Antwortcode 200 OK. Das zurückgegebene Array enthält nun eine Benachrichtigung.

(Zur besseren Lesbarkeit wurde der Inhalt des JSON-Schlüssels value entfernt.)

[
    {
        "@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": {
        }
    }
]

Diese Benachrichtigung meldet die Veröffentlichung des Produkts mit folgendem Namen:

S1A_IW_SLC__1SDV_20250326T101553_20250326T101621_058474_073BCB_A673.SAFE

Speichern Sie die benötigten Informationen aus dieser Benachrichtigung zur späteren Verwendung, zum Beispiel für die Verarbeitung.

Danach wird die Benachrichtigung nicht mehr benötigt und kann durch Bestätigen mit Ack gelöscht werden.

Dazu benötigen Sie die AckId der Benachrichtigung. In diesem Beispiel lautet sie:

MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Senden Sie zum Bestätigen mit Ack eine POST-Anfrage an die folgende URL. Die URL enthält die ID des Abonnements und diese AckId:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTY0Mzg5MC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

ERINNERUNG: Geben Sie die obligatorischen Header an.

Der Antwortcode lautet 200 OK. Die zurückgegebenen JSON-Daten enthalten die Ergebnisse dieser Operation:

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

Das JSON-Objekt zeigt, dass

  • diese Ack-Operation eine Benachrichtigung entfernt hat (AckMessagesNum) und

  • keine Benachrichtigungen in der Warteschlange verbleiben (CurrentQueueLength).

Es erinnert außerdem daran, dass eine Warteschlange höchstens 100000 Benachrichtigungen speichern kann, angegeben im Schlüssel MaxQueueLength.

Prüfen Sie die aktuelle Warteschlange erneut mit einer GET-Anfrage an diese URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read?$top=20

ERINNERUNG: Geben Sie die obligatorischen Header an.

Die Anfrage liefert den Antwortcode 200 OK und ein leeres JSON-Array:

[]

Zuvor war eine Benachrichtigung vorhanden. Sie wurde mit Ack entfernt, daher ist die Liste nun leer.

Mehrere Benachrichtigungen gleichzeitig mit Ack bestätigen

Warten Sie, bis weitere Benachrichtigungen in der Warteschlange vorliegen.

Prüfen Sie die Warteschlange anschließend mit einer GET-Anfrage an dieselbe URL wie zuvor:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read?$top=20

ERINNERUNG: Geben Sie die obligatorischen Header an.

Sie erhalten den Antwortcode 200 OK und drei Benachrichtigungen. Zur besseren Lesbarkeit wurde der Inhalt des Schlüssels value entfernt.

[
    {
        "@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": {
        }
    }
]

Jede dieser drei Benachrichtigungen steht für ein Produkt. Die Benachrichtigungen sind chronologisch nach dem Empfangszeitpunkt NotificationDate sortiert, von der ältesten zur neuesten.

Angenommen, Sie möchten die zweite Benachrichtigung mit Ack bestätigen. Sie wurde zum Zeitpunkt 2025-03-26T12:21:41.000000Z gesendet.

Ihre AckId lautet:

MTc0Mjk5MTcwMTQ5OC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Senden Sie dazu eine POST-Anfrage an diese URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTcwMTQ5OC0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

ERINNERUNG: Geben Sie die obligatorischen Header an.

Die Anfrage liefert den Antwortcode 200 OK und JSON-Daten mit einer Zusammenfassung des Ergebnisses:

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

Das Bestätigen mit Ack entfernt sowohl die ausgewählte Benachrichtigung als auch alle davor eingegangenen Benachrichtigungen. In diesem Fall gab es eine ältere Benachrichtigung, daher wurden beide entfernt. Insgesamt wurden zwei Benachrichtigungen entfernt, wie der Wert von AckMessagesNum zeigt.

Die dritte Benachrichtigung bleibt in der Warteschlange, da sie zeitlich nach der bestätigten Benachrichtigung eingegangen ist. Sie wird im Wert von CurrentQueueLength gezählt.

Zeigen Sie die verbleibende Benachrichtigung an, indem Sie die Warteschlange erneut prüfen. Senden Sie eine GET-Anfrage an diese URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read?$top=20

ERINNERUNG: Geben Sie die obligatorischen Header an.

Sie erhalten den Antwortcode 200 OK und ein Array mit der verbleibenden Benachrichtigung. Der Inhalt von value wurde erneut zur besseren Lesbarkeit entfernt:

[
    {
        "@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": {
        }
    }
]

Ihre AckId lautet:

MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

Senden Sie eine POST-Anfrage an diese URL, um auch diese Benachrichtigung mit Ack zu bestätigen:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Ack?$ackid=MTc0Mjk5MTcxOTU3MS0wOjMyZWU2ZGY5LTMwMDgtNDI3OS05MmU2LTIwMDgyOGU1MzJkMQ==

ERINNERUNG: Geben Sie die obligatorischen Header an.

Die Anfrage liefert erneut den Antwortcode 200 OK und das Ergebnis der Operation als JSON-Daten:

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

Das JSON-Objekt zeigt, dass dies die letzte Benachrichtigung in der Warteschlange war. Prüfen Sie die Warteschlange erneut mit einer GET-Anfrage an diese URL, um zu bestätigen, dass sie leer ist:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)/Read?$top=20

ERINNERUNG: Geben Sie die obligatorischen Header an.

Der Antwortcode 200 OK wird zusammen mit leeren JSON-Daten zurückgegeben:

[]

Da die einzige Benachrichtigung gelöscht wurde, ist die Warteschlange nun leer.

Abonnement löschen

Angenommen, Sie benötigen das Abonnement nach einiger Zeit nicht mehr und möchten es entfernen.

Senden Sie dazu eine DELETE-Anfrage an folgende URL:

https://catalogue.code-de.org/odata/v1/Subscriptions(32ee6df9-3008-4279-92e6-200828e532d1)

ERINNERUNG: Geben Sie die obligatorischen Header an.

Der Antwortcode 204 No Content wird ohne JSON-Daten zurückgegeben.

Rufen Sie die aktuelle Liste der Abonnements mit einer GET-Anfrage an diese URL ab:

https://catalogue.code-de.org/odata/v1/Subscriptions/Info

ERINNERUNG: Geben Sie die obligatorischen Header an.

Sie erhalten den Antwortcode 200 OK und ein leeres Array:

[]

Damit ist bestätigt, dass keine Abonnements im Konto verbleiben.

Nächste Schritte

Nach dem Empfang einer Benachrichtigung können Sie das betreffende Produkt herunterladen. Dafür stehen unter anderem folgende Möglichkeiten zur Verfügung:

Die folgenden Artikel behandeln einige Möglichkeiten zur Verarbeitung von EODATA:

Still need help?
If this article does not answer all of your questions, the support team will help you.
Contact support