Sync ή async integration στο Boomi

Ένας συνεργάτης θέλει να σας στέλνει παραγγελίες μέσω API. Ο προφανής σχεδιασμός είναι: δέξου την παραγγελία, δημιούργησέ την στο ERP, απάντησε με τον αριθμό παραγγελίας του ERP. Στις δοκιμές δουλεύει τέλεια. Μετά το ERP είναι αργό ένα πρωινό Δευτέρας, οι κλήσεις του συνεργάτη αρχίζουν να κάνουν timeout, εκείνος ξαναδοκιμάζει, και καταλήγετε με διπλές παραγγελίες. Σε αυτό το άρθρο εξηγούμε πότε το σύγχρονο request-reply είναι η σωστή επιλογή, πότε δεν είναι, και φτιάχνουμε το ίδιο API με τους δύο τρόπους στο Boomi.

Το πρόβλημα της αναμονής

Σε έναν σύγχρονο σχεδιασμό, αυτός που καλεί περιμένει όσο το integration κάνει όλη τη δουλειά:

Συνεργάτης ──► API ──► mapping ──► δημιουργία στο ERP ──► απάντηση (5-30 s)

Αυτό είναι εντάξει όταν η δουλειά είναι γρήγορη και ο καλών χρειάζεται το αποτέλεσμα. Γίνεται πρόβλημα όταν:

Το backend είναι αργό ή απασχολημένο. Το ERP θέλει 20 δευτερόλεπτα στο κλείσιμο του μήνα, και ο HTTP client του καλούντος τα παρατάει στα 15.
Το backend είναι εκτός λειτουργίας. Συντήρηση στο ERP σημαίνει ότι το API επιστρέφει σφάλματα, ενώ θα μπορούσατε απλώς να δεχτείτε τις παραγγελίες και να τις δημιουργήσετε μία ώρα αργότερα.
Ο όγκος έρχεται σε κύματα. Ένας συνεργάτης στέλνει 2.000 παραγγελίες στις 09:00. Η καθεμία κρατά μια σύνδεση ανοιχτή όσο περιμένει.
Τα timeouts φέρνουν διπλότυπα. Ο καλών κάνει timeout, αλλά η δική σας πλευρά ολοκλήρωσε τη δουλειά. Ξαναδοκιμάζει και η παραγγελία δημιουργείται δύο φορές.

Το pattern: δέξου τώρα, επεξεργάσου αργότερα

Σε έναν ασύγχρονο σχεδιασμό, το API κάνει μόνο τα ελάχιστα όσο περιμένει ο καλών: ελέγχει ότι το αίτημα είναι έγκυρο, το αποθηκεύει με ασφάλεια σε μια ουρά, και απαντά 202 Accepted με ένα ID παρακολούθησης. Ένα ξεχωριστό process παίρνει τα μηνύματα από την ουρά και κάνει την πραγματική δουλειά με τον ρυθμό που αντέχει το ERP.

Συνεργάτης ──► API: έλεγχος + ουρά ──► 202 Accepted { "trackingId": "..." }
                         │
                         ▼
                ουρά ──► worker: mapping ──► δημιουργία στο ERP

Ο καλών μπορεί να ελέγξει το αποτέλεσμα αργότερα μέσα από ένα endpoint κατάστασης, ή να λάβει ένα callback.

Πώς διαλέγετε

Ερώτηση	Προς sync	Προς async
Χρειάζεται ο καλών το αποτέλεσμα για να συνεχίσει;	ναι (απόθεμα, τιμή)	όχι (παραγγελία, τιμολόγιο)
Πόσο διαρκεί η δουλειά;	κάτω από 1-2 δευτ.	δευτερόλεπτα έως λεπτά
Πρέπει να δουλεύει όταν το backend είναι κάτω;	όχι	ναι
Μπορεί η κίνηση να έρθει σε κύματα;	σπάνια	συχνά

Οι ερωτήσεις («ποιο είναι το απόθεμα του SKU-771;», «ποιο είναι το υπόλοιπο του πελάτη C-1042;») είναι εκ φύσεως σύγχρονες. Οι εντολές («δημιούργησε αυτή την παραγγελία») συνήθως δουλεύουν καλύτερα ασύγχρονα. Για ευρύτερη σύγκριση αυτών των patterns, δείτε τον οδηγό μας Integration patterns που πρέπει να ξέρει κάθε ομάδα.

Υλοποίηση στο Boomi

Και οι δύο εκδοχές ξεκινούν από τα ίδια δομικά στοιχεία: ένα process με start shape Web Services Server (action Listen) και ένα component API Service που το δημοσιεύει ως REST endpoint, όπως περιγράφουμε στο Το ERP σας ως REST API με το Boomi.

Εκδοχή 1: σύγχρονο request-reply

Start: Web Services Server, Listen, input type ένα JSON αντικείμενο (η παραγγελία), output type ένα JSON αντικείμενο (το αποτέλεσμα).
Έλεγχος: χρησιμοποιήστε ένα shape Decision ή Business Rules για τα υποχρεωτικά πεδία. Σε αποτυχία, ορίστε τον κωδικό απάντησης σε 400 και επιστρέψτε ένα σώμα σφάλματος.
Mapping και δημιουργία: ένα shape Map προς το profile της παραγγελίας του ERP, και μετά η κλήση του connector του ERP.
Απάντηση: κάντε mapping του αποτελέσματος του ERP στο profile της απάντησης (για παράδειγμα { "orderId": "SO-2026-0815" }) και τελειώστε με Return Documents.

Ο καλών παίρνει τον αριθμό παραγγελίας του ERP στην ίδια κλήση. Κρατήστε αυτή την εκδοχή για γρήγορες λειτουργίες, και γράψτε καθαρά στην τεκμηρίωση του API τι χρόνους απόκρισης να περιμένει ο καλών.

