Direkt zum Hauptinhalt

Abruf von Gast-Daten als Liste (pull)

Swagger-Referenz: Operation und Antwortschema öffnen.

Worum es geht

pull liefert die für Ihre Datenansicht freigegebenen Gäste in aufeinanderfolgenden Seiten. Über einen Änderungszeitpunkt können Sie den Abruf auf neuere Änderungen eingrenzen.

Aufruf

curl --get 'https://gwatch.events/ext-api/pull' \
  --header 'x-api-key: IHR_HAUPTSCHLUESSEL' \
  --header 'x-api-flavor: IHR_PULL_SCHLUESSEL' \
  --header 'Accept: application/json' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0'

Der Flavor muss aktiv und vom Typ pull sein. Bei einer vereinbarten Standardansicht mit leerem Schlüssel lassen Sie den Flavor-Header weg. Allgemeine Zugangsvoraussetzungen stehen in der Übersicht.

Optionale URL-Parameter

Parameter Bedeutung
limit Anzahl pro Seite: Ganzzahl von 1 bis 2500. Ohne Angabe werden im aktuellen Portal bis zu 2500 Gäste angefordert.
offset Anzahl zu überspringender Datensätze, mindestens 0. Standard: 0.
changesUntil Untere Änderungsgrenze: Berücksichtigt werden Datensätze mit einer erfassten Änderung nach diesem Zeitpunkt. Ohne Angabe entfällt der Zeitfilter.

Der Name changesUntil ist missverständlich: Gemeint ist „geändert seit“, nicht „geändert bis“. Der Vergleich ist strikt größer (>). Verwenden Sie beispielsweise 2026-09-18T10:00:00 und stimmen Sie die Portal-Zeitzone ab. Die ausgegebenen Zeitstempel enthalten keinen Zeitzonenoffset.

Der Änderungsfilter berücksichtigt Gaständerungen einschließlich Löschung, Teilnahmestatus und Änderungen durch den Gast sowie Änderungen und Löschungen an Gästefeldern. Er ist kein vollständiges Ereignisprotokoll aller abhängigen Daten oder Konfigurationsänderungen.

Antwort verstehen

Beispiel nach dem Swagger-Modell pullData, mit limit=1 und insgesamt zwei verfügbaren Gästen:

{
  "error": false,
  "meta": {
    "changesUntil": null,
    "available": 2,
    "limit": 1,
    "offset": 0,
    "nextUrl": "https://gwatch.events/ext-api/pull?limit=1&offset=1"
  },
  "event": {
    "name": "IT summit",
    "ort": "Frankfurt am Main"
  },
  "guests": [
    {
      "First name": "Susi",
      "Surname": "Sorglos",
      "Access": "IT-Security Concepts",
      "Last scan": "20.03.2025 19:57:57",
      "id": 347639,
      "created": "2017-01-07T20:08:30",
      "updated": "2025-03-20T20:13:47",
      "deleted": false
    }
  ]
}
Bereich Bedeutung
meta.available Zahl der zur aktuellen Abfrage passenden Gäste vor der Seiteneinteilung.
meta.nextUrl URL der nächsten Seite; null, wenn keine weitere Seite folgt.
event Konfigurierte Veranstaltungsfelder. Ohne konfigurierte Felder kann dieser Bereich als leeres Array [] erscheinen.
guests Array mit den Datensätzen dieser Seite. Die Reihenfolge richtet sich nach aufsteigender Gast-ID.

Die Administration legt sämtliche fachlichen Feldnamen und Feldinhalte des Listenexports fest – sowohl für event als auch für die Gäste. Dabei sind auch zusammengesetzte Inhalte möglich, etwa ein Feld Name mit Vor- und Nachname. Die Felder First name, Surname, Access, Last scan, name und ort stammen lediglich aus den Swagger-Beispielen und sind keine fest vorgegebenen API-Feldnamen. Zusätzlich erhält jeder Gast vier feste Felder:

  • id: Datenbank-ID des Gastes.
  • created: Erstellungszeitpunkt als YYYY-MM-DDTHH:MM:SS.
  • updated: Letzter aus den ausgewerteten Gast- und Gästefeld-Zeitstempeln ermittelter Änderungszeitpunkt.
  • deleted: JSON-Boolean für den Löschstatus.

