REST API und MCP

Verwenden Sie REST und MCP, wenn ein Opfield-Ablauf wiederholbar, zuordenbar und unabhängig vom Browser eines einzelnen Operators sein muss. Ein Ablauf ist abgeschlossen, wenn die Ressource den beabsichtigten Zustand erreicht, nicht wenn die HTTP-Anfrage angenommen wird oder der Werkzeugaufruf zurückkehrt.

Die REST API stellt dokumentierte Ressourcenoperationen mit Sitzungs-, API-Token- oder OAuth-Authentifizierung bereit, je nach Bedarf. Remote-MCP bietet aufgabenorientierte Werkzeuge über dieselben Scopes, dieselbe Validierung, denselben Leistungsumfang und denselben Audit-Trail.

Automatisierung sollte:

eine eigene Identität mit minimalen Rechten verwenden;
202 oder die Erstellung eines Tasks als angenommene Arbeit behandeln und dann den dauerhaften Zustand abfragen;
nur idempotente Operationen wiederholen, bei Erstellungen, die einen solchen akzeptieren, einen Idempotency-Key senden oder den Wiederholungsvertrag der Operation verwenden;
401, 403, 409, 422 und Fehler wegen eines offline gegangenen Nodes unterschiedlich behandeln;
das Parsen von Oberflächentext vermeiden, wenn ein strukturiertes API-Feld existiert;
Ressourcen- und Request-IDs festhalten, ohne Secrets zu protokollieren.

Verwenden Sie das OpenAPI-Dokument, das die laufende Opfield-Instanz bereitstellt, für genaue Anfrage- und Antwortschemas. Die Schemaversion muss zur automatisierten Instanz passen; kopieren Sie keine Anfrageinhalte aus einem anderen Release. Produktanleitungen beschreiben die erforderliche Reihenfolge der Ressourcen und betriebliche Folgen, die Schemas allein nicht erfassen können.

Authentifizierung und Erkennung

Wählen Sie je nach Aufrufer eine Sitzung, ein API-Token oder einen OAuth-Client. Remote-MCP-Clients autorisieren sich über OAuth und erkennen aufgabenorientierte Werkzeuge, die nach denselben Scopes und demselben Produktzustand gefiltert sind. Dass ein Werkzeug vorhanden ist, beweist nicht, dass eine bestimmte Ressourcenänderung zugelassen wird.

Beginnen Sie die Automatisierung, indem Sie die Zielressource und den Zustand ihrer Fähigkeiten lesen. Lösen Sie stabile IDs auf, statt Namen aus der Oberfläche auszulesen. Halten Sie Basis-URL, Token und Umgebung getrennt, damit ein Entwicklungsskript nicht versehentlich die Produktion ansteuert.

Herausfinden, worauf der Aufrufer zugreifen kann

Auf Ordner, Nodes oder einzelne Ressourcen beschränkter Zugriff ist für Automatisierung und Agenten normal. Lesen Sie die Zugriffszusammenfassung des Aufrufers, bevor Sie Ressourcen erstellen, und immer dann, wenn eine Liste leer zurückkommt oder ein Erstellen auf oberster Ebene abgelehnt wird:

REST: GET /api/auth/me/access, mit einer Sitzung, einem API-Token oder einem OAuth-Token.
MCP und AI Workspace: das Werkzeug get_my_access, optional mit einem area wie docker_containers oder routes.
MCP-Ressource: opfield://access.

Die Zusammenfassung gruppiert den Zugriff nach Produktbereich. Für jeden Bereich gibt sie an, ob der Zugriff broad oder limited ist, listet die berechtigten Ordner (ID, Name und Pfad), Nodes, Konten und Ressourcen mit den jeweils erlaubten Aktionen auf und gibt an, wo der Aufrufer erstellen darf: create.atRoot, create.folders und create.nodes, mit einem Hinweis howTo. Das Objekt principal nennt den Typ der Zugangsdaten (session, api-token, oauth-token, mcp oder assistant). Nur eine Browsersitzung und der AI Workspace erhalten außerdem ID, Name, E-Mail-Adresse und Berechtigungsgruppe des Benutzers; API-Tokens, OAuth-Tokens und MCP-Clients erhalten nur principal: { credential, boundedByOwner: true }, weil ihr Zugriff nie über den aktuellen Zugriff des Eigentümers hinausgeht. Ist eine MCP-Verbindung eingeschränkt, fügt Opfield beim Verbindungsaufbau außerdem eine Kurzfassung der Zusammenfassung zu den Anweisungen des MCP-Servers hinzu.

