Zum Hauptinhalt springen

Communication-Methoden

Seit System.Communication 4.17.0 sind die Operationen auf Adaptern, Workloads und Adapter-Pools und seit 4.18.0 die Operationen auf Pipelines, Data Flows und der Chart-Version eines Workloads, die der Communication Controller über seine REST-API anbietet, auch als CK-Methoden deklariert. Ein Aufrufer findet sie im Tenant-Schema als typisierte Mutationen, und der Communication Controller bearbeitet sie (handler: service). Die Wirkung ist die des REST-Endpunkts: Der Handler ruft dieselben Services auf.

Die REST-Endpunkte bleiben

Die REST-Endpunkte des Communication Controllers sind unverändert und tragen noch keinen Deprecation-Header. Studio, octo-cli und der MCP-Server wechseln in einem späteren Schritt auf die Methoden; erst dann werden die Endpunkte als veraltet markiert.

Adapter​

MethodeArtParameterErgebnisDeklarierte FehlerREST-Endpunkt
DeployUpdate-1InstanzkeinekeinesADAPTER_CONFIGURATION_DEPLOY_FAILED (Parameter message)POST {tenant}/v1/Adapter/deployUpdate?adapterRtEntityId=
ReconcileServiceAccount-1InstanzkeineServiceAccountReconcileResultSERVICE_ACCOUNT_RECONCILE_FAILEDPOST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/reconcile
RotateServiceAccountSecret-1InstanzkeineServiceAccountSecretRotationResultSERVICE_ACCOUNT_ROTATION_FAILEDPOST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/rotateSecret

Workload (Adapter, Applikation, Adapter-Pool)​

Wake ist auf dem abstrakten Basistyp DeployableWorkload deklariert, damit jeder Adapter, jede Applikation und jeder Adapter-Pool die Methode hat, so wie der REST-Endpunkt jedes Workload annimmt.

MethodeArtParameterErgebnisDeklarierte FehlerREST-Endpunkt
Wake-1InstanzkeinekeinesWORKLOAD_WAKE_FAILED (Parameter message)POST {tenant}/v1/Adapter/{workloadRtId}/wake
SetChartVersion-1 (4.18.0)InstanzchartVersion (optional; SemVer, leer oder fehlend = neuester Chart des konfigurierten Repositorys)keinesWORKLOAD_CHART_VERSION_UPDATE_FAILED (METHOD_VALIDATION_FAILED bei ungültiger Version)PATCH {tenant}/v1/Workload/{workloadRtId}/chart-version

SetChartVersion deployt nicht; das Workload wird danach deployt, wie beim REST-Endpunkt.

Adapter-Pool​

MethodeArtParameterErgebnisDeklarierte FehlerREST-Endpunkt
RefreshMirrors-1statischkeineAdapterPoolMirrorSyncResultkeinePOST {tenant}/v1/AdapterPool/mirrors/refresh
PublishMirrors-1statischkeineAdapterPoolMirrorSyncResultkeinePOST {tenant}/v1/AdapterPool/mirrors/publish
GrantLease-1InstanzborrowerTenantId, adapterRtId, executionId (optional), ttlSeconds (optional, 1-3600)AdapterPoolLeaseResultkeinePOST {tenant}/v1/AdapterPool/{adapterPoolRtId}/lease
CancelQueuedExecution-1InstanzexecutionIdkeinesEXECUTION_ALREADY_LEASED, QUEUED_EXECUTION_NOT_FOUNDDELETE {tenant}/v1/AdapterPool/{adapterPoolRtId}/queue/{executionId}

RefreshMirrors arbeitet für den aufrufenden Tenant als Entleiher, PublishMirrors für den aufrufenden Tenant als Verleiher; beide sind statisch und brauchen keinen Pool. GrantLease ist wie sein REST-Endpunkt eine Test- und Diagnose-Schnittstelle: Produktive Leases kommen vom Scheduler. Ein Lease, das nicht vergeben werden kann, ist ein normales Ergebnis mit granted: false und einer statusMessage, kein Fehler. CancelQueuedExecution storniert einen Eintrag der Warteschlange, nie eine laufende Pipeline.

Pipeline (4.18.0)​

