Suche
gridsz
GRIDSZ
Kontaktieren Sie uns
Demo anfordern
GRIDSZ

Equitri-Protokoll

Equitri ist das Protokoll, das GRIDSZ nutzt, um die an derselben Aufgabe arbeitenden Parteien aufeinander abzustimmen. Es bildet die Grundlage für die Fulfillment- (TASK) und Assurance- (SERVICE) APIs und geht von einem relativ geringen Aufkommen an Aktualisierungen bei lang andauernden Aufgaben aus (die in der Regel länger als einen Tag laufen). Hinter einer bewusst einfach gehaltenen API verbirgt Equitri die Komplexität von Backend-Systemen, Middleware, nächtlicher Stapelverarbeitung und Echtzeitsystemen.

Jede verbundene Partei muss sowohl einen Client als auch einen Server implementieren: Der Client initiiert Aktualisierungen und ruft Aufgabeninformationen vom Server einer anderen Partei ab, während der Server die Aufgabendaten für den Client einer anderen Partei (in der Regel Gridsz) bereitstellt. Der Ersteller (InTask) und der Empfänger (OutTask) verwenden unterschiedliche APIs, das zugrunde liegende Protokoll ist jedoch identisch.

Nach einer Erläuterung einiger Begriffe und des Protokolls selbst werden auf dieser Seite die Schritte für beide Richtungen detailliert beschrieben:

  • Gridsz : Eine neue Aufgabe Gridsz oder eine bestehende Aufgabe aktualisieren
  • Ein integriertes System, das eine neue Aufgabe erstellt oder eine bestehende Aufgabe aktualisiert

Die Begriffe „integriertes System“ und „Sie“ beziehen sich auf die Partei, die Equitri implementiert.

Diese Seite befasst sich nicht mit der zugrunde liegenden Konnektivität auf HTTP(S)-Ebene, VPNs, Proxys usw. und geht auch nicht näher darauf ein, wie die betreffende Partei mit den erhaltenen Aufgabeninformationen umgehen soll. Das absolute Minimum besteht darin, dass das integrierte System in der Lage ist, die Equitri-API (INDICATION / FETCH / SYNC) in beide Richtungen mit gültigem JSON und Autorisierung zu verarbeiten, wobei sowohl normale als auch Ausnahmesituationen berücksichtigt werden müssen.

Hinweis: Es ist möglich, den FETCH-Vorgang getrennt vom INDICATION- und SYNC-Prozess abzuwickeln – also Informationen zu erfassen, ohne die Aufgabe zu aktualisieren.

Glossar

Eine kurze Erläuterung der verwendeten Begriffe.

Equitri

Der Name, der dem API-Mechanismus zugewiesen wurde, wie er in den GRIDSZ verwendet wird. Dieser Mechanismus gilt sowohl für Fulfilment- als auch für Assurance-Abläufe sowie sowohl für die Ersteller- (InTask) als auch für die Empfänger- (OutTask) APIs.

INDIKATION

Eine INDICATION ist die erste Nachricht im Equitri-Protokoll. Es handelt sich um eine „Fire-and-Forget“-POST-Nachricht, die lediglich angibt, dass am Endpunkt des Absenders eine Aufgabe abgerufen werden soll. Der Inhalt des Nachrichtenteils gibt an, welche Aufgabe von welchem Endpunkt abgerufen werden soll. Dabei kann es sich entweder um eine völlig neue Aufgabe oder um eine Aktualisierung einer bestehenden Aufgabe handeln.

FETCH

Ein FETCH ist die zweite Nachricht in Equitri und der eigentliche „Kraftakt“. Mit einem einfachen HTTP-GET-Aufruf an die richtige URL wird der gesamte Aufgabeninhalt zurückgegeben. Der FETCH kann auch als eigenständiger Aufruf ohne vorherige INDICATION erfolgen und erfordert dann auch keinen SYNC.

SYNC

Eine SYNC-Nachricht ist die dritte und letzte Nachricht im Equitri-Protokoll. Es handelt sich um eine PUT-Nachricht, die angibt, dass die Aufgabe verarbeitet wurde und für diese bestimmte Aktualisierung (Version) keine weitere INDICATION-Nachricht gesendet werden sollte. Die SYNC-Nachricht enthält außerdem ein Feld für Erläuterungen und Gründe, das ausgefüllt wird, falls die Aktualisierung die Datenvalidierungen nicht besteht.

