Richtlinien für die Clientimplementierung

Dieser Leitfaden enthält Architektur- und Implementierungsrichtlinien für Entwickler, die Universal Ledger API-Clients erstellen. Sie erfahren, wie Sie:

  • Netzwerktopologie für Hochverfügbarkeit nutzen
  • Transaktionen senden und Ausführungsergebnisse verstehen.
  • Implementieren Sie Abfragen, Zeitüberschreitungen und Wiederholungsstrategien.

Verbindung zu einem Universal Ledger API-Endpunkt herstellen

Anfragen werden über die Universal Ledger API an einen bestimmten Netzwerkendpunkt weitergeleitet. Netzwerkendpunkte sind regionale Cloud-Ressourcen, die Anfragen an Validatoren innerhalb dieser Region verteilen. Um einen Netzwerkendpunkt zu erreichen, müssen Clients eine Verbindung zum regionalen API-Endpunkt (REP) herstellen, der der Cloud-Region entspricht, in der sich der Netzwerkendpunkt befindet.

Namen regionaler Endpunkte haben folgendes Format:

universalledger.REGION.rep.googleapis.com

Ersetzen Sie REGION durch die unterstützte Region, in der sich Ihr Netzwerkendpunkt befindet.

Netzwerktopologie und Hochverfügbarkeit

Ein Universal Ledger-Netzwerk besteht aus einer Reihe von Validatoren, die auf mehrere Zonen und Regionen verteilt sind. Dadurch wird eine Hochverfügbarkeit für das gesamte Netzwerk gewährleistet.

  • Zonenausfälle: Wenn ein einzelner Validator innerhalb einer Cloud-Zone ausfällt, verarbeiten andere Validatoren innerhalb derselben Region weiterhin nahtlos Anfragen.

  • Regionale Ausfälle: Wenn eine ganze Region nicht mehr verfügbar ist, bleiben Validatoren in anderen Regionen betriebsbereit. Wenn Sie weiterhin Transaktionen senden möchten, kann Ihr Client ein Fallback ausführen und versuchen, Transaktionen über einen anderen Endpunkt noch einmal zu senden.

Merkmale der Transaktionsausführung

  • Atomare Ausführung: Transaktionen sind entweder vollständig erfolgreich oder schlagen vollständig fehl. Eine teilweise Transaktionsausführung, z. B. die Übertragung nur eines Teils der angeforderten Mittel aufgrund eines unzureichenden Guthabens, findet nie statt. Dazu gehören Transaktionsketten, mit denen Sie mehrere beliebige Transaktionen zu einer einzigen atomaren Sequenz kombinieren können.

  • Keine automatischen Wiederholungsversuche: Das Netzwerk versucht, eine gesendete Transaktion genau einmal auszuführen. Wenn die Ausführung fehlschlägt, wird die Transaktion nicht automatisch in die Warteschlange gestellt oder wiederholt.

  • Idempotente erneute Übermittlung: Für jede übermittelte Transaktion wird eine eindeutige Transaktions-ID generiert, die auf der genauen serialisierten Nutzlast (einschließlich Sequenznummer und Absender) basiert. Wenn Sie dieselbe Nutzlast mehrmals senden, wird dieselbe Transaktions-ID generiert. Das Ledger sorgt dafür, dass eine Transaktion höchstens einmal ausgeführt wird. Daher ist es sicher, dieselbe Transaktionsnutzlast an einen anderen Endpunkt zu senden, wenn einer der Endpunkte nicht verfügbar ist.

    Weitere Informationen finden Sie auf der Referenzseite zu SubmitTransactionRequest.

Latenz, Abfrage und Wiederholungsstrategie

Wenn Sie eine Transaktion senden, führt der Validator zuerst eine schnelle Prüfung durch, um sicherzustellen, dass die Signaturen und Sequenznummern gültig sind. Bei Erfolg antwortet die Universal Ledger API sofort mit einer SubmitTransactionResponse, einschließlich der zugewiesenen Transaktions-ID.

