Zum Hauptinhalt springen

Pipeline-Methoden-Handler

Eine Methode mit execution.handler: pipeline wird von einer Pipeline statt von C#-Code umgesetzt. Ein Mandantenadministrator oder Lösungsbauer kann damit eine fachliche Operation zu einem Datenmodell hinzufügen, ohne einen Dienst zu schreiben: Das Modell deklariert die Methode, eine Pipeline setzt sie um, und Aufrufer nutzen sie wie jede andere Methode. Diese Seite beschreibt den Vertrag zwischen der Plattform und der Pipeline. Die allgemeinen Regeln für Handler (Konsistenz, Fehler, Timeouts) stehen in Methoden-Handler implementieren und im Konsistenzmodell für Methoden.

Wo es läuft

Pipeline-Methoden behandelt der Communication Controller. Er startet Pipelines bereits auf Kommando (die Aktion Execute der Benutzeroberfläche und die API ExecutePipeline) und startet die Pipeline für einen Methodenaufruf auf dieselbe Weise, mit der Identität des Aufrufers, und wartet auf das Ergebnis. Am Adapter ist keine Änderung nötig.

Methode deklarieren​

types:
- typeId: Device
methods:
- methodId: UpdateFirmware-1
parameters:
- name: version
valueType: String
result:
valueType: Int
errors:
- code: FIRMWARE_LOCKED
execution:
timeoutSeconds: 120 # Pflicht für eine Pipeline-Methode
handler: pipeline

Die qualifizierte Methoden-ID lautet Acme.Assets/Device.UpdateFirmware-1 (Modell, Typ, Methode mit Version). Eine Pipeline-Methode muss timeoutSeconds deklarieren und darf weder Parameter noch ein Ergebnis haben, die als sensitive markiert sind: Der Compiler lehnt die Kombination mit Meldung 132 (Parameter) oder 134 (Ergebnis) ab (siehe Grenzen).

Pipeline zuordnen​

Es gibt kein Zuordnungselement. Die Pipeline, die eine Methode umsetzt, ist die deployte Pipeline im Mandanten des Aufrufs, deren Well-Known-Name der qualifizierten Methoden-ID entspricht:

entities:
- rtId: 'a1b2c3d4e5f60718293a4b5c'
ckTypeId: System.Communication/Pipeline
rtWellKnownName: Acme.Assets/Device.UpdateFirmware-1
associations:
- roleId: System/ParentChild
targetRtId: '...' # ein DataFlow
targetCkTypeId: System.Communication/DataFlow
- roleId: System.Communication/Executes
targetRtId: '...' # der Adapter, der sie ausführt
targetCkTypeId: System.Communication/Adapter

Deployen Sie sie wie jede Pipeline (DeployPipeline). Eine geänderte Pipeline wirkt nach erneutem Deploy. Der Controller kündigt die Methode an, sobald eine deployte Pipeline dieses Namens existiert, und zieht sie zurück, wenn die Pipeline undeployt oder gelöscht wird; ohne Pipeline wird der Aufruf mit METHOD_HANDLER_NOT_AVAILABLE (reason pipeline-not-deployed) beantwortet. Ist eine Methode handler: pipeline, aber beim Start des Controllers existiert keine Pipeline, protokolliert der Controller einen Fehler mit Methode und Mandant und läuft weiter; mit PipelineMethods:FailStartupOnInvalidMethod=true schlägt stattdessen der Start fehl.

Was die Pipeline erhält​

Die Pipeline beginnt mit FromExecutePipelineCommand@1. Die Datenwurzel enthält:

{
"parameters": { "version": "2.4.1" },
"target": { "ckTypeId": "Acme.Assets/Device", "rtId": "65f0c0ffee0000000000dead" },
"method": { "id": "Acme.Assets/Device.UpdateFirmware-1", "invocationId": "...", "correlationId": "..." }
}
PfadInhalt
$.parameters.<name>Die Methodenparameter in camelCase, wie der Aufrufer sie gesendet hat.
$.target.ckTypeId, $.target.rtIdDie Entität, auf der die Methode aufgerufen wird. rtId ist bei einer statischen Methode null.
$.method.*Methoden-ID, Aufruf-ID und Korrelations-ID; für Logmeldungen.