Anzahl der Aktualisierungen

Auch als „Version“ bezeichnet. Sie gibt an, in welcher Version sich eine bestimmte Aufgabe derzeit befindet. Auf GRIDSZ von GRIDSZ ist die Version der Master und kann nur erhöht werden oder unverändert bleiben (falls die Aktualisierung fehlschlägt).

Regeln des Equitri-Protokolls

Es gelten die folgenden allgemeinen Regeln:

  1. Die Schlüsselwörter „MUST“, „MUST NOT“, „REQUIRED“, „SHALL“, „SHALL NOT“, „SHOULD“, „SHOULD NOT“, „RECOMMENDED“, „MAY“ und „OPTIONAL“ in diesem Dokument sind gemäß der Beschreibung in RFC 2119 zu interpretieren.
  2. HTTP-Header, die nicht erkannt werden, werden stillschweigend ignoriert.
  3. Wenn eine Partei eine Aufgabe an eine andere Partei sendet und diese Aufgabe unmittelbar danach bei derselben Partei abruft, enthält die empfangene Aufgabe genau dieselben Daten wie das Original.
  4. Wenn Sie eine INDICATION für eine Aufgabe erhalten, dürfen Sie selbst keine INDICATION für diese Aufgabe senden, bevor Sie nicht zunächst die eingehende INDICATION mit FETCH und SYNC abgerufen haben.
  5. Wenn mehrere Aktualisierungen für dieselbe Aufgabe eingehen, ist nur die letzte Aktualisierung (d. h. die mit dem höchsten „updateCount“) relevant. Ältere Aktualisierungen werden übersprungen.
  6. Eine Aufgabe bezieht sich immer auf 1 TASK auf 1 Verbindung. Die Verbindung (DHid) und der taskType einer bestehenden Aufgabe dürfen nicht geändert werden.

Schema erneut versuchen

Es kann zu Problemen kommen – und irgendwann wird es auch dazu kommen. Immer wenn die Aktualisierung einer bestehenden Aufgabe fehlschlägt, muss sich die Partei auf das Wiederholungsschema verlassen:

  • Sofern kein SYNC zurückgesendet wird, werden die INDICATION-Nachrichten von der Gegenstelle auf unbestimmte Zeit erneut gesendet.
  • Da der Empfang einer INDICATION häufig als Auslöser für einen FETCH und einen SYNC dient, beträgt die Mindestzeit zwischen zwei INDICATION-Anfragen für dieselbe Aufgabe 10 Sekunden und beginnt in der Produktion in der Regel bei 1 Minute.
  • Implementierungen von Equitri könnten ein progressives Backup implementieren, bei dem sich die Wartezeit zwischen zwei Abfrageanfragen nach jeder Anfrage bis zu einem Maximum von 1 INDICATION pro 4 Stunden verlängert.

Alle INDICATON-Anfragen für dieselbe Kombination aus Aufgabe und Aktualisierungsanzahl gehören zur selben Konversation.

Relative Aufgabenversionierung

Es ist möglich und sogar wahrscheinlich, dass es zu einem bestimmten Zeitpunkt zu Ausfällen bei einem oder mehreren Systemen der an einer Aufgabe beteiligten Parteien kommt. Außerdem reagieren die Parteien mit unterschiedlicher Häufigkeit auf Aktualisierungen innerhalb einer Aufgabe. Um Versionskonflikte zu vermeiden, verfügt die Equitri-Aufgabe stets über einen „updatecount“. Der „updatecount“ fungiert als eine Art Versionsnummer. Bei einer neuen Aufgabe muss er immer mit dem ganzzahligen Wert 1 beginnen. Bei jeder Aktualisierung, die eine Partei an andere Parteien übermittelt, muss der „updateCount“ im Vergleich zum aktuellen Wert um (mindestens) 1 erhöht werden.
Wenn der „updateCount“ 500 oder mehr beträgt, ist die Aufgabe in eine (möglicherweise endlose) Schleife geraten. Das integrierte System sollte keine weiteren INDICATION-Meldungen für diese Aufgabe senden und sicherstellen, dass manuelle Maßnahmen ergriffen werden, um die Situation zu beheben.

updateCount ist kleiner oder gleich dem aktuellen updateCount