Der Bereich apps listet nur App-Scopes auf. Eine App, die der Aufrufer nur über ihre Ressourcen sieht, wird dort nicht aufgeführt; list_apps und get_app liefern sie mit access: "members". Siehe Wer eine App sieht.

Arbeiten Sie innerhalb der aufgeführten Berechtigungen:

Listen-Endpunkte und -Werkzeuge liefern nur, worauf der Aufrufer zugreifen darf; eine leere Liste ist keine Ablehnung.
list_resource_folders zeigt jeden Ordner, auf dem der Aufrufer eine beliebige Berechtigung besitzt, einschließlich leerer, mit access.actions und access.canCreate.
Ein Erstellen ohne folderId zielt auf die oberste Ebene. Übergeben Sie folderId und, wo die Operation es akzeptiert, nodeId, wenn der Erstellungszugriff beschränkt ist.
Eine Ablehnung eines beschränkten Aufrufers – ein Erstellen auf oberster Ebene oder das Lesen einer Ressource außerhalb seiner Berechtigungen – nennt die Ordner, Nodes und Ressourcen, die der Aufrufer verwenden darf, und fordert auf, folderId zu übergeben, in REST-Antworten ebenso wie in Werkzeugfehlern von MCP und AI Workspace. Behandeln Sie eine Berechtigung nur dann als fehlend, wenn die Zusammenfassung nirgends eine Berechtigung für die Aktion zeigt.

Codex oder Claude Code über MCP verbinden

Opfield stellt seinen authentifizierten Remote-MCP-Server unter folgender Adresse bereit:

https://opfield.example.com/api/mcp

Ersetzen Sie opfield.example.com durch den kanonischen öffentlichen Hostnamen Ihrer Opfield-Installation. Verwenden Sie denselben HTTPS-Origin, den Operatoren zum Öffnen von Opfield verwenden. Hängen Sie kein weiteres /mcp an und richten Sie den Client nicht auf die Wurzel der REST API.

Nach der Verbindung kann der Client Opfield-Werkzeuge erkennen und nur die Operationen ausführen, die dem angemeldeten Benutzer erlaubt sind. MCP gewährt keinen Administratorzugriff und umgeht weder Ressourcen-Scopes noch den Leistungsumfang des Tarifs, Bestätigungen oder Audit-Protokollierung.

Opfield vorbereiten

Ein Administrator führt diese einmaligen Schritte aus:

Öffnen Sie Settings, wählen Sie Features und suchen Sie OAuth and MCP access.
Schalten Sie Enable MCP server ein.
Lassen Sie Extended MCP compatibility für normale Clients aktiviert. Deaktivieren Sie es nur, wenn ein Client den gesamten Werkzeugkatalog in seinen Kontext lädt und dessen Größe nicht bewältigen kann.
Lassen Sie OAuth extended callback compatibility für Codex und Claude Code deaktiviert. Deren lokale Loopback-Callbacks funktionieren mit der sichereren Standardrichtlinie.
Geben Sie dem verbindenden Benutzer Use MCP (mcp:use) plus die gewöhnlichen Scopes für die Ressourcen, die dieser Client lesen oder ändern darf.

Der Benutzer muss sich außerdem in einem Browser bei Opfield anmelden können. Funktioniert die Verbindung, fehlt aber ein Werkzeug oder eine Ressource, prüfen Sie Gruppenmitgliedschaften und Ressourcen-Scopes, statt die OAuth-Callback-Richtlinie zu erweitern.

Codex verbinden

Fügen Sie Opfield hinzu, schließen Sie die OAuth-Anmeldung ab und prüfen Sie die Verbindung:

codex mcp add opfield --url https://opfield.example.com/api/mcp
codex mcp login opfield
codex mcp list

Der Anmeldebefehl öffnet Opfield in Ihrem Browser. Melden Sie sich als der vorgesehene Opfield-Benutzer an, prüfen Sie den angeforderten Zugriff und stimmen Sie zu. Codex speichert die resultierenden OAuth-Zugangsdaten; Sie erstellen kein API-Token und fügen keines ein.

In der Codex-Desktop-App oder der IDE-Erweiterung können Sie stattdessen einen MCP-Server vom Typ Streamable HTTP mit derselben URL hinzufügen und Authenticate wählen. Desktop-App, CLI und IDE-Erweiterung teilen sich die MCP-Konfiguration von Codex.

Claude Code verbinden

Fügen Sie Opfield als entfernten HTTP-Server für Ihr Benutzerkonto hinzu:

claude mcp add --transport http opfield --scope user https://opfield.example.com/api/mcp
claude mcp login opfield
claude mcp get opfield

Sie können auch eine interaktive Claude-Code-Sitzung öffnen, /mcp eingeben, opfield wählen und die Authentifizierung im Browser abschließen. Verwenden Sie --scope project statt --scope user nur, wenn das Repository die Serverdefinition über .mcp.json teilen soll; jeder Entwickler meldet sich weiterhin mit seinem eigenen Opfield-Konto an.

So funktioniert der OAuth-Ablauf

Sie müssen für Codex oder Claude Code keinen OAuth-Client manuell registrieren:

Der Client kontaktiert /api/mcp und erhält die OAuth-Discovery-Informationen von Opfield.
Der Client registriert sich selbst und startet Authorization Code mit PKCE.
Opfield öffnet einen Anmelde- und Zustimmungsbildschirm im Browser.
Der Benutzer stimmt einem Zugriff zu, der durch seine aktuellen Opfield-Scopes begrenzt ist, und kann ihn auf Ordner, App-Umgebungen oder Ressourcen beschränken, zum Beispiel über eine Abschnittsüberschrift unter Review N scopes, die Everywhere zeigt; siehe Tokens und OAuth-Freigaben einschränken.
Opfield stellt ein OAuth-Access-Token für die MCP-Ressource aus.
Der Client speichert diese Zugangsdaten und sendet sie bei späteren Anfragen an /api/mcp.

Opfield akzeptiert nur OAuth-Access-Tokens, die für seine MCP-Ressource ausgestellt wurden. Browser-Cookies, gewöhnliche gw_-API-Tokens, gwl_-Logging-Tokens und gwi_-Tokens von Opfield Inference werden abgelehnt. Der Server prüft die aktuellen Scopes und mcp:use des Benutzers erneut, sodass das Entfernen des Zugriffs künftige MCP-Operationen stoppt, selbst wenn der Client die Werkzeuge zuvor erkannt hat.

Die Verbindung prüfen

Beginnen Sie mit einer reinen Leseanfrage:

List the Opfield nodes I can access and summarize their current status. Do not change anything.

Bestätigen Sie, dass der Client opfield als verbunden meldet, nur erwartete Ressourcen sichtbar sind, ein Lesevorgang gelingt, eine Aktion außerhalb der Scopes des Benutzers abgewiesen wird und Opfield den Aufruf im Audit-Log dem erwarteten Benutzer zuordnet.

Fehlerbehebung bei der MCP-Verbindung

