GraphQL-Mapping

Diese Seite beschreibt, wie Elemente von CK Language 2 im GraphQL-Schema eines Tenants (Asset Repository) erscheinen: das Attribut-access, CK-Interfaces als GraphQL-Interfaces und die CK-Meta-API.

Elementnamen

GraphQL-Namen von CK-Elementen setzen sich aus dem Modellnamen und dem Elementnamen ohne Trennzeichen zusammen. Eine Elementversion über 1 wird ohne den Bindestrich angehängt; Version 1 hat kein Suffix:

CK-Element	GraphQL-Name
Acme.Assets/Named-1	AcmeAssetsNamed
Acme.Assets/Named-2	AcmeAssetsNamed2

Die Regel gilt für alle Elementarten, sodass aufeinanderfolgende Interface-Versionen in einem Schema nebeneinander bestehen. Von abstrakten CK-Typen abgeleitete Interfaces behalten ihre bestehenden <Type>Interface-Namen.

Namenskollisionen

Der Compiler lehnt nur ein Interface mit exakt dem Namen eines Typs desselben Modells ab (Meldung 93). Andere Kollisionen generierter GraphQL-Namen werden noch nicht erkannt und lassen den Aufbau des GraphQL-Schemas des Tenants scheitern – zum Beispiel ein Element, das wörtlich Named2 heißt, neben Named-2, oder ein Interface, dessen Name einem generierten Namen wie <Type>Interface, <Type>Input oder <Type>Update entspricht. Vermeiden Sie solche Namen.

Attribut-access

Das access einer Attributzuweisung bestimmt das generierte Schema und den generischen CRUD-Pfad:

access	Ausgabefeld	Eingabe-/…InputUpdate-Feld	Filter / Sortierung	Generisches create / update
ReadWrite	ja	ja	ja	erlaubt
ReadOnly	ja	ja	ja	erlaubt – in dieser Phase nicht erzwungen
MethodOnly	ja	nein	ja	abgelehnt (ATTRIBUTE_NOT_WRITABLE)
Hidden	nein	nein	abgelehnt (ATTRIBUTE_NOT_QUERYABLE)	abgelehnt (ATTRIBUTE_NOT_WRITABLE)

ReadOnly wird geparst, persistiert und von der CK-Meta-API (access) gemeldet, aber die generischen Eingabetypen und Mutationen behandeln es derzeit wie ReadWrite.

Die vollständige Liste der Pfade, die Hidden abdeckt – und derer, die es noch nicht abdeckt –, steht unter Zugriffsmodifikatoren.

Fehler

Zugriffsfehler (ATTRIBUTE_NOT_WRITABLE, ATTRIBUTE_NOT_QUERYABLE) tragen extensions.code, den Attributpfad und die Operation. Sie enthalten in keiner Umgebung jemals einen Wert; Werte innerhalb von Entity-Selector-Pfaden werden geschwärzt ([apiKeyHash=…]). Ausnahmedetails (Ausnahmetext, innere Ausnahmen, Stack Traces in extensions.details) werden nur in der Development-Umgebung oder mit der Opt-in-Einstellung GraphQl:ExposeExceptionDetails (OCTO_GraphQl__ExposeExceptionDetails) zurückgegeben; bereitgestellte Dienste laufen als Production.

CK-Interfaces als GraphQL-Interfaces

Jedes CK-Interface des Tenants wird zu einem GraphQL-Interface-Typ (benannt wie oben):

• Felder: die Systemfelder jeder Runtime-Entität (rtId, ckTypeId, ...) plus ein Feld pro Attribut-Member – eigene und die jedes erweiterten Interfaces. Optionale Member sind nullable.
• Implementierende Typen: Jeder Entitätstyp, der das CK-Interface implementiert – direkt, über einen Basistyp oder über ein erweitertes Interface –, implementiert das GraphQL-Interface. Weist ein Typ einen optionalen Member nicht zu, erhält er das Feld dennoch; das Feld wird stets zu null aufgelöst. Lassen sich die Felder eines Typs nicht mit dem Interface in Einklang bringen, wird der Typ nicht mit dem GraphQL-Interface verknüpft, und das Asset Repository protokolliert eine Warnung.
• extends entspricht der GraphQL-Interface-Vererbung: Das GraphQL-Interface implementiert alle seine (transitiven) Eltern-Interfaces, und implementierende Objekttypen listen die vollständige Hülle auf.
• Assoziations-Member werden nur dann zu Interface-Feldern, wenn jeder implementierende Typ das ausgehende Assoziationsfeld dieser Rolle in derselben Form (Name, Connection-Typ, Argumente) bereitstellt. Andernfalls wird der Member im GraphQL-Interface ausgelassen, und das Asset Repository protokolliert eine Warnung. Eingehende Assoziations-Member werden nicht bereitgestellt.
• Auf ein Interface eingeschränkte Assoziationen (targetCkInterfaceId): Die Union des Navigationsfelds enthält nur die konkreten Zieltypen, die das Interface implementieren.