MethodeArtParameterErgebnisDeklarierte FehlerREST-Endpunkt
Deploy-1InstanzadapterRtId (optional, Standard: der zugeordnete Adapter), pipelineDefinition (optional, sensitiv)keinesPIPELINE_ADAPTER_NOT_ASSIGNED, PIPELINE_DEPLOY_REJECTED, PIPELINE_DEPLOY_FAILED (Parameter message)POST {tenant}/v1/Pipeline/deploy?adapterRtEntityId=&pipelineRtEntityId=
Execute-1Instanzinput (optional, sensitiv), isDryRun (optional)PipelineExecutionStartResult (executionId, startedAt)PIPELINE_EXECUTION_START_FAILED (Parameter message)POST {tenant}/v1/Pipeline/execute?pipelineRtId=&isDryRun=
SetDebugging-1InstanzenabledPipelineDebugResult (enabled, appliedToRunningAdapter)PIPELINE_DEBUG_CHANGE_FAILED (Parameter message)PATCH {tenant}/v1/Pipeline/{pipelineRtId}/debug
MoveToAdapter-1InstanztargetAdapterRtId, redeploy (optional)PipelineMoveResult (oldAdapterRtId, newAdapterRtId, warning)PIPELINE_MOVE_FAILED (Parameter message)PATCH {tenant}/v1/Pipeline/move-to-adapter

Deploy ohne adapterRtId deployt auf den Adapter, dem die Pipeline zugeordnet ist; pipelineDefinition ersetzt vorher die gespeicherte Definition, wie der Body der REST-Anfrage. Execute startet die Ausführung und liefert ihre Id, ohne auf das Ende zu warten; der Aufrufer wird wie bei REST an eine FromExecutePipelineCommand-Pipeline weitergegeben. MoveToAdapter verschiebt eine Pipeline (der REST-Endpunkt nimmt eine Liste; die Methode wird pro Pipeline einmal aufgerufen). Ein fehlgeschlagenes Redeploy nach dem Verschieben macht das Verschieben nicht rückgängig: Das Ergebnis enthält eine warning. Anders als bei REST deployt redeploy: true auch dann, wenn die Pipeline schon auf den Ziel-Adapter zeigt, damit ein wiederholter Aufruf trotzdem deployt.

Data Flow (4.18.0)​

MethodeArtParameterErgebnisDeklarierte FehlerREST-Endpunkt
Deploy-1InstanzkeinekeinesDATA_FLOW_DEPLOY_FAILED (Parameter message)POST {tenant}/v1/DataFlow/deploy?dataFlowRtId=
Undeploy-1InstanzkeinekeinesDATA_FLOW_UNDEPLOY_FAILED (Parameter message)POST {tenant}/v1/DataFlow/undeploy?dataFlowRtId=

Was ein REST-Endpunkt bleibt​

Die Tenant-Endpunkte des Communication Controllers sind keine Operationen auf einer Entität und bekommen keine Methode: enable und disable schalten die Kommunikationsfähigkeit des Tenants ein und aus (sie installieren oder entfernen das Modell selbst), GET/PUT lifecycle ist Tenant-Konfiguration, validate-expression prüft einen Ausdruck ohne Entität, und encrypt-value ist veraltet (Secret-Overrides gehören in ValueOverride.SecretValue) und nimmt ein Secret entgegen.

Vertrag jeder Methode​

MethodeTimeoutIdempotent
Adapter.DeployUpdate-190 sja
DeployableWorkload.Wake-190 s (das Wake-Budget ist 60 s)ja
Adapter.ReconcileServiceAccount-160 sja
Adapter.RotateServiceAccountSecret-160 snein
AdapterPool.RefreshMirrors-1120 sja
AdapterPool.PublishMirrors-1120 sja
AdapterPool.GrantLease-130 snein
AdapterPool.CancelQueuedExecution-115 snein
Pipeline.Deploy-1200 s (ein Wake von 60 s plus ein Push von 120 s)ja
Pipeline.Execute-130 s (bis die Ausführung gestartet ist)nein
Pipeline.SetDebugging-1300 s (deployt den Data Flow erneut)ja
Pipeline.MoveToAdapter-1200 s (mit redeploy)ja
DataFlow.Deploy-1300 sja
DataFlow.Undeploy-1300 sja
DeployableWorkload.SetChartVersion-115 sja

Alle Methoden antworten synchron. Ein Data Flow über mehrere Adapter weckt und beliefert diese nacheinander, deshalb verwenden DataFlow.Deploy, DataFlow.Undeploy und Pipeline.SetDebugging das maximale Timeout von 300 s; sie werden in einer späteren Version zu asynchronen Operationen.