Dies geschieht, wenn eine andere Partei eine Aktualisierung zu einer früheren Version der Aufgabe sendet. Die andere Partei war wahrscheinlich offline und hat die letzten Aktualisierungen zur Aufgabe nicht erhalten. Die Version der Aufgabe GRIDSZgilt als Master.
Beispielsweise werden Kommentare, die in der Version des integrierten Systems nicht vorhanden waren, in der richtigen Reihenfolge eingefügt. Anhänge können hinzugefügt werden. Sogar der Status der Aufgabe kann aktualisiert werden, jedoch nur, wenn dies nicht mit dem Status in der aktuellen Aufgabenversion kollidiert.
Nach der Zusammenführung führt das System eine Synchronisierung mit der anderen Partei durch, um zu signalisieren, dass die Aufgabenaktualisierung empfangen und verarbeitet wurde. Für die Synchronisierung ist es wichtig, dass das integrierte System denselben „updateCount“ aufweist wie die aktuell auf GRIDSZ befindliche Version. Wird ein niedrigerer „updateCount“ synchronisiert, sollte das System, das die „INDICATION“ initiiert hat, weiterhin „INDICATIONS“ für den nicht synchronisierten neuesten „updateCount“ senden.
Anschließend kann das integrierte System eine neue Konvertierung starten, beginnend mit einer „INDICATION“, um die andere Partei auf den aktuellen Stand Ihrer Aufgabenversion zu bringen.
Hinweis: Es ist für GRIDSZ NICHT möglich GRIDSZ einer früheren Version GRIDSZ . Die aktuelle Version ist und bleibt maßgeblich, auch wenn das andere System dies nicht akzeptieren kann.

UpdateCount ist größer als der aktuelle UpdateCount

Dies ist das „Sunny-Day“-Szenario. Eine der beiden Parteien hat eine Aktualisierung vorgenommen und ist nun in Bezug auf die Aktualisierungen weiter fortgeschritten als die andere Seite. Die Version der Aufgabe mit dem niedrigeren „updateCount“ wird als veraltet gelten. Und die empfangene Version der Aufgabe (mit dem höheren „updateCount“) dient fortan als neue „Wahrheit“.
Nun besteht die Aufgabe darin, die empfangene und die gespeicherte Aufgabe zu einer neuen, konsistenten Version zusammenzuführen. Meistens ist dies so einfach wie das Überschreiben der alten Version der Aufgabe durch die abgerufene Version. Komplizierter wird es, wenn die empfangene Aktualisierung für die andere Seite nicht akzeptabel ist. Zum Beispiel, wenn GRIDSZ die Aufgabe im Endstatus GRIDSZ und dann eine Aktualisierung vom integrierten System erhält, die sie wieder in den offenen Status versetzen soll.
In diesem Fall GRIDSZ ein SYNC zurück, in dem die Klarstellung und der Grund angegeben GRIDSZ . Dies bedeutet automatisch, dass die Version nicht akzeptiert wird und die vorherige Version weiterhin als gültig gilt. Da GRIDSZ zu einer früheren Version zurückkehren GRIDSZ , wird jede SYNC-Nachricht, bei der der „updateCount“ dem aktuellen „updateCount“ entspricht, als „SYNC-ok“ vom integrierten System gewertet, selbst wenn die Klarstellung und der Grund angegeben sind.
Wird überhaupt keine SYNC-Nachricht gesendet, leitet das andere System das Wiederholungsschema ein und sendet weiterhin INDICATION-Nachrichten. In solchen Szenarien wird empfohlen, die Ursache dafür zu ermitteln, warum die Aktualisierung nicht akzeptiert wird. Falls es sich um eine unerwartete JSON-Antwort oder einen unerwarteten Wert handelt, wenden Sie sich am besten an GRIDSZ dies gemeinsam weiter GRIDSZ untersuchen.
Hinweis: Es ist für GRIDSZ NICHT möglich GRIDSZ einer früheren Version GRIDSZ . Die aktuelle Version ist und bleibt maßgeblich, auch wenn das andere System dies nicht akzeptieren kann.

Support Smoke-Tests

