Bekräftelseåteranrop

En bekräftelseåterkoppling låter din klient reagera asynkront på bekräftelser och fel på inspelningar, utan att blockera din producentloop. När skivor blir hållbara eller misslyckas, aktiverar Zerobus Ingest din callback i bakgrunden, så att du kan följa framsteg och uppdatera mätvärden utan att sakta ner din producent, och få reda på misslyckanden så fort de inträffar.

Detta skiljer sig från att vänta på en offset eller att tömma bufferten: detta är blockerande anrop där din kod väntar på beständighet direkt i körflödet. En återkallelse är inte ett blockeringssamtal. Det är en hanterare som SDK:n anropar åt dig när bekräftelser anländer.

Återanrop för bekräftelser stöds för JSON- och Protocol Buffers-dataströmmar i SDK:t. Arrow Flight-strömmar stöder inte återanrop; för att bekräfta beständighet för en Arrow-ström, använd wait_for_offset() eller flush(). Se Använda pilflygning med Zerobus-inmatning.

Metod- och typnamn nedan kommer från Python SDK. Andra Zerobus SDK:er tillhandahåller återanrop för bekräftelser där detta stöds, med motsvarande konstruktioner i respektive språk.

Hur återanrop fungerar

Du definierar en callback genom att subclassa AckCallback och implementera två metoder:

  • on_ack(offset: int): anropas när en inlämning (en post eller en batch) framgångsrikt bekräftas som hållbar av servern. Den offset identifierar den bekräftade insändningen.
  • on_error(offset: int, error_message: str): anropas när en submission stöter på ett fel. on_error är valfritt. Implementera det för att hantera eller logga fel.

Återanropet anropas en gång för varje inskickad datapost eller batch när dess logiska offset bekräftas eller när det misslyckas, så det fungerar som en löpande signal om inmatningens förlopp i hela strömmen.

Dina callback-metoder körs på SDK:ns bakgrundstrådar, så att anropa dem blockerar inte din producent. Håll dem snabba och utan att blockera. Vad man ska göra åt ett misslyckande är din klients ansvar: logga, larma, försöka igen eller stoppa. Vissa fel är terminala, och om on_error rapporterar att strömmen har fallerat permanent måste du återhämta dig med en ny ström. Se återhämtnings- och återförsöksmönster.

Konfigurera ett återanrop

Du kopplar ett återanrop till en ström genom att ange en instans av din AckCallback-underklass som alternativet ack_callback i StreamConfigurationOptions när du skapar strömmen. Callbacken gäller sedan för varje post som tas in i den streamen.

from zerobus.sdk.sync import ZerobusSdk
from zerobus.sdk.shared import AckCallback, StreamConfigurationOptions, TableProperties

class MyAckCallback(AckCallback):
    def on_ack(self, offset: int) -> None:
        print(f"Record acknowledged at offset: {offset}")

    def on_error(self, offset: int, error_message: str) -> None:
        print(f"Error at offset {offset}: {error_message}")

sdk = ZerobusSdk(SERVER_ENDPOINT, DATABRICKS_WORKSPACE_URL)

table_properties = TableProperties("main.default.air_quality")
options = StreamConfigurationOptions(
    ack_callback=MyAckCallback(),
)
stream = sdk.create_stream(CLIENT_ID, CLIENT_SECRET, table_properties, options)

try:
    for row in records:
        stream.ingest_record_offset(row)
finally:
    stream.close()

När återuppringningen är registrerad behöver du inte vänta i kön. on_ack utlöses när varje post har bekräftats som varaktigt lagrad, och on_error utlöses om en post misslyckas.

Callback-funktioner kontra blockering

Callbacks och blockeringsanrop löser olika problem, och du kan använda dem tillsammans:

  • Använd en bekräftelseåterkoppling för att reagera på hållbarhetsbekräftelser och fel när de inträffar, asynkront, samtidigt som hög genomströmning upprätthålls. Bra för framstegsspårning, mätvärden och felregistrering.
  • Använd wait_for_offset() eller flush() när din kod måste blockeras tills en specifik post, eller alla väntande poster, är hållbara innan du fortsätter.