Reservieren Sie diese vier Namen in Ihrer Feldvereinbarung. Sie werden vom Portal für die festen Angaben verwendet.

Alle Seiten abrufen

  1. Beginnen Sie mit offset=0 und einem passenden limit, etwa 100.
  2. Verarbeiten Sie die zurückgegebenen Gäste.
  3. Rufen Sie meta.nextUrl auf, solange der Wert nicht null ist. Senden Sie bei jeder Folgeseite dieselben Authentifizierungsheader mit.
  4. Prüfen Sie, dass die Folge-URL zum vereinbarten API-Host gehört, bevor Sie Schlüssel mitsenden.

Alternativ erhöhen Sie den Offset selbst um das Limit: 0, 100, 200 usw. Behalten Sie den Änderungsfilter während eines Durchlaufs unverändert bei.

Gelöschte und ausgefilterte Gäste

Auch als gelöscht markierte Gäste können in der Liste enthalten sein. Entscheidend ist deleted=true. Konfigurierte Ausgabefelder sind dabei nicht garantiert leer. Verwenden Sie den Löschstatus, um Ihre lokale Kopie entsprechend zu behandeln.

Die Bedingungen der Datenansicht filtern die Ergebnismenge zusätzlich. Fällt ein zuvor sichtbarer Gast später aus diesen Bedingungen heraus, ist damit keine eigene Löschmeldung an Ihr System garantiert. Stimmen Sie einen regelmäßigen Bestandsabgleich ab, wenn Ihre Anbindung solche Änderungen erkennen muss.

Änderungen synchronisieren

  • Speichern Sie Gäste anhand ihrer id, nicht anhand ihrer Position in der Antwort.
  • Setzen Sie den nächsten Synchronisationsstand erst nach erfolgreicher Verarbeitung aller Seiten.
  • Arbeiten Sie mit einem zeitlichen Überlappungsbereich und verarbeiten Sie Wiederholungen anhand der ID. So werden Änderungen an der Sekundengrenze nicht allein durch den strikten Zeitvergleich übersehen.
  • Offset-Seiten bilden keinen eingefrorenen Datenstand. Gleichzeitige Änderungen an Gästen oder Filtern können die Seiteneinteilung verschieben; ein regelmäßiger vollständiger Abgleich bleibt sinnvoll.

Die API liefert hierfür keinen Snapshot- oder Ereignis-Cursor. Ein lückenloses Änderungsprotokoll lässt sich allein aus changesUntil nicht ableiten.

Formate der vereinbarten Ausgabefelder

Die Ausgabe hängt vom verwendeten Feld beziehungsweise Platzhalter ab. Benutzerdefinierte Datumsfelder werden im aktuellen Code als YYYY-MM-DD beziehungsweise YYYY-MM-DDTHH:MM:SS eingesetzt; andere Platzhalter können anders formatieren. Listen und Ja/Nein-Felder können lesbare Bezeichnungen enthalten.

Eine durchgehend an der Sprache jedes einzelnen Gastes ausgerichtete Ausgabe ist nicht zugesichert. Vereinbaren und testen Sie deshalb die Formate Ihrer Datenansicht ausdrücklich. Für den Rückimport gelten die Eingabeformate aus metadata.

Fehler

Ungültige Parameter liefern HTTP 422, beispielsweise bei limit=0:

{
  "error": true,
  "message": {"limit": ["The limit must be at least 1."]}
}

Der genaue Meldungstext kann sprachabhängig abweichen. HTTP 401 weist auf Zugang, Flavor oder IP-Filter hin. Eine gültige Abfrage ohne Treffer liefert HTTP 200 und guests: [].

Weiter: Einzelnen Gast abrufen.
Zurück: Metadaten.

nach oben