Der Endpunkt liefert 404: Schalten Sie Settings → Features → OAuth and MCP access → Enable MCP server ein und prüfen Sie, dass die URL auf /api/mcp endet.
Der Client verlangt eine Authentifizierung: Führen Sie codex mcp login opfield oder claude mcp login opfield aus. Verwenden Sie in einem interaktiven Client /mcp.
Die Anmeldung gelingt, aber Opfield liefert 403: Das Konto benötigt mcp:use und mindestens einen wirksamen Ressourcen-Scope. Eine auf einen Ordner beschränkte Berechtigung sieht nur die Ressourcen dieses Ordners; das Erstellen an anderer Stelle wird abgelehnt. Bitten Sie den Agenten, get_my_access aufzurufen und in einem der aufgeführten Ordner zu erstellen; siehe Herausfinden, worauf der Aufrufer zugreifen kann.
Ein Client sendet einen Scope-Namen, der nicht mehr existiert: Opfield akzeptiert weiterhin die außer Dienst gestellten Scope-Namen und vergibt deren Ersatz.
Der Client erschöpft seinen Kontext mit zu vielen Werkzeugen: Deaktivieren Sie Extended MCP compatibility, um den kompakten Anfangskatalog und die Kategorieerkennung zu verwenden.
Opfield lehnt den OAuth-Callback ab: Aktualisieren Sie zuerst den Client und versuchen Sie es erneut. Normale Loopback-Callbacks von Codex und Claude Code erfordern OAuth extended callback compatibility nicht.
Eine gespeicherte Verbindung funktioniert nicht mehr: Prüfen Sie, ob sich die OAuth-Autorisierung, mcp:use, die Ressourcen-Scopes oder die kanonische Opfield-URL geändert haben. Authentifizieren Sie sich erneut, statt ein normales API-Token zu verwenden.

Dauerhafte Operationen

Viele Infrastrukturänderungen liefern einen angenommenen Task oder eine angenommene Operation statt eines abgeschlossenen Ergebnisses:

Senden Sie die validierte Anfrage.
Speichern Sie die zurückgegebenen Ressourcen-, Task-, Operations- und Request-IDs.
Fragen Sie den dauerhaften Operationszustand ab oder abonnieren Sie ihn.
Prüfen Sie strukturierte Fehlerdetails.
Prüfen Sie den resultierenden Ressourcenzustand unabhängig.
Wiederholen Sie nur gemäß dem Idempotenzvertrag der Operation.

Übersetzen Sie eine Zeitüberschreitung beim Transport nicht direkt in eine zweite Erstellungs- oder Löschanfrage. Die erste Anfrage hat den zuständigen Daemon möglicherweise erreicht und wartet auf den Abgleich. Eine Ausnahme ist ein Erstellen an einen Endpunkt, der einen Idempotency-Key akzeptiert: Wiederholen Sie es mit demselben Schlüssel.

Sichere Wiederholungen mit Idempotency-Key

Ausgewählte Erstellungs-Endpunkte akzeptieren einen optionalen Header Idempotency-Key mit 1–255 druckbaren ASCII-Zeichen, zum Beispiel einer UUID. Das OpenAPI-Dokument führt den Header genau bei diesen Operationen auf:

Docker: Erstellen und Duplizieren von Containern sowie Erstellen von Deployments, Compose-Projekten, Ressourcen aus einer Git-Quelle, Volumes, Netzwerken und Registries;
Ingress und Zertifikate: Routen (POST /api/proxy-hosts), Routenordner, Domains, ACME-Zertifikate sowie Root- und Zwischenzertifizierungsstellen;
Datenbanken und Speicher: Datenbankverbindungen, verwaltete Datenbanken, Speicherverbindungen und verwalteter Speicher;
Sonstiges: Pages-Projekte, Alarmregeln und SIEM-Ziele.

Erzeugen Sie für jede logische Operation einen neuen Schlüssel und senden Sie denselben Schlüssel nur dann erneut, wenn Sie diese Anfrage nach einer Zeitüberschreitung oder einer abgebrochenen Verbindung wiederholen:

curl -X POST https://opfield.example.com/api/domains \
  -H "Authorization: Bearer $OPFIELD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6c1e-8a55-4c43-9d4e-2f1f8c3d9b10" \
  -d '{"domain":"app.example.com"}'

