Attributes

Attribute sind wiederverwendbare Property-Definitionen, die auf Typen angewendet werden können. Jedes Attribut besitzt einen Wertetyp und optionale Einschränkungen.

Attribute auflisten

Alle Attribute abrufen:

query getCkAttributes($after: String, $first: Int, $ckModelIds: [String]) {
  constructionKit {
    attributes(after: $after, first: $first, ckModelIds: $ckModelIds) {
      totalCount
      items {
        ckAttributeId {
          fullName
          semanticVersionedFullName
        }
        attributeValueType
      }
    }
  }
}

Antwort

{
  "data": {
    "constructionKit": {
      "attributes": {
        "totalCount": 25,
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Basic-1.0.0/Name-1",
              "semanticVersionedFullName": "Basic/Name"
            },
            "attributeValueType": "STRING"
          },
          {
            "ckAttributeId": {
              "fullName": "Industry.Energy-1.0.0/Voltage-1",
              "semanticVersionedFullName": "Industry.Energy/Voltage"
            },
            "attributeValueType": "DOUBLE"
          }
        ]
      }
    }
  }
}

Nach Modell filtern

Attribute aus bestimmten Modellen abrufen:

query {
  constructionKit {
    attributes(ckModelIds: ["Industry.Energy-1"]) {
      totalCount
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
      }
    }
  }
}

Details eines Attributs

Detaillierte Informationen zu einem bestimmten Attribut abrufen:

query getCkAttributeDetails($attributeId: String) {
  constructionKit {
    attributes(ckId: $attributeId) {
      items {
        ckAttributeId {
          fullName
          semanticVersionedFullName
        }
        description
        attributeValueType
        defaultValues
        ckEnum {
          ckEnumId {
            fullName
            semanticVersionedFullName
          }
          useFlags
          isExtensible
          values {
            key
            name
            description
            isExtension
          }
        }
        ckRecord {
          ckRecordId {
            fullName
            semanticVersionedFullName
          }
          isAbstract
          isFinal
        }
      }
    }
  }
}

Variablen:

{
  "attributeId": "Industry.Energy-1.0.0/State-1"
}

Antwort für ein Enum-Attribut

{
  "data": {
    "constructionKit": {
      "attributes": {
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Industry.Energy-1.0.0/State-1",
              "semanticVersionedFullName": "Industry.Energy/State"
            },
            "description": "The operational state of the energy meter",
            "attributeValueType": "ENUM",
            "defaultValues": null,
            "ckEnum": {
              "ckEnumId": {
                "fullName": "Industry.Energy-1.0.0/EnergyMeterState-1",
                "semanticVersionedFullName": "Industry.Energy/EnergyMeterState"
              },
              "useFlags": false,
              "isExtensible": false,
              "values": [
                { "key": 0, "name": "OFF", "description": "Meter is off", "isExtension": false },
                { "key": 1, "name": "ON", "description": "Meter is on", "isExtension": false },
                { "key": 2, "name": "STANDBY", "description": "Meter is in standby", "isExtension": false }
              ]
            },
            "ckRecord": null
          }
        ]
      }
    }
  }
}

Antwort für ein Record-Attribut

{
  "data": {
    "constructionKit": {
      "attributes": {
        "items": [
          {
            "ckAttributeId": {
              "fullName": "Basic-1.0.0/Contact-1",
              "semanticVersionedFullName": "Basic/Contact"
            },
            "description": "Contact information",
            "attributeValueType": "RECORD",
            "defaultValues": null,
            "ckEnum": null,
            "ckRecord": {
              "ckRecordId": {
                "fullName": "Basic-1.0.0/Contact-1",
                "semanticVersionedFullName": "Basic/Contact"
              },
              "isAbstract": false,
              "isFinal": false
            }
          }
        ]
      }
    }
  }
}

Attribute durchsuchen

Attribute anhand ihres Namens suchen:

query {
  constructionKit {
    attributes(
      searchFilter: {
        searchTerm: "voltage"
        type: ATTRIBUTE_FILTER
        attributePaths: ["ckAttributeId.fullName"]
      }
    ) {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
      }
    }
  }
}

