HTTP API

Το HTTP API είναι η διεπαφή ενσωμάτωσης του Beam Bench. Η εφαρμογή υπολογιστή, το CLI και κάθε εξωτερικός πελάτης επικοινωνούν με τις ίδιες διαδρομές. Αν έχετε μια περίπτωση χρήσης που χρειάζεται το 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 του μηχανήματος στο τοπικό δίκτυο από οποιαδήποτε συσκευή του δικτύου.

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

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

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

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

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

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

Content-Type: application/json

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

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

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

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

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

{
  "error": {
    "code": "InvalidInput",
    "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.

Ομάδες endpoint

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

Ανακάλυψη της ενεργής διεπαφής

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

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 και επιλέγετε τη θύρα.