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 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
| Methode | Art | Parameter | Ergebnis | Deklarierte Fehler | REST-Endpunkt |
|---|---|---|---|---|---|
DeployUpdate-1 | Instanz | keine | keines | ADAPTER_CONFIGURATION_DEPLOY_FAILED (Parameter message) | POST {tenant}/v1/Adapter/deployUpdate?adapterRtEntityId= |
ReconcileServiceAccount-1 | Instanz | keine | ServiceAccountReconcileResult | SERVICE_ACCOUNT_RECONCILE_FAILED | POST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/reconcile |
RotateServiceAccountSecret-1 | Instanz | keine | ServiceAccountSecretRotationResult | SERVICE_ACCOUNT_ROTATION_FAILED | POST {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.
| Methode | Art | Parameter | Ergebnis | Deklarierte Fehler | REST-Endpunkt |
|---|---|---|---|---|---|
Wake-1 | Instanz | keine | keines | WORKLOAD_WAKE_FAILED (Parameter message) | POST {tenant}/v1/Adapter/{workloadRtId}/wake |
SetChartVersion-1 (4.18.0) | Instanz | chartVersion (optional; SemVer, leer oder fehlend = neuester Chart des konfigurierten Repositorys) | keines | WORKLOAD_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
| Methode | Art | Parameter | Ergebnis | Deklarierte Fehler | REST-Endpunkt |
|---|---|---|---|---|---|
RefreshMirrors-1 | statisch | keine | AdapterPoolMirrorSyncResult | keine | POST {tenant}/v1/AdapterPool/mirrors/refresh |
PublishMirrors-1 | statisch | keine | AdapterPoolMirrorSyncResult | keine | POST {tenant}/v1/AdapterPool/mirrors/publish |
GrantLease-1 | Instanz | borrowerTenantId, adapterRtId, executionId (optional), ttlSeconds (optional, 1-3600) | AdapterPoolLeaseResult | keine | POST {tenant}/v1/AdapterPool/{adapterPoolRtId}/lease |
CancelQueuedExecution-1 | Instanz | executionId | keines | EXECUTION_ALREADY_LEASED, QUEUED_EXECUTION_NOT_FOUND | DELETE {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)
| Methode | Art | Parameter | Ergebnis | Deklarierte Fehler | REST-Endpunkt |
|---|---|---|---|---|---|
Deploy-1 | Instanz | adapterRtId (optional, Standard: der zugeordnete Adapter), pipelineDefinition (optional, sensitiv) | keines | PIPELINE_ADAPTER_NOT_ASSIGNED, PIPELINE_DEPLOY_REJECTED, PIPELINE_DEPLOY_FAILED (Parameter message) | POST {tenant}/v1/Pipeline/deploy?adapterRtEntityId=&pipelineRtEntityId= |
Execute-1 | Instanz | input (optional, sensitiv), isDryRun (optional) | PipelineExecutionStartResult (executionId, startedAt) | PIPELINE_EXECUTION_START_FAILED (Parameter message) | POST {tenant}/v1/Pipeline/execute?pipelineRtId=&isDryRun= |
SetDebugging-1 | Instanz | enabled | PipelineDebugResult (enabled, appliedToRunningAdapter) | PIPELINE_DEBUG_CHANGE_FAILED (Parameter message) | PATCH {tenant}/v1/Pipeline/{pipelineRtId}/debug |
MoveToAdapter-1 | Instanz | targetAdapterRtId, 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)
| Methode | Art | Parameter | Ergebnis | Deklarierte Fehler | REST-Endpunkt |
|---|---|---|---|---|---|
Deploy-1 | Instanz | keine | keines | DATA_FLOW_DEPLOY_FAILED (Parameter message) | POST {tenant}/v1/DataFlow/deploy?dataFlowRtId= |
Undeploy-1 | Instanz | keine | keines | DATA_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
| Methode | Timeout | Idempotent |
|---|---|---|
Adapter.DeployUpdate-1 | 90 s | ja |
DeployableWorkload.Wake-1 | 90 s (das Wake-Budget ist 60 s) | ja |
Adapter.ReconcileServiceAccount-1 | 60 s | ja |
Adapter.RotateServiceAccountSecret-1 | 60 s | nein |
AdapterPool.RefreshMirrors-1 | 120 s | ja |
AdapterPool.PublishMirrors-1 | 120 s | ja |
AdapterPool.GrantLease-1 | 30 s | nein |
AdapterPool.CancelQueuedExecution-1 | 15 s | nein |
Pipeline.Deploy-1 | 200 s (ein Wake von 60 s plus ein Push von 120 s) | ja |
Pipeline.Execute-1 | 30 s (bis die Ausführung gestartet ist) | nein |
Pipeline.SetDebugging-1 | 300 s (deployt den Data Flow erneut) | ja |
Pipeline.MoveToAdapter-1 | 200 s (mit redeploy) | ja |
DataFlow.Deploy-1 | 300 s | ja |
DataFlow.Undeploy-1 | 300 s | ja |
DeployableWorkload.SetChartVersion-1 | 15 s | ja |
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 Scopeocto_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ältMETHOD_FORBIDDEN, bevor das Ziel gelesen wird. Ein Token eines anderen Tenants wird abgewiesen (METHOD_FORBIDDEN, Grundtenant-not-allowed). - Rollen des Service-Accounts:
ReconcileServiceAccountsetzt die deklarierten Rollen des Accounts nur, wenn der Aufrufer auchUserManagementhat, wie der REST-Endpunkt; sonst meldet das ErgebnisroleChangesSkipped: true. - Kein Secret im Ergebnis:
RotateServiceAccountSecretschreibt das neue Secret in dieServiceAccountConfigurationund 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 mitSERVICE_ACCOUNT_ROTATION_FAILED; das bisherige Secret bleibt gültig. - Sensitive Parameter:
Pipeline.Deploy.pipelineDefinition(eine Definition kann Zugangsdaten enthalten) undPipeline.Execute.inputsindsensitivedeklariert: 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 derPipelineExecutiondes Tenants gespeichert und bleibt dort auch nach der Ausführung, wie bei REST. - Fehlermeldungen: Die
messageeines 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.