Felder eines Attributs

CkAttribute

Feld	Typ	Beschreibung
ckAttributeId	CkAttributeId	Der Identifier des Attributs
description	String	Beschreibung des Attributs
attributeValueType	String	Der Datentyp (STRING, INT32, ENUM, RECORD usw.)
defaultValues	[SimpleScalar]	Standardwerte für das Attribut
ckEnum	CkEnum	Enum-Definition (falls attributeValueType ENUM ist)
ckRecord	CkRecord	Record-Definition (falls attributeValueType RECORD ist)

Attribut-Wertetypen

Wert	Beschreibung	GraphQL Input	GraphQL Output
STRING	Textwert	String	String
STRING_ARRAY	Array von Textwerten	[String]	[String]
INT32	32-Bit-Ganzzahl	Int	Int
INT32_ARRAY	Array von 32-Bit-Ganzzahlen	[Int]	[Int]
INT64	64-Bit-Ganzzahl	Long	Long
FLOAT	Gleitkommazahl	Float	Float
DOUBLE	Gleitkommazahl mit doppelter Genauigkeit	Decimal	Decimal
BOOLEAN	Wahr/Falsch-Wert	Boolean	Boolean
DATE_TIME	Datums- und Zeitwert	DateTime	DateTime
DATE_TIME_OFFSET	Datum/Zeit mit Zeitzonen-Offset	DateTimeOffset	DateTimeOffset
TIME_SPAN	Dauer/Zeitintervall (in Sekunden)	Decimal (Sekunden)	Decimal (Sekunden)
BINARY	Inline-Binärdaten (Byte-Array)	[Int] (0-255)	[Int] (0-255)
BINARY_LINKED	Referenz auf eine externe Binärdatei	über REST-API	LargeBinaryInfo
OBJECT_ID	MongoDB-ObjectId-Referenz	OctoObjectId	OctoObjectId
ENUM	Enumerationswert (siehe verknüpftes ckEnum)	Generated Enum	Generated Enum
RECORD	Einzelner eingebetteter Record (siehe verknüpftes ckRecord)	Generated Input	Generated Type
RECORD_ARRAY	Array eingebetteter Records	[Generated Input]	[Generated Type]
GEOSPATIAL_POINT	Geospatiale Punktkoordinaten	PointInput	RtGeospatialValue

---

Spezielle Skalar-Typen

TimeSpan-Attribute

TimeSpan-Attribute speichern Werte für Dauer/Zeitintervalle. In GraphQL werden TimeSpan-Werte als Sekunden (Dezimalzahl) dargestellt.

YAML-Definition:

attributes:
  - id: DataTransmissionInterval
    valueType: TimeSpan
    description: "Interval between data transmissions"

Query-Beispiel:

query {
  constructionKit {
    attributes(ckId: "OctoSdkDemo-1.0.0/DataTransmissionInterval-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "TIME_SPAN"
        description
      }
    }
  }
}

Runtime-Abfrage:

TimeSpan-Werte werden als Sekunden zurückgegeben:

query {
  runtime {
    octoSdkDemoMeteringPoints(first: 10) {
      items {
        rtId
        meteringPointNumber
        dataTransmissionInterval  # Returns seconds as decimal
      }
    }
  }
}

Antwort:

{
  "data": {
    "runtime": {
      "octoSdkDemoMeteringPoints": {
        "items": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c",
            "meteringPointNumber": "MP-001",
            "dataTransmissionInterval": 900.0
          }
        ]
      }
    }
  }
}

Gängige TimeSpan-Werte:

Dauer	Sekunden
1 Minute	60
5 Minuten	300
15 Minuten	900
1 Stunde	3600
1 Tag	86400
1 Woche	604800

---

Komplexe Attributtypen

Record-Attribute

Record-Attribute betten strukturierte Daten in eine Entität ein. Die Record-Struktur wird separat im Construction Kit definiert.

YAML-Definition:

attributes:
  - id: MainSpecification
    valueType: Record
    valueCkRecordId: ${this}/Specification
    description: "Main specification of the product"