Der Aufrufer ist nicht Teil der Daten. Die Pipeline läuft als der Benutzer, der die Methode aufgerufen hat, genau wie bei einer manuellen Ausführung: Knoten, die den verifizierten Aufrufer lesen, sehen diesen Benutzer, und Knoten, die für den Aufrufer gegen einen anderen Dienst handeln, nutzen das weitergereichte Token. Setzen Sie callerBinding: BindingRequired am Trigger, damit die Pipeline abgewiesen wird, wenn kein Aufrufer mitgegeben wurde, statt als Service-Konto zu laufen.

Vertrauen in den Aufrufer

Die Methoden-Queue wird nicht je Nachricht authentifiziert, daher beweisen die caller-Daten eines Requests nichts: Wer in die Queue schreiben kann, könnte dort einen Administrator eintragen. Der Controller validiert deshalb das weitergereichte Access-Token, bevor er die Methode prüft oder eine Pipeline startet, mit demselben Vertrauen wie seine HTTP-API (Aussteller, Signatur, Ablauf, Mandant, Scope octo_api; siehe Validierung des Aufrufer-Tokens). Der Aufrufer der Pipeline wird ausschließlich aus dem validierten Token gebildet, mit Vertrauensstufe stark; die caller-Daten des Requests werden nie verwendet. Ein Benutzer-Token führt die Pipeline als Subjekt des Tokens aus; ein Service-Token (Client Credentials, kein sub) führt sie mit der Client-Id als Subjekt aus.

Ein Aufruf ohne gültiges Token wird mit METHOD_FORBIDDEN und einem reason (token-missing, token-expired, token-invalid, tenant-not-allowed) beantwortet, und es wird keine Pipeline gestartet. Kann der Controller die Signaturschlüssel des Identity-Dienstes nicht laden, lautet die Antwort METHOD_HANDLER_FAILED: Der Aufrufer hat nichts falsch gemacht, und ein Token wird nie ohne verifizierte Signatur akzeptiert. Nach token-expired mit einem frischen Token erneut aufrufen.

Was die Pipeline zurückgibt​

Die Pipeline endet mit SetPipelineExecutionResult@1. Der Wert am path wird als OutputData der Ausführung gespeichert und wird zur Antwort:

OutputDataAntwort an den Aufrufer
{"value": 1}, der Wert hat den Typ des result der MethodeErfolg. Der Aufrufer erhält den reinen Wert 1 als Ergebnis, genau wie von einem Service-Handler (ein String-Ergebnis ist "abc", ein Record {"name": "x"}); der Wrapper {"value": ...} ist nur die Form der Pipeline-Ausgabe. Weitere Member entfallen.
leer, bei einer Methode ohne resultErfolg ohne Ergebnis.
{"error": {"code": "FIRMWARE_LOCKED", "parameters": {"reason": "maintenance-window"}}}Der deklarierte Fehler mit seinen Parametern. Der Code muss in den errors der Methode deklariert sein oder METHOD_VALIDATION_FAILED, METHOD_TARGET_NOT_FOUND oder METHOD_FORBIDDEN sein. Parameterwerte sind Strings, Zahlen oder Booleans und dürfen keine Methodenparameterwerte enthalten.
alles andere: kein JSON, kein value, falscher Typ, nicht deklarierter CodeMETHOD_HANDLER_FAILED mit correlationId, field und reason invalid-result. Nie ein fehlerhafter Erfolg.
die Pipeline ist an einem Schreibvorgang gescheitert, den die Datenbank nicht bestätigt hat (zum Beispiel ein Write-Concern-Timeout oder ein Commit, dessen Ergebnis der Treiber als unbekannt meldet)METHOD_OUTCOME_UNKNOWN mit correlationId: Der Schreibvorgang kann auf dem Primary liegen, "es ist nichts passiert" wäre falsch. Der Adapter klassifiziert die Exception und meldet eine strukturierte Fehlerart (PipelineExecution.FailureKind = OutcomeUnknown); der Controller liest dafür nie die Fehlermeldung. Ein Schreibvorgang, den die Datenbank abgelehnt hat (zum Beispiel ein doppelter Schlüssel), bleibt METHOD_HANDLER_FAILED. Lesen Sie den Zustand, bevor Sie erneut aufrufen (R5).
die Pipeline ist aus einem anderen Grund fehlgeschlagen, wurde unterbrochen oder abgebrochenMETHOD_HANDLER_FAILED mit correlationId. Die Fehlermeldung der Ausführung bleibt im Log des Controllers. Eine unterbrochene Ausführung und eine Ausführung, die ein Adapter nach einer Offline-Phase nachmeldet, tragen keine Fehlerart und werden auch bei einem laufenden Schreibvorgang mit METHOD_HANDLER_FAILED beantwortet.
die Pipeline ist zum Ablauf der Frist nicht fertigMETHOD_TIMEOUT. Die Pipeline wird nicht abgebrochen und kann noch fertig werden; siehe Grenzen.
die Pipeline kann nicht gestartet werden, z. B. der Adapter ist offlineMETHOD_HANDLER_NOT_AVAILABLE mit reason pipeline-start-failed.