Ein Schlüssel gehört zu dem API-Token, OAuth-Token oder der Browsersitzung, die ihn gesendet hat, zusammen mit den aktuellen wirksamen Scopes dieses Aufrufers, der Methode und dem genauen Pfad. Nach einer Scope-Änderung beginnt derselbe Schlüssel neu, sodass eine Wiedergabe einen widerrufenen Zugriff nie überdauert.
Eine Wiederholung mit demselben Schlüssel und derselben Anfrage – demselben Query-String und JSON-Inhalt, in beliebiger Schlüsselreihenfolge – liefert die gespeicherte Antwort mit dem Header Idempotency-Replayed: true und erstellt nichts Neues. Opfield bewahrt das Ergebnis 24 Stunden lang auf, verschlüsselt mit seinem Master-Schlüssel, und schreibt jede Wiedergabe als api.idempotency.replay ins Audit-Log.
Derselbe Schlüssel mit einer anderen Anfrage liefert 422 IDEMPOTENCY_KEY_REUSED. Derselbe Schlüssel, während die erste Anfrage noch läuft, liefert 409 IDEMPOTENCY_KEY_IN_PROGRESS mit Retry-After. Ein ungültiger Schlüssel liefert 400 IDEMPOTENCY_KEY_INVALID.
Opfield speichert nie eine Antwort, die so aussieht, als enthielte sie geheimes Material wie ein Token, ein Passwort, einen privaten Schlüssel oder Zugangsdaten, und auch keine, die größer als 1 MiB ist. Es erfasst nur, dass die Anfrage abgeschlossen wurde, und eine Wiederholung liefert 409 IDEMPOTENCY_RESPONSE_WITHHELD mit dem ursprünglichen Status und, falls bekannt, Location: Suchen Sie die Ressource, statt es erneut zu versuchen.
Erfasst werden nur 2xx-Antworten sowie 400-, 404-, 409- und 422-Antworten mit JSON- oder leerem Inhalt. 401, 403, 5xx, gestreamte und Download-Antworten werden nicht erfasst, sodass eine Wiederholung danach die Anfrage erneut ausführt.
Nicht abgedeckt: jeder Endpunkt außerhalb der obigen Liste, der normal läuft und den Header ignoriert. Das schließt bewusst Endpunkte ein, die ein Secret einmal zurückgeben oder sensible Eingaben zurückspiegeln: API-, Inference-, Logging-Aufnahme- und Pages-Deploy-Tokens, Node-Registrierung, Zugriffsschlüssel und Zugangsdaten, Bindings, Access Lists und Benachrichtigungs-Webhooks. Anfrageinhalte über 1 MiB und Uploads, die kein JSON sind, laufen ebenfalls ohne Idempotenz, ebenso alles, solange Redis, das die Schlüssel speichert, nicht verfügbar ist.

Erstellungswerkzeuge von MCP akzeptieren ein optionales Argument idempotencyKey mit denselben Regeln. Der Schlüssel ist an das MCP-Token und seine Scopes, die aktuellen Scopes des Eigentümers und das Werkzeug gebunden. Es werden nur erfolgreiche Ergebnisse gespeichert, sodass ein Werkzeugfehler mit demselben Schlüssel wiederholt werden kann; ein wiedergegebenes Ergebnis trägt _meta.idempotencyReplayed: true und wird auditiert. Ein Ergebnis, das so aussieht, als enthielte es ein Secret, wird nicht gespeichert, und eine Wiederholung liefert IDEMPOTENCY_RESULT_WITHHELD. Das Argument wird angeboten bei:

Docker: create_docker_container, duplicate_docker_container und der Erstellungsoperation von manage_docker_deployment, manage_docker_compose, manage_docker_source, manage_docker_volume, manage_docker_network, manage_container_link und manage_docker_registry;
Ingress: create_route, create_route_folder und create_domain;
Zertifikate: request_acme_cert, der Upload-Operation von manage_ssl_certificate, create_root_ca und create_intermediate_ca;
Datenbanken und Speicher: der Erstellungsoperation von manage_database_connection, manage_managed_database, manage_storage_connection und manage_managed_storage;
Sonstiges: der Operation project_create von manage_pages, create_alert_rule und create_siem_destination.

Werkzeuge, die ein Secret zurückgeben oder sensible Eingaben zurückspiegeln – create_node, create_access_list, create_webhook, das Erstellen von Bindings, das Erstellen von Tokens und Zugriffsschlüsseln sowie issue_certificate –, akzeptieren das Argument nicht. Die Lebenszyklusoperationen von manage_docker_compose behalten ihr eigenes Argument idempotencyKey mit seiner bisherigen Bedeutung.