Query-Beispiel:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/MainSpecification-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType
        ckRecord {
          ckRecordId {
            fullName
          }
          attributes {
            items {
              attributeName
              attributeValueType
            }
          }
        }
      }
    }
  }
}

RecordArray-Attribute

RecordArray-Attribute speichern Arrays strukturierter Records – nützlich für Listen von Spezifikationen, Kontakten oder anderen sich wiederholenden Datenstrukturen.

YAML-Definition:

attributes:
  - id: TechnicalSpecifications
    valueType: RecordArray
    valueCkRecordId: ${this}/Specification
    description: "List of technical specifications"

Query-Beispiel:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/TechnicalSpecifications-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "RECORD_ARRAY"
        ckRecord {
          ckRecordId {
            fullName
          }
        }
      }
    }
  }
}

Binary-Attribute

Binary-Attribute speichern kleine Binärdaten direkt in der Entität als Inline-Byte-Arrays. Das ist ideal für kleine Dateien wie Profilbilder, Icons oder zwischengespeicherte Daten, bei denen eine externe Dateispeicherung übertrieben wäre.

YAML-Definition:

attributes:
  - id: ProfilePicture
    valueType: Binary
    description: "Profile picture stored inline"

Query-Beispiel:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/ProfilePicture-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "BINARY"
        description
      }
    }
  }
}

Runtime-Abfrage – Binary-Ausgabe:

Binärdaten werden als Array von Byte-Werten (Ganzzahlen 0-255) zurückgegeben:

query {
  runtime {
    octoSdkDemoCustomers(first: 10) {
      items {
        rtId
        contact {
          firstName
          lastName
        }
        profilePicture  # Returns [137, 80, 78, 71, ...]
      }
    }
  }
}

Antwort:

{
  "data": {
    "runtime": {
      "octoSdkDemoCustomers": {
        "items": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c",
            "contact": {
              "firstName": "John",
              "lastName": "Doe"
            },
            "profilePicture": [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13]
          }
        ]
      }
    }
  }
}

Binary vs BinaryLinked

• Binary: Kleine Daten inline gespeichert (< 16MB), sofortiger Zugriff, kein separater Download
• BinaryLinked: Große Dateien extern gespeichert, erfordert einen Download über die REST-API

BinaryLinked-Attribute

BinaryLinked-Attribute speichern Referenzen auf externe Binärdateien (Bilder, Dokumente, PDFs usw.). Dateien werden über einen GraphQL Multipart Request hochgeladen und über die REST-API heruntergeladen. Die Entität speichert nur die Referenz-Metadaten.

YAML-Definition:

attributes:
  - id: ProductImage
    valueType: BinaryLinked
    description: "Product image file"

  - id: ProductDatasheet
    valueType: BinaryLinked
    description: "Product datasheet document"

Query-Beispiel:

query {
  constructionKit {
    attributes(ckId: "MyModel-1.0.0/ProductImage-1") {
      items {
        ckAttributeId {
          fullName
        }
        attributeValueType  # Returns "BINARY_LINKED"
        description
      }
    }
  }
}

Runtime-Abfrage – BinaryLinked-Ausgabe:

Beim Abfragen von Entitäten mit BinaryLinked-Attributen erhalten Sie Metadaten über die Binärdaten:

query {
  runtime {
    products(first: 10) {
      items {
        productImage {
          binaryId
          filename
          contentType
          size
          downloadUri
        }
      }
    }
  }
}

LargeBinaryInfo-Felder:

Feld	Typ	Beschreibung
binaryId	OctoObjectId	Eindeutiger Identifier der Binärdaten
filename	String	Ursprünglicher Dateiname
contentType	String	MIME-Typ (z. B. image/png)
size	Long	Dateigröße in Bytes
downloadUri	String	URI zum Herunterladen des Binärinhalts

tipp

Zum Erstellen und Aktualisieren von Entitäten mit komplexen Attributtypen siehe:

• Create Mutations – Complex Attribute Types
• Update Mutations – Updating Complex Attribute Types