Die Fehlerart einer Ausführung sehen​

Die Fehlerart ist nicht nur die Antwort an einen Methodenaufrufer. Ein Operator liest sie an der Ausführung selbst: Die REST-Pipeline-Ausführung (GET /{tenantId}/v1/PipelineDebug/{pipelineRtId} für die Historie und .../latest für die neueste Ausführung) trägt failureKind, ebenso die octo-cli-Befehle GetPipelineExecutions und GetLatestPipelineExecution.

{ "Status": 2, "ErrorMessage": "...", "FailureKind": "OutcomeUnknown" }
failureKindBedeutung für den Operator
OutcomeUnknownDie Pipeline ist an einem Schreibvorgang gescheitert, den die Datenbank weder bestätigt noch abgelehnt hat. Der Schreibvorgang kann wirksam geworden sein: Lesen Sie den Zustand, bevor Sie die Pipeline erneut starten oder die Methode erneut aufrufen.
FailedEin gewöhnlicher Fehler. Die Datenbank hat den Schreibvorgang abgelehnt, oder die Pipeline ist aus einem anderen Grund fehlgeschlagen.
nullDie Ausführung ist nicht fehlgeschlagen oder trägt keine Fehlerart (siehe die Einschränkung unten).

Das Feld ist additiv: Clients und Controller von vor dieser Änderung ignorieren es oder lassen es weg. Einschränkung: Eine unterbrochene Ausführung (zum Beispiel durch einen Neustart des Controllers oder einen verlorenen Adapter) und eine Ausführung, die ein Adapter nach einer Offline-Phase nachmeldet, tragen keine Fehlerart. Sie zeigen failureKind: null, und ein Methodenaufrufer erhält auch bei einem laufenden Schreibvorgang METHOD_HANDLER_FAILED.

Beispiel​

Diese Pipeline setzt Acme.Assets/Device.UpdateFirmware-1 um: Version 0.0.0 ist gesperrt und wird mit dem deklarierten Fehler FIRMWARE_LOCKED abgewiesen, jede andere Version ist erfolgreich mit dem Ergebnis 1. Dieselbe Pipeline ist die Definition der Integrationstests des Communication Controllers (Methods/SamplePipelines/Device.UpdateFirmware-1.pipeline.yaml).

triggers:
# BindingRequired: die Pipeline läuft nie anonym
- type: FromExecutePipelineCommand@1
callerBinding: BindingRequired
transformations:
# Erfolgspfad: der Ergebnis-Record {"value": <Integer>}
- type: If@1
path: $.parameters.version
operator: NotEqual
value: "0.0.0"
valueType: String
transformations:
- type: SetPrimitiveValue@1
targetPath: $.result.value
value: 1
valueType: Int
# fachliche Ablehnung: FIRMWARE_LOCKED steht in den errors der Methode
- type: If@1
path: $.parameters.version
operator: Equal
value: "0.0.0"
valueType: String
transformations:
- type: WriteJson@1
targetPath: $.result
jsonString: '{"error": {"code": "FIRMWARE_LOCKED", "parameters": {"reason": "maintenance-window"}}}'
- type: SetPipelineExecutionResult@1
path: $.result

Ein Aufrufer der Methode erhält 1 oder für Version 0.0.0 den Fehler FIRMWARE_LOCKED.