Große Nutzdaten über einmalige Links übertragen

Werkzeugaufrufe sind ein schlechter Kanal für Dateien. Für große Nutzdaten liefern MCP-Werkzeuge einen einmaligen Link mit einem fertigen curl-Befehl, den eine Shell auf der Seite des Agenten ausführt; die Bytes fließen über Opfield, nie über das Modell:

Pages: Die Operation link von upload_pages_artifact akzeptiert ein Archiv, einen gepackten Build-Ordner oder eine einzelne HTML-Datei. Der Upload darf so groß sein wie das File upload limit (standardmäßig 100 MB, höchstens 500 MB); siehe Pages-Übersicht. Ohne Shell akzeptieren die Operationen begin, chunk und finalize höchstens 1 MiB pro Block.
Container-Archive: Die Operationen link von download_docker_archive und upload_docker_container_archive exportieren und importieren .gwca-Archive.
Speicherobjekte: download_storage_object liefert einen 15 Minuten gültigen Link, der ein Objekt beliebiger Größe herunterlädt, und upload_storage_object lädt in Blöcken hoch, die Opfield prüft.

Ein Link funktioniert einmal, gehört zu dem Token, das ihn angefordert hat, und wird bei der Verwendung erneut gegen die aktuellen Berechtigungen des Eigentümers geprüft. Behandeln Sie ihn wie eine kurzlebige Zugangsberechtigung.

Fehlerbehandlung

400 oder 422: Anfrageform oder Validierungseingabe korrigieren;
401: Authentifizierung erneuern oder ersetzen;
403: fehlenden Scope von fehlendem Leistungsumfang des Tarifs unterscheiden;
404: neben der Existenz auch die Sichtbarkeit der Ressource prüfen;
409: Lebenszykluskonflikt, Kontingent oder aktuellen Zustand prüfen;
429: begrenztes Backoff anwenden und Hinweise des Servers beachten;
5xx oder Node offline: Request-IDs bewahren und den dauerhaften Task-Zustand prüfen, bevor Sie es erneut versuchen.

Werkzeugfehler von MCP und AI Workspace beginnen mit demselben Code wie die REST-Antwort, zum Beispiel NOT_FOUND, STORAGE_NOT_FOUND oder NGINX_CONFIG_FAILED, gefolgt von Meldung und Details; ein Schemafehler lautet VALIDATION_ERROR mit den fehlerhaften Feldern. Eine Anfrage an einen unbekannten /api-Pfad liefert ein JSON-404 NOT_FOUND statt der Konsolenseite.

Betriebsregeln für MCP

MCP-Werkzeuge decken jede Ressourcen- und Verwaltungsoperation ab, die die Scopes der OAuth-Freigabe erlauben, einschließlich Node-Konfiguration und -Dateien, Docker-Migrationen, des Logging-Backends, Opfield-Einstellungen, Benutzern und Gruppen, Operationen von Relay-Pool und Updates, Inference-Administration, Hosting sowie der Connectoren für GitLab, GitHub, generisches Git, Cloudflare und External SSH. MCP stellt keine Interna von AI Workspace wie Unterhaltungen, Pläne und Sandboxes bereit und keine Werkzeuge, die API-Tokens oder OAuth-Autorisierungen ausstellen. Siehe Was Tokens können und was nicht.

Das Erstellen von Routen und Domains erfordert keine Node-Berechtigungen: create_route und create_domain können den Node weglassen, wenn eine registrierte Domain oder der einzige geeignete Ingress Node ihn bestimmt (bei Routen muss dieser Node online sein), und list_route_ingress_nodes listet die Nodes auf, auf denen der Aufrufer Routen erstellen darf. Siehe Den Ingress Node wählen.

Der MCP-Server meldet das Opfield-Release als seine Version. manage_opfield_diagnostics prüft Opfield selbst; siehe Opfield-Diagnose. Wenn ein MCP-Werkzeug die Umgebung eines Deployments setzt, wird sie mit der gespeicherten Umgebung zusammengeführt, anders als bei der REST-Deploy-Route; siehe Eine neue Version veröffentlichen.