Εκδοχή 2: ασύγχρονο με 202 και ουρά

Χωρίστε τη δουλειά σε δύο processes.

Process A: ο παραλήπτης (τρέχει όσο περιμένει ο καλών)

Start: Web Services Server, Listen, ίδιο input profile με πριν.
Έλεγχος: οι ίδιοι έλεγχοι με την εκδοχή 1. Η άμεση απόρριψη λάθος δεδομένων είναι ακόμη χρήσιμη, γιατί ο καλών μπορεί να τα διορθώσει αμέσως.
ID παρακολούθησης: δημιουργήστε ένα ID (για παράδειγμα από το execution ID, ή ένα GUID μέσω map function) και αποθηκεύστε το ως document property.
Αποστολή στην ουρά: στείλτε την παραγγελία σε μια ουρά. Στο Boomi μπορείτε να χρησιμοποιήσετε τον connector Atom Queue σε runtimes που τον υποστηρίζουν, ή να δημοσιεύσετε σε ένα topic με τον connector Boomi Event Streams. Το Event Streams είναι managed υπηρεσία, οπότε τα μηνύματα δεν εξαρτώνται από τον δίσκο ενός runtime.
Απάντηση: ορίστε τον κωδικό απάντησης σε 202 και επιστρέψτε { "trackingId": "...", "status": "accepted" } με Return Documents.

Ο παραλήπτης δεν κάνει καμία δουλειά στο ERP, οπότε απαντά σε κλάσμα του δευτερολέπτου, ακόμη κι αν το ERP είναι κάτω.

Process B: ο worker (τρέχει στο παρασκήνιο)

Start: ένας listener στην ίδια ουρά ή στο ίδιο topic (connector Atom Queue ή Event Streams με operation Listen).
Mapping και δημιουργία: το ίδιο mapping και η ίδια κλήση στο ERP με την εκδοχή 1, μέσα σε ένα shape Try/Catch.
Καταγραφή αποτελέσματος: αποθηκεύστε το αποτέλεσμα ανά ID παρακολούθησης (για παράδειγμα σε έναν πίνακα, με κατάσταση CREATED και τον αριθμό παραγγελίας του ERP, ή FAILED και την αιτία).
Idempotency: πριν τη δημιουργία, ελέγξτε αν υπάρχει ήδη στο ERP παραγγελία με τον αριθμό παραγγελίας του συνεργάτη. Οι ουρές συνήθως παραδίδουν τουλάχιστον μία φορά, οπότε ο worker πρέπει να αντέχει διπλότυπα.

Προαιρετικά: endpoint κατάστασης

Προσθέστε ένα δεύτερο operation στο API Service, GET /orders/status/{trackingId}, με ένα μικρό process που διαβάζει τον πίνακα αποτελεσμάτων. Οι συνεργάτες μπορούν να το ρωτούν περιοδικά, ή μπορείτε να στέλνετε callback σε ένα URL που δηλώνουν.

Μια συντόμευση που καλό είναι να ξέρετε

Το shape Process Call του Boomi μπορεί να ξεκινήσει ένα sub-process χωρίς να περιμένει να τελειώσει. Δίνει γρήγορη απάντηση, αλλά η δουλειά τότε υπάρχει μόνο μέσα στην εκτέλεση του runtime και δεν αποθηκεύεται μόνιμα όπως ένα μήνυμα σε ουρά. Χρησιμοποιήστε το για μη κρίσιμη δουλειά, και πραγματική ουρά ή topic για ό,τι δεν αντέχετε να χάσετε.

Πριν βγείτε σε παραγωγή

Τεκμηριώστε το συμβόλαιο. Πείτε στους καταναλωτές ότι το 202 σημαίνει «έγινε δεκτό για επεξεργασία», όχι «δημιουργήθηκε», και πώς παίρνουν το τελικό αποτέλεσμα.
Παρακολουθήστε το βάθος της ουράς. Μια ουρά που μεγαλώνει είναι η πρώτη ένδειξη ότι ο worker δεν προλαβαίνει ή ότι το ERP είναι κάτω. Βάλτε ειδοποίηση.
Χειριστείτε τα «δηλητηριώδη» μηνύματα. Ένα μήνυμα που αποτυγχάνει πάντα δεν πρέπει να μπλοκάρει την ουρά. Μεταφέρετέ το σε dead-letter ή ουρά ελέγχου μετά από λίγες προσπάθειες (δείτε Dead-letter handling με το Boomi Event Streams).
Δοκιμάστε τη διακοπή. Σταματήστε τη σύνδεση με το ERP, στείλτε παραγγελίες, βεβαιωθείτε ότι παίρνετε ακόμη 202, μετά επαναφέρετέ την και ελέγξτε ότι κάθε παραγγελία δημιουργείται ακριβώς μία φορά.

Συνοψίζοντας

Το σύγχρονο request-reply είναι η σωστή επιλογή για γρήγορες ερωτήσεις που ο καλών θέλει να απαντηθούν τώρα. Για εντολές που αγγίζουν αργά ή εύθραυστα συστήματα, δεχτείτε το αίτημα, βάλτε το σε ουρά, απαντήστε 202 και επεξεργαστείτε το στο παρασκήνιο. Στο Boomi, τα ίδια δομικά στοιχεία Web Services Server και API Service υποστηρίζουν και τα δύο, και η διαφορά είναι μια ουρά ή ένα event stream ανάμεσα σε δύο processes. Για την ευρύτερη εικόνα, δείτε το Integration patterns που πρέπει να ξέρει κάθε ομάδα.