Das Protokoll unterstützt einen optionalen HTTP-Header namensgridsz“. Ist dieser HTTP-Header in einer Anfrage vorhanden und hat er den Wert „TRUE“, so ist dies ein Hinweis darauf, dass die betreffende Konversation Teil eines Tests ist. In der Regel wird dieser Header für Smoke-Tests in der Produktionsumgebung verwendet. Er ist wie gewohnt zu verarbeiten, es sollten jedoch keine tatsächlichen physischen Aktionen durchgeführt werden. Parteien, die das Equitri-Protokoll implementieren, werden dazu angehalten, eine Protokollierung auf Debug-Ebene zu implementieren, die durch diesen Headergridsz ausgelöst wird.

Eine normale Aufgabe (die ohne den Headergridsz erstellt wurde), die eine Aktualisierung mit dem Headergridsz erhält, ist ein Grund zur Besorgnis. Möglicherweise werden Testaufgaben und normale Aufgaben verwechselt. Eine Testaufgabe (die mit dem Headergridsz erstellt wurde), die eine Aktualisierung ohne den Headergridsz erhält, ist kein Grund zur Beunruhigung. Möglicherweise support die Gegenpartei support HTTP-Header nicht.
Bei der Verwendung von Testaufgaben in der Produktionsumgebung ist Vorsicht geboten. Stellen Sie sicher, dass alle Beteiligten auf dem gleichen Stand sind, um zu verhindern, dass tatsächliche Arbeiten physisch ausgeführt werden.

GRIDSZ : Eine bestehende Aufgabe GRIDSZ oder eine neue Aufgabe erstellen

Dies lässt sich in drei Schritte unterteilen: die eingehende Abfrage (Gridsz das integrierte System), die Abrufanfrage (das integrierte System stellt Informationen an Gridsz bereit) und die Synchronisierung zur Bestätigung.

1. Eingangsanzeige

Die von Gridsz initiierte Indikation:

  1. Autorisieren Sie die Anfrage wie bei der Implementierung vereinbart auf der Grundlage der in Gridsz gespeicherten Autorisierungsdaten Gridsz möglicherweise ist die Erfassung eines OAuth-2.0-Tokens erforderlich).
  2. (Wenn der Headergridsz den Wert „TRUE“ hat, aktivieren Sie die Debug-Protokollierung.)
  3. Lies „updateCount“ aus der INDICATION aus
  4. (Möglich: Protokollierung: „Empfang einer Aktualisierungsanforderung mit dem Wert ‚updatecount‘ für die Task-ID von der Org-ID“)
  5. Speichern Sie die Information, dass für die Aufgabe ein Update verfügbar ist, zusammen mit den folgenden Daten:
    • orgId (erforderlich)
    • systemId (erforderlich)
    • taskId (erforderlich)
    • updateCount (muss angegeben werden)
    • x-request-id (könnte),
    • x-correlation-id (könnte)
    • requesttime (könnte)
    • Wert vongridsz(muss angegeben werden, falls vorhanden)
  6. Lösche frühere Aktualisierungseinträge für dieselbe orgId und taskId mit niedrigerem updatecount

2. Ausgehender Abruf

Der Abruf von Gridsz:

  1. Ermitteln Sie den aufzurufenden Endpunkt anhand der Umgebung, der OrgId und der TaskId in der INDICATION
  2. (Den Wert für „x-gridz-test“ auslesen und, falls vorhanden, den HTTP-Headergridsz auf diesen Wert setzen)
  3. FETCH-Anfrage an den Endpunkt senden; Informationen zur neuen Aufgabe abrufen
  4. Überprüfen Sie, ob die Aufgabendaten korrekt formatiert sind:
    • Gültiges JSON, das der Open-API-Definition für die neueste API-Version entspricht
    • Gültiges JSON, das die Geschäftsvalidierungen besteht
  5. Wenn die Aufgabe nicht korrekt formatiert ist: Ermitteln Sie die Ursache und wenden Sie sich Gridsz Bedarf an Gridsz :
    Hinweis: GRIDSZ lange „INDICATION“, bis ein „SYNC“ gesendet wurde:
    (ENDE DES FLOWS)
  6. Wenn die Daten korrekt formatiert sind:
    • Die Aufgabe im Aufgabenspeicher sperren
    • Alte Aufgabeninformationen aus dem Aufgabenspeicher auslesen
    • Aufgaben zwischen alten und neuen Aufgabeninformationen zusammenführen
    • Wenn das Ergebnis der Zusammenführung von den alten Aufgabeninformationen abweicht, werden die zusammengeführten Aufgabeninformationen in den Aufgabenspeicher geschrieben.
    • Die Aufgabe im Aufgaben-Speicher entsperren
  7. SYNC an den Endpunkt senden.

