HTTP API

A HTTP API a Beam Bench integrációs felülete. Az asztali alkalmazás, a CLI és minden külső kliens ugyanazokkal az útvonalakkal kommunikál. Ha olyan felhasználási esethez van szüksége a Beam Benchre, amely nem CLI-környezetet igényel (webalkalmazás, integrációs szerver, mobilalkalmazás, saját eszköz), használja közvetlenül az API-t.

Az API az asztali alkalmazás része, és a folyamaton belül fut. Nincs külön telepítendő szolgáltatás.

Alapértelmezések és biztonság

A jelenlegi verzióban a helyi API-szerver beállításai:

• Helyi API: kikapcsolva.
• API-port: 5900.
• Hálózati eszközök engedélyezése: kikapcsolva. Az API engedélyezésekor a szerver a 127.0.0.1 címhez kötődik, és csak erről a számítógépről fogad kapcsolatokat.

Az API addig nem figyeli a kapcsolatokat, amíg külön nem engedélyezi. A hálózati hozzáférés külön engedélyezést igényel, mert az API nem használ hitelesítést, és olyan műveleteket is tartalmaz, amelyek mozgathatják a gépet és bekapcsolhatják a lézert.

Az API használatához módosítsa a beállításait a Beállítások elemre → Általános oldalon:

1. Nyissa meg az asztali alkalmazást.
2. Szerkesztés → Beállítások elemre → Általános.
3. Kapcsolja be a Helyi API beállítást.
4. Hagyja kikapcsolva a Hálózati eszközök engedélyezése beállítást, kivéve, ha egy másik megbízható eszköznek kell csatlakoznia.

A módosítások azonnal érvénybe lépnek, nincs szükség újraindításra.

Alap URL

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

A <host> értéke localhost (vagy 127.0.0.1), ha a Hálózati eszközök engedélyezése ki van kapcsolva. Bekapcsolt állapotban a szerver a gép LAN IP-címén érhető el a hálózat bármely eszközéről.

A port a Beállítások elemre → Általános oldalon állítható be; az alapértelmezett érték 5900.

Hitelesítés

Nincs. Az API nem használ tokent, kulcsot vagy bejelentkezést.

• A localhosthoz kötött módban az operációs rendszer szintű hozzáférési modellje jelenti a határt: a gépen futó bármely folyamat kommunikálhat az API-val.
• Engedélyezett hálózati kötés esetén ugyanazon a hálózaton bárki kommunikálhat az API-val. Ne használja a hálózati kötési módot nem megbízható Wi-Fi-hálózaton.

Kérés formátuma

Minden POST/PATCH/PUT törzs JSON:

Content-Type: application/json

A lekérdezési karakterláncok egyszerű key=value formátumúak. Az útvonalszegmensek a szokásos módon URL-kódolva vannak.

Válaszburkoló

A sikeres válaszok közvetlenül az erőforrás törzsét adják vissza, burkoló nélkül:

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

A hibák egységes burkolóban érkeznek:

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

Az error.code lehetséges értékei:

Megerősítést igénylő hibák

Néhány művelet mozgathatja a gépet vagy bekapcsolhatja a lézert. Ezekhez a végpontokhoz a kérés törzsében kifejezett megerősítési jelző szükséges. Ha ez hiányzik, az API 428 Precondition Required választ ad:

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

Küldje el újra a kérést úgy, hogy a megnevezett jelző értéke true legyen. Jelenleg ezek a jelzők használatosak: confirm_motion, confirm_laser_on, confirm_raw_gcode és confirm_air_assist.

Végpontcsoportok

Az erőforrásonkénti referencioldalak még készülnek; addig is tekintse meg az agent képességsémáját.

Az aktuális felület felfedezése

A telepített verzió által biztosított felület megtekintésének leggyorsabb módja:

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

Ez a teljes képességsémát adja vissza, beleértve minden végpontot, annak paramétereit és válaszformátumát. A séma a mérvadó leírás; ez az oldal útmutatóként szolgál hozzá.

Az állapot vizsgálatához:

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

Az alkalmazás vezérléséről szóló írásos bevezetőhöz:

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

Verziókezelés

Minden útvonal a /api/v1 alatt található. A visszamenőleg inkompatibilis módosítások, amikor szükségesek, a /api/v2 alatt jelennek meg. A bővítő módosítások (új végpontok, új opcionális mezők) verzióváltás nélkül, a v1 részeként jelennek meg.

Kapcsolódó oldalak

• A HTTP API használata: oktató jellegű bevezetés kidolgozott példákkal.
• Hogyan osztja meg az állapotot a CLI és az alkalmazás: az ezen végpontok mögött álló konzisztenciamodell.
• Beállítások elemre → Általános: itt engedélyezheti az API-t, és itt választhatja ki a portot.