HTTP API

A HTTP API a Beam Bench integrációs felülete. A legtöbb CLI-parancs és külső kliens ezeket az útvonalakat használja. Az asztali frontend Tauri IPC-n keresztül hívja a megosztott szolgáltatást, és normál használat esetén nincs szüksége a HTTP-szerverre. Ha olyan felhasználási esethez van szüksége a Beam Benchre, amely nem CLI-környezetben működik, például webalkalmazásban, integrációs szerveren, mobilalkalmazásban vagy saját eszközben, 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 buildben a helyi API-szerver beállításai a következők:

• Helyi API: ki.
• API-port: 5900.
• Hálózati eszközök engedélyezése: ki. 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 mindaddig nem figyeli a kapcsolatokat, amíg kifejezetten nem engedélyezi. A hálózati hozzáférés külön engedélyezést igényel, mert az API nem hitelesít, és olyan műveleteket is tartalmaz, amelyek megmozgathatjá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 részen:

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, amikor 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 részen állítható be; az alapértelmezett érték 5900.

Hitelesítés

Nincs. Az API-ban nincs token, kulcs vagy bejelentkezés.

• Helyi kötés esetén az operációs rendszer szintű hozzáférési modell jelenti a határt: a gépén futó bármely folyamat kommunikálhat az API-val.
• Hálózati kötés engedélyezésekor 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 lapos key=value formátumúak. Az útvonal szegmenseit a szokásos módon URL-kódolja a rendszer.

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ót adnak vissza:

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

Az error.code értéke a következők egyike:

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

A műveletek egy kis csoportja megmozgathatja 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 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. A jelenleg használt jelzők: confirm_motion, confirm_laser_on, confirm_raw_gcode és confirm_air_assist.

Egyidejű projektszerkesztések

A tervezési tranzakciók véglegesítéskor összehasonlítják a rögzített projektet. Egyidejű szerkesztés, projektváltás vagy bezárás stale_revision hibát adhat vissza. Frissítse az állapotot, és gondolja át újra a módosítást az újrapróbálás előtt. Ne játsszon vissza vakon egy régebbi projektpillanatképet az újabb munkára.

Végpontcsoportok

Az erőforrásonkénti referencialapok készítése folyamatban van; addig tekintse meg az ügynök képességsémáját.

Az aktuális felület felfedezése

A telepített verzió által elérhető 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áját. A séma a hiteles 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ének írásos áttekintéséhez:

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

Verziókezelés

Minden útvonal /api/v1 alatt található. Ha törő változások történnek, azok a /api/v2 alatt jelennek meg. A bővítő változások, például új végpontok vagy új opcionális mezők, verzióváltás nélkül kerülnek a v1 verzióba.

Kapcsolódó oldalak

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