HTTP API

Το HTTP API είναι το περιβάλλον ενσωμάτωσης του Beam Bench. Οι περισσότερες εντολές CLI και οι εξωτερικοί πελάτες χρησιμοποιούν αυτές τις διαδρομές. Το περιβάλλον εργασίας υπολογιστή καλεί την κοινόχρηστη υπηρεσία μέσω Tauri IPC και δεν απαιτεί τον διακομιστή HTTP για κανονική χρήση. Αν έχετε περίπτωση χρήσης που χρειάζεται το Beam Bench σε περιβάλλον εκτός CLI, όπως web εφαρμογή, διακομιστή ενσωμάτωσης, εφαρμογή κινητού ή δικά σας εργαλεία, χρησιμοποιήστε απευθείας το API.

Το API παρέχεται μαζί με την εφαρμογή υπολογιστή και εκτελείται εντός της ίδιας διεργασίας. Δεν υπάρχει ξεχωριστή υπηρεσία για εγκατάσταση.

Προεπιλογές και ασφάλεια

Στην τρέχουσα έκδοση, ο τοπικός διακομιστής API παρέχεται με αυτές τις ρυθμίσεις:

• Τοπικό API: απενεργοποιημένο.
• Θύρα API: 5900.
• Να επιτρέπεται η σύνδεση συσκευών δικτύου: απενεργοποιημένο. Όταν το API είναι ενεργοποιημένο, συνδέεται στη 127.0.0.1 και δέχεται συνδέσεις μόνο από αυτόν τον υπολογιστή.

Το API δεν ακούει για συνδέσεις μέχρι να επιλέξετε να το ενεργοποιήσετε. Η ενεργοποίηση της πρόσβασης δικτύου απαιτεί ξεχωριστή ρητή επιλογή, επειδή το API δεν διαθέτει έλεγχο ταυτότητας και περιλαμβάνει λειτουργίες που μπορούν να μετακινήσουν το μηχάνημα και να ενεργοποιήσουν το λέιζερ.

Για να χρησιμοποιήσετε το API, αλλάξτε τις ρυθμίσεις του από τις Ρυθμίσεις → Γενικά:

1. Ανοίξτε την εφαρμογή υπολογιστή.
2. Επεξεργασία → Ρυθμίσεις → Γενικά.
3. Ενεργοποιήστε το Τοπικό API.
4. Αφήστε απενεργοποιημένο το Να επιτρέπεται η σύνδεση συσκευών δικτύου, εκτός αν πρέπει να συνδεθεί άλλη αξιόπιστη συσκευή.

Οι αλλαγές εφαρμόζονται αμέσως, χωρίς επανεκκίνηση.

Βασικό URL

http://<host>:5900/api/v1

Το <host> είναι localhost ή 127.0.0.1 όταν το Να επιτρέπεται η σύνδεση συσκευών δικτύου είναι απενεργοποιημένο. Όταν είναι ενεργοποιημένο, ο διακομιστής είναι προσβάσιμος στη διεύθυνση IP LAN του μηχανήματος από οποιαδήποτε συσκευή του δικτύου.

Η θύρα μπορεί να ρυθμιστεί στις Ρυθμίσεις → Γενικά, ενώ η προεπιλογή είναι 5900.

Έλεγχος ταυτότητας

Κανένας. Το API δεν διαθέτει διακριτικό, κλειδί ή σύνδεση.

• Με σύνδεση localhost, το όριο είναι το μοντέλο πρόσβασης σε επίπεδο λειτουργικού συστήματος: κάθε διεργασία στον υπολογιστή σας μπορεί να επικοινωνήσει με το API.
• Με ενεργοποιημένη σύνδεση δικτύου, οποιοσδήποτε στο ίδιο δίκτυο μπορεί να επικοινωνήσει με το API. Μην χρησιμοποιείτε τη λειτουργία σύνδεσης δικτύου σε μη αξιόπιστο Wi-Fi.

Μορφή αιτήματος

Όλα τα σώματα POST/PATCH/PUT είναι JSON:

Content-Type: application/json

Τα συμβολοσειρά ερωτήματος είναι επίπεδα key=value. Τα τμήματα διαδρομής κωδικοποιούνται ως URL, όπως συνήθως.

Περίβλημα απόκρισης

Οι επιτυχείς αποκρίσεις επιστρέφουν απευθείας το σώμα του πόρου, χωρίς περίβλημα:

{
  "field": "value",
  "...": "..."
}

Τα σφάλματα επιστρέφουν ομοιόμορφο περίβλημα:

{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

Το error.code είναι ένα από τα εξής:

Σφάλματα που απαιτούν επιβεβαίωση

Ένα μικρό σύνολο λειτουργιών μπορεί να μετακινήσει το μηχάνημα ή να ενεργοποιήσει το λέιζερ. Αυτά τα endpoint απαιτούν ρητή σημαία επιβεβαίωσης στο σώμα του αιτήματος. Αν λείπει, το API επιστρέφει 428 Precondition Required:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Στείλτε ξανά το αίτημα με την επώνυμη σημαία ορισμένη σε true. Οι σημαίες που χρησιμοποιούνται επί του παρόντος είναι confirm_motion, confirm_laser_on, confirm_raw_gcode και confirm_air_assist.

Ταυτόχρονες επεξεργασίες έργου

Οι συναλλαγές σχεδίασης συγκρίνουν το έργο που κατέγραψαν κατά τη στιγμή της υποβολής. Μια ταυτόχρονη επεξεργασία, αλλαγή έργου ή κλείσιμο μπορεί να επιστρέψει stale_revision. Ανανεώστε την κατάσταση και επανεκτιμήστε την αλλαγή πριν από την επανάληψη. Μην επαναφέρετε άκριτα ένα παλαιότερο στιγμιότυπο έργου πάνω από νεότερη εργασία.

Ομάδες endpoint

Οι σελίδες αναφοράς ανά πόρο βρίσκονται ακόμη υπό ανάπτυξη. Στο μεταξύ, συμβουλευτείτε το σχήμα δυνατοτήτων του πράκτορα.

Ανακαλύψτε το ενεργό περιβάλλον

Ο ταχύτερος τρόπος για να δείτε τι παρέχει η εγκατεστημένη έκδοσή σας:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Αυτό επιστρέφει το πλήρες σχήμα δυνατοτήτων, συμπεριλαμβανομένων κάθε endpoint, των παραμέτρων του και της μορφής της απόκρισής του. Το σχήμα είναι η έγκυρη περιγραφή, ενώ αυτή η σελίδα αποτελεί οδηγό.

Για έλεγχο της κατάστασης:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Για γραπτή καθοδήγηση σχετικά με τον χειρισμό της εφαρμογής:

curl -s http://localhost:5900/api/v1/agent/guide

Εκδόσεις

Όλες οι διαδρομές βρίσκονται κάτω από το /api/v1. Οι αλλαγές που δεν είναι συμβατές μεταφέρονται στο /api/v2 όταν προκύπτουν. Οι προσθετικές αλλαγές, όπως νέα endpoint και νέα προαιρετικά πεδία, παρέχονται στο v1 χωρίς αλλαγή έκδοσης.

Σχετικά

• Οδηγός χρήσης του HTTP API: εισαγωγή σε μορφή οδηγού με παραδείγματα.
• Πώς το CLI και η εφαρμογή μοιράζονται την κατάσταση: το μοντέλο συνέπειας πίσω από αυτά τα endpoint.
• Ρυθμίσεις → Γενικά: εδώ ενεργοποιείτε το API και επιλέγετε τη θύρα.