Eine nicht idempotente Methode lässt sich mit demselben Idempotency-Key gefahrlos wiederholen: Der zweite Aufruf liefert das erste Ergebnis, statt das Secret erneut zu rotieren oder ein weiteres Lease zu vergeben.

  • Rollen: Jede Methode deklariert die Rolle CommunicationManagement, dazu den Scope octo_api, den jeder Methodenaufruf braucht. Die REST-Endpunkte verlangen nur den Scope; eine Methode ohne Rollen ließe nur Administratoren zu, deshalb nennen die Methoden die Rolle, die der Integrationsbereich des Studios und jeder Pipeline-Service-Account tragen. Ein Aufrufer ohne die Rolle erhält METHOD_FORBIDDEN, bevor das Ziel gelesen wird. Ein Token eines anderen Tenants wird abgewiesen (METHOD_FORBIDDEN, Grund tenant-not-allowed).
  • Rollen des Service-Accounts: ReconcileServiceAccount setzt die deklarierten Rollen des Accounts nur, wenn der Aufrufer auch UserManagement hat, wie der REST-Endpunkt; sonst meldet das Ergebnis roleChangesSkipped: true.
  • Kein Secret im Ergebnis: RotateServiceAccountSecret schreibt das neue Secret in die ServiceAccountConfiguration und in den Identity-Client. Das Ergebnis nennt den Client, sagt, ob die Pipelines neu deployt werden müssen (requiresPipelineRedeploy), und enthält eine Meldung, nie das Secret, wie beim REST-Endpunkt. Eine fehlgeschlagene Rotation antwortet mit SERVICE_ACCOUNT_ROTATION_FAILED; das bisherige Secret bleibt gültig.
  • Sensitive Parameter: Pipeline.Deploy.pipelineDefinition (eine Definition kann Zugangsdaten enthalten) und Pipeline.Execute.input sind sensitive deklariert: Sie erscheinen nie in einem Log, im Audit oder in einem Trace. Eine Fehlermeldung, die sie (oder das Token des Aufrufers) zitieren würde, enthält an ihrer Stelle ***. Die Eingabe einer Ausführung auf einem Leased-Adapter (kein Dry Run) wird in der PipelineExecution des Tenants gespeichert und bleibt dort auch nach der Ausführung, wie bei REST.
  • Fehlermeldungen: Die message eines Pipeline- oder Data-Flow-Fehlers enthält den Fehlertext des Controllers (den REST liefert, z. B. die Validierungsfehler des Adapters). Ein unerwarteter Fehler liefert nur den Fehlercode; die Details bleiben im Log des Services.
  • Datenzugriff: Die Instanzmethoden verwenden den Standard für dataAccess (Write): Der Aufrufer braucht eine Schreibberechtigung auf den Ziel-Datensatz.
  • Versionierung: Die Methoden und ihre Ergebnis-Records sind additiv, Minor-Versionen (4.17.0, 4.18.0). Sie ändern keinen Attributzugriff; die Zugangsdaten der Konfigurationen bleiben in 4.x über die generische API schreibbar.

Beispiel​

mutation {
runtime {
systemCommunicationAdapters {
rotateServiceAccountSecret(rtId: "65f0c0ffee65f0c0ffee65f0") {
invocationId
result { clientId requiresPipelineRedeploy message }
}
}
}
}

Eine Pipeline auf den zugeordneten Adapter deployen:

mutation {
runtime {
systemCommunicationPipelines {
deploy(rtId: "65f0c0ffee65f0c0ffee65f1") {
invocationId
}
}
}
}

Betrieb​

Der Communication Controller hostet die Handler mit dem Methoden-Host der Plattform: eine gemeinsame Queue pro Methode, damit jede Replika Aufrufe bedient. Er prüft das weitergereichte Token des Aufrufers mit der Authority seiner eigenen HTTP-API, wie die Pipeline-Methoden-Handler. Methods:Communication:Enabled=false (OCTO_METHODS__COMMUNICATION__ENABLED) schaltet die Handler ab; die REST-Endpunkte funktionieren weiter, und ein Methodenaufruf antwortet mit METHOD_HANDLER_NOT_AVAILABLE. Beim Start werden die Handler gegen das Modell System.Communication des System-Tenants geprüft; fehlt das Modell dort, schlägt der Start mit einer Meldung fehl, die die Methode nennt.