3. Synchronisierung ausgehender Daten

Die Synchronisierung zur Bestätigung:

  1. SYNC-Anfrage an den Endpunkt des FETCH senden
  2. Für eine SYNC-Nachricht gibt es keinen Wiederholungsversuch. Wenn die Anfrage/Antwort fehlschlägt, können Sie die Ausnahme sowie etwaige Fehlercodes und Erläuterungen, die in der SYNC-Nachricht enthalten sind, protokollieren. Verlassen Sie sich auf das Wiederholungsschema der Gegenpartei, um einen erneuten Versuch zu unternehmen.
  3. Die während der Anzeige geschriebenen Aktualisierungsinformationen löschen

Integriertes System zur Aktualisierung einer bestehenden Aufgabe oder zur Erstellung einer neuen Aufgabe

Dies lässt sich wiederum in drei Schritte unterteilen: die Abfrageanforderung (das integrierte System an Gridsz), die Abrufanforderung (Gridsz Informationen aus dem integrierten SystemGridsz ) und die Synchronisierung zur Bestätigung.

1. Ausgangsanzeige

Das integrierte System erkennt eine Änderung (die Gridsz vorangegangenen Szenario nicht von Gridsz verursacht wurde) und möchte Gridsz informieren, indem es eine Meldung an Gridsz sendet:

  1. Autorisieren Sie die Anfrage gemäß der bei der Implementierung getroffenen Vereinbarung (möglicherweise ist die Erfassung eines OAuth 2.0-Tokens erforderlich).
  2. (Wenn der Headergridsz den Wert „TRUE“ hat, aktivieren Sie die Debug-Protokollierung.)
  3. Erhöhe den Wert „updateCount“, der im bestehenden Aufgabendatensatz im integrierten System gespeichert ist, um 1 (verwende 1 für neue Aufgaben)
  4. (Möglich: Protokollierung: „Sendeanzeige für Update updateCount bei taskId aus orgId“)
  5. Senden Sie eine Meldung an Gridsz den folgenden Daten:
    • orgId (erforderlich)
    • systemId (erforderlich)
    • taskId (erforderlich)
    • updateCount (muss angegeben werden)
    • x-request-id (könnte),
    • x-correlation-id (könnte)
    • requesttime (könnte)
    • Wert vongridsz(muss angegeben werden, falls vorhanden)

Warten Sie nicht auf eine Antwort und versuchen Sie auch nicht, diese auszulesen. Versuchen Sie nicht, eine Ausnahme abzufangen, sondern verlassen Sie sich auf das Wiederholungsschema, um den Vorgang erneut zu versuchen.

2. Eingehende Abfrage

Gridsz auf die Anweisung aus dem vorherigen Schritt, indem Gridsz die Aufgabe vom vereinbarten Endpunkt abruft:

  1. Nehmen Sie den Anruf am Endpunkt auf der Grundlage der vereinbarten Authentifizierung entgegen
  2. (Den Wert für „x-gridz-test“ auslesen und, falls vorhanden, den HTTP-Headergridsz auf diesen Wert setzen)
  3. Wenn die Aufgabe im integrierten System nicht gefunden wird, einen 404-Fehler zurückgeben
  4. Bereitstellung von FETCH-Informationen durch Laden und Aufbereiten der Aufgabeninformationen aus dem integrierten System

3. Eingehende Synchronisierung

Gridsz die Informationen aus dem vorherigen Schritt und sendet einen PUT-Befehl an den Endpunkt, um die Synchronisierung zu bestätigen:

  1. Die authentifizierte SYNC-Anfrage an den Endpunkt des FETCH verarbeiten
  2. Wenn der SYNC-Eintrag einen Grund und eine Erläuterung enthält, bedeutet dies, dass GRIDSZ die Aktualisierung nicht akzeptiert GRIDSZ und die vorherige Version weiterhin als Master gilt.

Der „Indication-Fetch-Sync“-Vorgang läuft möglicherweise nicht immer reibungslos ab, doch das Protokoll sollte, wie oben beschrieben, einen ordnungsgemäßen Wiederholungsversuch durchführen. Allerdings sollten Fehlercodes und Erläuterungen aus dem Synchronisierungsschritt ordnungsgemäß verarbeitet (und den Benutzern gemeldet) werden, um Endlosschleifen zu vermeiden.