Die meisten Transaktionen werden innerhalb von 3 Sekunden abgeschlossen. Wenn Sie den Transaktionsstatus prüfen möchten, rufen Sie die Methode QueryTransactionState mit der angegebenen Transaktions-ID auf.

  • Wenn der Transaktionsstatus immer noch PENDING lautet, rufen Sie den Status noch einmal mit einer exponentiellen Backoff-Strategie ab. Fragen Sie beispielsweise in Intervallen von 3 Sekunden, 9 Sekunden, 27 Sekunden und 60 Sekunden ab.

  • Wenn QueryTransactionState den Wert NOT_FOUND zurückgibt, senden Sie die Transaktion noch einmal.

Sobald ein Transaktionsversuch FINALIZED ist, enthält die Antwort auch ein TransactionCertificate mit verschiedenen Details, z. B.:

  • Die Runde-ID, bei der die Transaktion abgeschlossen wurde.
  • Der Ausführungsstatus (OK oder fehlgeschlagen).
  • Transaktionsereignisse, einschließlich aller Transaktionsausgaben.

Zeitüberschreitungsprotokoll

In dem unwahrscheinlichen Fall, dass eine Transaktion nach 60 Sekunden im Status PENDING oder NOT_FOUND verbleibt, ist davon auszugehen, dass der Validator, der Ihre Anfragen verarbeitet, nicht mit anderen Validatoren im Netzwerk Schritt halten kann. Führen Sie diese Schritte aus:

  1. Wählen Sie einen anderen Endpunkt in einer anderen Netzwerkregion aus.
  2. Senden Sie die genau gleiche signierte Transaktionsnutzlast noch einmal.
  3. Melden Sie das Problem über den Button „Feedback geben“ oben auf dieser Seite, damit das Universal Ledger-Team es untersuchen kann.

Wenn Sie den Transaktionsstatus prüfen, enthält die Antwort möglicherweise mehrere TransactionAttempt-Nachrichten, wenn Sie dieselbe Nutzlast mehrmals gesendet haben. Höchstens ein Versuch wird mit dem Transaktionsstatus „OK“ abgeschlossen, der im TransactionEffects zu finden ist. Andere Versuche sind entweder ausstehend oder haben den Status „Fehlgeschlagen“. Dies ist das erwartete Verhalten. Das Ledger hat eine der Transaktionseinreichungen erfolgreich ausgeführt und die duplizierten erneuten Einreichungen korrekt abgelehnt oder wird sie schließlich ablehnen.

Netzwerkkonsistenz

  • Abgeschlossene Transaktionen: Sobald eine Transaktion von einem Validator als abgeschlossen gemeldet wird, müssen alle anderen Validatoren im selben Netzwerk die Transaktion schließlich verarbeiten und genau dieselben Ergebnisse reproduzieren. Wenn Sie eine QueryAccountRequest mit der Runden-ID einreichen, bei der die Transaktion abgeschlossen wurde, wie sie in der TransactionCertificate zu finden ist, erhalten Sie auf allen synchronisierten Validatoren identische Ergebnisse.

  • Nicht abgeschlossene Transaktionen: Da Transaktionen asynchron über das Netzwerk verteilt werden, kann es je nach Validator variieren, ob eine Transaktion als abgeschlossen gemeldet wird.

    Ein Validator, der sich von einem Ausfall erholt oder eine Synchronisierungsverzögerung hat, meldet eine abgeschlossene Transaktion möglicherweise vorübergehend als PENDING oder NOT_FOUND. Der Transaktionsstatus wird aufgelöst, sobald der Validator aufholt.

Pflichten des Kunden und Fehlerbehandlung

  • Transaktions-Tracking: Clientanwendungen müssen den Status aller gesendeten Transaktionen verfolgen, bis sie abgeschlossen sind.

  • Fehlerbehandlung: Wenn eine Transaktion fehlschlägt, rufen Sie die Fehlerdetails in der TransactionCertificate ab und prüfen Sie sie, um die entsprechende Fehlerbehebung auf Geschäftsebene auszulösen.

Nächste Schritte