Die Codecs-API stellt die Codec-Bibliothek und Ihre eigenen Codecs Personen, Skripten und lizenzierten Routern zur Verfügung. Nutzen Sie sie, um Codecs in der Versionsverwaltung zu halten, sie aus einer Pipeline zu veröffentlichen oder Payloads aus Ihren eigenen Werkzeugen zu testen.
Die Pfade unten folgen der üblichen Form https://<your host>/tenant/<tenantId>/api/…. Senden Sie einen API-Schlüssel als Authorization: Bearer <API key>. Siehe REST-API-Grundlagen.
Routen
| Methode und Pfad | Berechtigung | Antwort |
|---|---|---|
GET /api/iot/lorawan/codecs | Optional (siehe unten) | Der Codec-Index: { version, scope, codecs: [...], sig: null } |
GET /api/iot/lorawan/codecs/<codecId> | Optional | Ein Codec: { id, rev, sha256, scope, document, outputSet } |
GET /api/iot/lorawan/codecs/bundle | Optional | Jeder Codec mit seinem Dokument, komprimiert: { version, codecs: [{ id, rev, sha256, scope, document }] } |
GET /api/iot/lorawan/codec-library | Codecs anzeigen | Die Liste, die das Codec-Fenster anzeigt (seitenweise, sortierbar, aus beiden Quellen) |
POST /api/iot/lorawan/codecs | Codecs verwalten | Einen neuen Codec veröffentlichen (201) |
PATCH /api/iot/lorawan/codecs/<codecId> | Codecs verwalten | Eine neue Revision Ihres Codecs veröffentlichen |
DELETE /api/iot/lorawan/codecs/<codecId> | Codecs verwalten | Ihren Codec löschen |
POST /api/iot/lorawan/codecs/<codecId>/test | Codecs anzeigen | Einen Frame mit einem gespeicherten Codec dekodieren |
POST /api/iot/lorawan/codecs/test | Codecs anzeigen | Ein Codec-Dokument prüfen und optional einen Frame dekodieren; nichts wird gespeichert |
GET /api/iot/lorawan/codecs/<codecId>/revisions | Codecs anzeigen | Die Revisionen des Codecs |
„View codecs“ ist die Berechtigung, LoRaWAN-Codecs anzusehen und den Testbereich zu nutzen (standardmäßig für Benutzer). „Manage codecs“ ist die Berechtigung, Ihre eigenen Codecs hinzuzufügen, zu ändern und zu löschen (standardmäßig für Administratoren).
Wer was auf den drei Leserouten sieht
| Gesendete Anmeldedaten | Antwort |
|---|---|
| Keine | Nur die öffentliche Bibliothek. Fünf Minuten zwischengespeichert (Cache-Control: public, max-age=300). |
| Eine gültige Sitzung oder ein API-Schlüssel mit der Berechtigung zum Anzeigen | Die Bibliothek plus die Codecs Ihrer Organisation. Nicht zwischengespeichert (private, no-store). |
| Die signierte Anfrage eines lizenzierten Routers | Die Bibliothek plus die Codecs der Organisation des Routers. |
| Eine vorhandene, aber falsche Anmeldung (fehlerhafter Header, abgelaufene Sitzung, unbekannter Schlüssel) | 401 mit invalid_credentials, signature_expired oder certificate_revoked. Niemals die öffentliche Liste. |
| Eine gültige Anmeldung ohne die Berechtigung | 403 |
Filter und Caching
Der Index akzeptiert q (Suche), vendor, model, oui, fport und scope. Jede Antwort enthält einen ETag, der der Indexversion entspricht; senden Sie ihn in If-None-Match zurück, um 304 Not Modified zu erhalten, wenn sich nichts geändert hat.
GET …/codecs/<codecId>?sha256=<fingerprint> fordert genau eine Revision an. Ein zurückgezogener Codec antwortet mit 410 (codec_withdrawn).
Einen Codec veröffentlichen
POST /tenant/<tenantId>/api/iot/lorawan/codecs
Content-Type: application/json
{ "document": { "id": "t.room-sensor", "title": "…", "vendor": "…", "kind": "layout", "frames": [ … ], "tests": [ … ] } }Oder einen Bibliothekscodec kopieren:
{ "copyOf": "<library codec id>", "id": "t.my-copy" }Die Antwort ist 201 { codec, indexVersion }. Bibliothekscodecs können über diese Routen nicht geändert oder gelöscht werden: 403 codec_read_only.
Einen Frame testen
POST /tenant/<tenantId>/api/iot/lorawan/codecs/t.room-sensor/test
Content-Type: application/json
{ "fport": 2, "hex": "0BC4010A32" }fport liegt zwischen 1 und 255, hex umfasst höchstens 255 Bytes. Ein ungültiger Frame antwortet mit Geben Sie den FPort (1-255) und die Payload als hexadezimale Ziffern ein (höchstens 255 Bytes).
Ratenbegrenzungen
| Aufrufer | Grenze |
|---|---|
| Keine Anmeldung: Index und einzelner Codec | 60 Anfragen pro Minute und Adresse |
| Keine Anmeldung: Bundle | 6 pro Stunde und Adresse |
| Angemeldete Benutzer und API-Schlüssel | 240 pro Minute; Bundle 30 pro Stunde |
| Lizenzierte Router | 120 pro Minute und Gerätezertifikat |
Bei Überschreitung einer Grenze antwortet die API mit 429 (Zu viele Anfragen. Versuchen Sie es später erneut.).
Fehlercodes
| Status | details.reason | Bedeutung |
|---|---|---|
| 404 | — | Codec nicht gefunden. |
| 409 | codec_exists | Ein Codec mit dieser ID existiert bereits. Wählen Sie eine andere ID. |
| 410 | codec_withdrawn | Diese Codec-Revision wurde zurückgezogen. |
| 403 | codec_read_only | Bibliothekscodecs werden hier nicht bearbeitet: Speichern Sie eine Kopie und ändern Sie die Kopie. |
| 422 | codec_format_not_supported | Ein JavaScript-Decoder wurde gesendet. |
| 422 | codec_tests_failed | Testvektoren sind fehlgeschlagen; die fehlgeschlagenen Vektoren werden aufgelistet. |
| 422 | codec_incompatible | Die neue Revision entfernt Schlüssel oder ändert Einheiten. |
| 422 | codec_model_claimed | Ein anderer Ihrer Codecs deckt dieses Modell ab. |
| 422 | codec_choice_unknown | (Wenn ein Gerät oder Profil einen Codec auswählt) Der Codec existiert nicht oder wurde zurückgezogen. |
| 401 | invalid_credentials | Die mit dieser Anfrage gesendeten Anmeldedaten sind nicht gültig. |
Die vollständige LoRaWAN-API (Gateways, Geräte, Schlüssel, Kopplung, Frames) finden Sie unter LoRaWAN-API.