Interface-Felder werden mit einem Fragment ausgewählt:

query {
  runtime {
    acmeAssetsGateway(first: 10) {
      items {
        ... on AcmeAssetsIdentified {
          name
          description
          serialNumber
        }
      }
    }
  }
}

Es gibt noch kein Abfragefeld, das Entitäten nach Interface zurückgibt (runtime.byInterface); fragen Sie die konkreten Typen ab und verwenden Sie Fragmente.

CK-Meta-API

Die Abfrage constructionKit beschreibt das Metamodell von CK Language 2. Die neuen enumerationsartigen Werte (visibility, derivable, access, kind, multiplicity) sind Strings mit PascalCase-Namen (Public, Model, Hidden, Instance, ...); Werttypen (valueType, attributeValueType) sind die bestehende GraphQL-Enum (STRING, RECORD, ...). Elemente von Modellen der CK Language 1 melden die v1-Standardwerte.

Typ	Neue Felder
CkType	visibility, derivable, declaredInterfaces, interfaces (deklarierte, geerbte und erweiterte), methods (eigene und geerbte)
CkTypeAttribute	access
CkRecord	visibility, derivable
CkEnum, CkAttribute, CkAssociationRole	visibility
CkModel	ckLanguage (1, wenn nicht deklariert), minEngineVersion, dependencyRanges { range floor } (null bei exakt gepinnten Modellen)
CkInterface (neu)	ckInterfaceId, rtCkInterfaceId, description, visibility, deprecated, extends, allExtends, attributes (ckAttributeId, attributeName, attributeValueType, isOptional, einschließlich erweiterter Member), associations (ckAssociationRoleId, targetCkTypeId, targetCkInterfaceId, multiplicity, isOptional, declaringCkInterfaceId), methods, implementingTypes
CkMethod (neu, nur Definitionen)	methodId, qualifiedMethodId, declaringCkTypeId / declaringCkInterfaceId, kind, description, visibility, parameters (name, valueType, valueCkRecordId, valueCkEnumId, isOptional, sensitive, description), result, errors (CkMethodErrorDefinition), authorization (roles, allowSelf, scopes), execution (timeoutSeconds, idempotent)
ConstructionKitQuery	interfaces(ckModelIds, rtCkId, rtCkIds)

Internal-Elemente werden wie öffentliche aufgelistet – „intern" bedeutet „nicht aus anderen Modellen referenzierbar", nicht geheim.

Beispiel:

query {
  constructionKit {
    types(rtCkId: "Acme.Assets/Device") {
      items {
        visibility
        derivable
        interfaces { rtCkInterfaceId }
        methods {
          methodId
          kind
          parameters { name valueType isOptional sensitive }
          authorization { roles allowSelf }
        }
        attributes(first: 50) { items { attributeName access } }
      }
    }
    interfaces(ckModelIds: ["Acme.Assets"]) {
      items {
        rtCkInterfaceId
        extends { semanticVersionedFullName }
        attributes { attributeName isOptional }
        implementingTypes { semanticVersionedFullName }
      }
    }
    models(first: 50) {
      items {
        id { name }
        ckLanguage
        dependencyRanges { range floor }
      }
    }
  }
}

Weitere CK-Meta-Abfragen: Abruf von Construction Kits.

Methoden

Methodendefinitionen sind ausschließlich in der CK-Meta-API sichtbar. Sie erzeugen keine Mutationsfelder; der Methodenaufruf folgt mit der Methoden-Runtime in einer späteren Phase.

Siehe auch

• Zugriffsmodifikatoren
• Interfaces