Verwenden Sie MCP für zielorientierte Operationen, bei denen das Werkzeugschema Sicherheit und Ressourcenkontext hinzufügt. Lesen Sie Werkzeugbeschreibungen und zurückgegebene Warnungen, übergeben Sie genaue Ressourcenkennungen und behandeln Sie externe Inhalte als nicht vertrauenswürdige Eingaben. MCP-Aufrufe werden auditiert und dürfen nicht verwendet werden, um Bestätigungs-, Berechtigungs-, Leistungsumfangs- oder Lebenszyklusprüfungen zu umgehen.

Prüfung

Testen Sie für jeden Automatisierungspfad eine erlaubte Aktion, eine abgewiesene Aktion, einen Validierungsfehler, einen asynchronen Erfolg und eine unterbrochene Operation. Bestätigen Sie die Audit-Zuordnung und stellen Sie sicher, dass Logs Zugangsdaten und sensible Anfragefelder schwärzen.

Zuverlässige Clients entwerfen

Modellieren Sie Automatisierung als Abgleich statt als Abfolge blinder Klicks. Lesen Sie die aktuelle Ressource, vergleichen Sie sie mit dem Sollzustand, senden Sie die kleinste erforderliche Änderung und prüfen Sie den resultierenden, vom Eigentümer gemeldeten Zustand. Verwenden Sie im gespeicherten Zustand stabile IDs und für Menschen lesbare Namen nur zur Anzeige. Stellt eine API eine Operations- oder Task-ID bereit, speichern Sie sie zusammen mit dem Automatisierungslauf, damit ein Operator eine Zeitüberschreitung mit dem Verlauf in Opfield in Beziehung setzen kann.

Legen Sie begrenzte Fristen für Verbindung, Anfrage und Gesamtoperation getrennt fest. Eine kurze HTTP-Frist kann neben einem lang laufenden dauerhaften Task bestehen. Wiederholen Sie Lesevorgänge und ausdrücklich idempotente Updates mit begrenztem exponentiellem Backoff und Jitter. Wiederholen Sie Erstellungen, Löschungen, Migrationen, Wiederherstellungen oder die Rotation von Zugangsdaten nach einer mehrdeutigen Zeitüberschreitung nicht automatisch, es sei denn, die Anfrage enthielt einen Idempotency-Key an einen Endpunkt, der einen akzeptiert, oder die bestehende Operation wurde abgeglichen.

Versionieren Sie den Client gegen das OpenAPI-Dokument und die Opfield-Releases, die er tatsächlich getestet hat. Lehnen Sie unbekannte destruktive Felder und Zustände ab, statt sie stillschweigend zu ignorieren. Ändert ein Release einen Lebenszyklusvertrag, aktualisieren Sie den Client und seine Abnahmetests, bevor Sie ihn auf alle Installationen ausrollen.

Sicherer Rollout und Rollback

Führen Sie neue Automatisierung gegen einen Wegwerf-Ordner oder eine Wegwerf-Ressourcenmenge mit produktionsähnlichen Scopes aus. Erfassen Sie die beabsichtigte Anfrage, den resultierenden Task, den Audit-Eintrag und die unabhängige Zustandsprüfung. Rollen Sie zuerst auf eine Installation oder Fehlerdomäne aus und beobachten Sie Fehler und Abgleichsverzögerung, bevor Sie erweitern.

Ein Rollback bedeutet normalerweise, den Aufrufer zu deaktivieren, neue Übermittlungen zu stoppen und auf bereits geänderte Ressourcen ein unterstütztes Produkt-Rollback anzuwenden. Es bedeutet nicht, Tasks zu löschen oder den Sollzustand in PostgreSQL zu bearbeiten. Bewahren Sie Request-IDs und Metadaten fehlgeschlagener Nutzdaten ohne Secrets, damit der Produktverantwortliche einen Client-Fehler von einem Fehler von Opfield oder eines Daemons unterscheiden kann.