Konsistenz und Grenzen​

  • Jeder Aufruf ist eine eigene Arbeitseinheit. Die Knoten einer Pipeline committen, während sie laufen; ein später fehlschlagender Knoten macht frühere nicht rückgängig. Schreibknoten ans Ende oder Kompensation als Knoten modellieren. Der Aufruf läuft wie jede Methode außerhalb der Request-Transaktion des Aufrufers (Konsistenzmodell).
  • Entitäten des Typs der Methode anlegen. Ersetzt die Methode das generische Anlegen eines Typs, ist die Pipeline dieser Methode der einzige Pipeline-Lauf, in dem ApplyChanges@1, ApplyChanges@2 und ImportFromExcel@1 Entitäten dieses Typs einfügen dürfen; in jedem anderen Lauf (auch bei manuellem Ausführen der Pipeline und in einer mit ToPipelineDataEvent verketteten Pipeline) wird das Einfügen mit GENERIC_CREATE_REPLACED_BY_METHOD abgelehnt. Siehe Pipelines, die Entitäten anlegen.
  • Ein Timeout stoppt die Pipeline nicht. Nach METHOD_TIMEOUT kann die Pipeline noch fertig werden; das Ergebnis ist unbekannt. Eine Pipeline-Methode, die nicht doppelt laufen darf, liegt in der Verantwortung des Autors. Ein vom Bus erneut zugestellter Request wird nicht erneut gestartet; der Aufrufer erhält METHOD_OUTCOME_UNKNOWN.
  • Keine sensiblen Parameter oder Ergebnisse. Eine Pipeline-Ausführung speichert ihre Eingabe und Ausgabe, deshalb kann eine Methode mit einem als sensitive: true markierten Parameter nicht handler: pipeline verwenden: Der Compiler lehnt sie mit Meldung 132 ab, die Methode, Typ und sensible Parameter nennt (Entscheidung OD-9). Setzen Sie eine solche Methode als Service-Handler um. Als zweites Tor lehnt der Controller eine Pipeline-Methode mit einem sensitive-Parameter (oder vom Typ Secret) auch zur Laufzeit ab, für ein Modell, das den Compiler nicht passiert hat: Sie wird nicht angekündigt, der Controller protokolliert einen Fehler mit Methode und Parameternamen (nie Werten), und ein Aufruf wird mit METHOD_HANDLER_NOT_AVAILABLE und reason sensitive-parameters-not-supported beantwortet. Dasselbe gilt für ein Ergebnis, das ein Geheimnis ist: Ein als sensitive: true markiertes Ergebnis wird mit Meldung 134 abgelehnt, weil der Ausführungsspeicher die Ausgabe von SetPipelineExecutionResult behält (Sensible Ergebnisse). Das Laufzeit-Tor deckt auch Ergebnisse ab: Eine Pipeline-Methode, deren Ergebnis als sensitive markiert ist (nur mit einer von Hand gebauten oder älteren Definition möglich, die den Compiler nicht passiert hat), wird ebenfalls nicht angekündigt, und ein Aufruf wird mit METHOD_HANDLER_NOT_AVAILABLE und reason sensitive-result-not-supported beantwortet, ohne dass eine Pipeline gestartet wird. Hat eine Methode einen sensiblen Parameter und ein sensibles Ergebnis, bleibt der Grund sensitive-parameters-not-supported. Die Schwärzung sensibler Ergebnisse durch die Plattform (Sensible Ergebnisse) muss sich daher nie mit einer Pipeline-Ausführung befassen, die die Ausgabe gespeichert hat.
  • Dedizierte Adapter. Eine Pipeline auf einem geleasten Adapter wird wie jede Ausführung eingereiht, bis ein Pool-Mitglied geleast ist; bei kurzem Methoden-Timeout kann der Aufruf in METHOD_TIMEOUT enden.
  • Eine Handler-Art pro Methoden-ID. Die Methoden-Queue gilt pro Methoden-ID, nicht pro Mandant. Deklarieren Sie dieselbe Methoden-ID nicht in einem Mandanten als service und in einem anderen als pipeline.
  • Nur synchron. Eine asynchrone Methode (execution.mode: async, Operations-Handle) braucht einen Service-Handler; der Compiler lehnt async zusammen mit handler: pipeline ab (Meldung 142). Siehe Asynchrone Handler.

Konfiguration des Controllers​

Abschnitt PipelineMethods (Umgebungsvariablen OCTO_PIPELINEMETHODS__...):

EinstellungStandardBedeutung
Enabledtruefalse: der Controller bedient keine Pipeline-Methoden.
HeartbeatInterval / Ttl15 s / 45 sWie oft der Controller die Pipelines prüft und sich neu ankündigt, und wie lange eine Ankündigung gilt.
EndpointReadyTimeout30 sWie lange er wartet, bis eine Methoden-Queue Nachrichten annimmt, bevor er die Methode bis zum nächsten Heartbeat überspringt.
PollInterval / MaxPollInterval100 ms / 750 msWie oft er die Ausführung einer gestarteten Pipeline liest, während er wartet.
FailStartupOnInvalidMethodfalsetrue: der Start schlägt fehl, wenn eine Pipeline-Methode keine deployte Pipeline hat oder sensible Parameter oder ein sensibles Ergebnis hat.

Siehe auch​