Aktualisieren
GraphQL erlaubt es, Daten abzufragen und zu verändern. Mutationen sind Operationen wie Erstellen, Aktualisieren und Löschen. Dieses Kapitel beschreibt, wie Daten aktualisiert werden können.
API-Ansätze
OctoMesh bietet zwei Möglichkeiten, Entitäten zu aktualisieren:
| Ansatz | Endpunkt | Anwendungsfall |
|---|---|---|
| Typisiert | runtime.[typeName].update | Stark typisiert, IDE-Autovervollständigung, Validierung zur Kompilierzeit |
| Generisch | runtime.runtimeEntities.update | Dynamische Typbehandlung, flexible Attributangabe |
Generische Update-Mutation
Die generische Mutation runtimeEntities.update erlaubt es, Entitäten beliebigen Typs zu aktualisieren, indem rtId und Attribute dynamisch angegeben werden. Dies ist nützlich, wenn der Typ zur Kompilierzeit nicht bekannt ist oder wenn dynamische Anwendungen erstellt werden.
Einfache generische Aktualisierung
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "69692194d66195e5364c310f"
item: {
ckTypeId: "Basic/TreeNode"
attributes: [
{ attributeName: "name", value: "Updated Name" }
{ attributeName: "Description", value: "New description" }
]
}
}
]
) {
rtId
ckTypeId
attributes {
items {
attributeName
value
}
}
}
}
}
}
Das Ergebnis lautet:
{
"data": {
"runtime": {
"runtimeEntities": {
"update": [
{
"rtId": "69692194d66195e5364c310f",
"ckTypeId": "Basic/TreeNode",
"attributes": {
"items": [
{ "attributeName": "name", "value": "Updated Name" },
{ "attributeName": "Description", "value": "New description" }
]
}
}
]
}
}
}
}
Generische Stapel-Aktualisierung
Mehrere Entitäten können in einer einzigen Mutation aktualisiert werden:
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "69692194d66195e5364c310f"
item: {
ckTypeId: "Basic/TreeNode"
attributes: [
{ attributeName: "name", value: "Node 1 Updated" }
]
}
},
{
rtId: "69692194d66195e5364c3110"
item: {
ckTypeId: "Basic/TreeNode"
attributes: [
{ attributeName: "name", value: "Node 2 Updated" }
]
}
}
]
) {
rtId
ckTypeId
}
}
}
}
Struktur der generischen Update-Eingabe
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
rtId | OctoObjectId | Ja | Runtime-Identifier der zu aktualisierenden Entität |
item | GenericEntityInput | Ja | Das Update-Payload |
GenericEntityInput:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
ckTypeId | String | Ja | Construction-Kit-Typ-Identifier (z. B. Basic/TreeNode) |
attributes | [AttributeInput] | Nein | Array von zu aktualisierenden Attribut-Name-Wert-Paaren |
AttributeInput:
| Feld | Typ | Beschreibung |
|---|---|---|
attributeName | String | Name des zu aktualisierenden Attributs |
value | SimpleScalar | Neuer Wert für das Attribut |
Nur die im Array attributes angegebenen Attribute werden aktualisiert. Andere Attribute bleiben unverändert.
Typisierte Update-Mutation
Der typisierte Ansatz verwendet typspezifische Endpunkte mit stark typisierten Eingabeobjekten. Dies bietet bessere IDE-Unterstützung und Validierung zur Kompilierzeit.
Einfache Update-Mutation
Der Bereich runtime erlaubt den Zugriff auf Entitäten des Runtime-Modells. Um eine Entität zu aktualisieren, müssen Sie die rtId der Entität sowie die Felder angeben, die Sie aktualisieren möchten.
mutation {
runtime {
industryEnergyEnergyMeters {
update(
entities: [
{
rtId: "662532d5241639b42933057e"
item: {
voltage: 235
state: ON
name: "Updated Energy Meter"
}
}
]
) {
rtId
voltage
state
name
}
}
}
}
Diese Mutation aktualisiert den Energiezähler mit der angegebenen rtId. Nur die in der Mutation angegebenen Felder werden aktualisiert. Das Ergebnis lautet:
{
"data": {
"runtime": {
"industryEnergyEnergyMeters": {
"update": [
{
"rtId": "662532d5241639b42933057e",
"voltage": 235,
"state": "ON",
"name": "Updated Energy Meter"
}
]
}
}
}
}
Aktualisierung mit Variablen
Für komplexere Aktualisierungen wird empfohlen, GraphQL-Variablen zu verwenden. Der Eingabetyp für Aktualisierungen folgt der Namenskonvention [TypeName]InputUpdate.
mutation updateAdapter($entities: [SystemCommunicationAdapterInputUpdate]!) {
runtime {
systemCommunicationAdapters {
update(entities: $entities) {
rtId
ckTypeId
name
description
configuration
imageName
imageVersion
deploymentState
}
}
}
}
Variablen:
{
"entities": [
{
"rtId": "65d5c447b420da3fb12381bc",
"item": {
"name": "Updated Adapter Name",
"configuration": "{\"host\": \"localhost\", \"port\": 8080}"
}
}
]
}
Stapel-Aktualisierungen
Mehrere Entitäten können in einer einzigen Mutation aktualisiert werden, indem ein Array von Entitäten angegeben wird:
mutation {
runtime {
industryEnergyEnergyMeters {
update(
entities: [
{
rtId: "662532d5241639b42933057e"
item: {
state: ON
}
},
{
rtId: "65dc6d24cc529cdc46c84fcc"
item: {
state: OFF
}
}
]
) {
rtId
state
}
}
}
}
Aktualisierung mit verschachtelten Objekten
Für Entitäten mit verschachtelten Objekten wie Records muss das gesamte verschachtelte Objekt angegeben werden:
mutation updateCustomer($customer: EnergyCommunityCustomerInputUpdate!) {
runtime {
energyCommunityCustomers {
update(entities: [$customer]) {
rtId
contact {
firstName
lastName
email
address {
street
zipcode
cityTown
}
}
bankAccount {
iban
accountHolder
}
}
}
}
}
Variablen:
{
"customer": {
"rtId": "667acc3be06025c7329fc57c",
"contact": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"address": {
"street": "Main Street 1",
"zipcode": "12345",
"cityTown": "Berlin"
}
},
"bankAccount": {
"iban": "DE89370400440532013000",
"accountHolder": "John Doe"
}
}
}
Namenskonvention für Eingabetypen
| Operation | Muster des Eingabetyps | Beispiel |
|---|---|---|
| Create | [TypeName]Input | SystemCommunicationAdapterInput |
| Update | [TypeName]InputUpdate | SystemCommunicationAdapterInputUpdate |
Der wesentliche Unterschied besteht darin, dass Update-Eingabetypen stets das Feld rtId benötigen, um die zu aktualisierende Entität zu identifizieren.
Aktualisierung spezieller skalarer Typen
TimeSpan-Attribute aktualisieren
TimeSpan-Attribute werden aktualisiert, indem der neue Wert in Sekunden (Dezimalzahl) angegeben wird.
Typisierte Aktualisierung mit TimeSpan
mutation {
runtime {
octoSdkDemoMeteringPoints {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
# Update interval from 15 minutes to 30 minutes
dataTransmissionInterval: 1800
}
}
]
) {
rtId
meteringPointNumber
dataTransmissionInterval
}
}
}
}
Generische Aktualisierung mit TimeSpan
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
ckTypeId: "OctoSdkDemo/MeteringPoint"
attributes: [
# Update to 1 hour interval
{ attributeName: "dataTransmissionInterval", value: 3600 }
]
}
}
]
) {
rtId
attributes(first: 10) {
items {
attributeName
value
}
}
}
}
}
}
Aktualisierung komplexer Attributtypen
OctoMesh unterstützt die Aktualisierung komplexer Attributtypen, darunter Record, RecordArray, Binary und BinaryLinked.
Die folgenden Beispiele verwenden den Typ OctoSdkDemo/Customer aus dem Construction Kit Octo.Sdk.Demo, der Folgendes umfasst:
contact- Record (mit verschachteltemaddress-Record)bankAccount- Recordnotes- RecordArray vonCustomerNoteprofilePicture- Binary (inline-Binärdaten)contractDocument- BinaryLinked (Verweis auf externe Datei)
Record-Attribute aktualisieren
Beim Aktualisieren eines Record-Attributs geben Sie die vollständige Record-Struktur an. Record-Aktualisierungen ersetzen den gesamten Record-Wert.
Typisierte Aktualisierung mit Record
Aktualisieren Sie die Kontaktinformationen des Kunden:
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
contact: {
legalEntityType: NATURAL_PERSON
firstName: "John"
lastName: "Doe-Smith" # Changed last name
email: "john.doe-smith@newmail.com" # New email
address: {
street: "456 New Avenue" # New address
zipcode: 10117
cityTown: "Berlin"
nationalCode: "DE"
}
}
}
}
]
) {
rtId
contact {
firstName
lastName
email
address {
street
cityTown
}
}
}
}
}
}
Generische Aktualisierung mit Record
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
ckTypeId: "OctoSdkDemo/Customer"
attributes: [
{
attributeName: "contact"
value: {
legalEntityType: "NATURAL_PERSON"
firstName: "John"
lastName: "Doe-Smith"
email: "john.doe-smith@newmail.com"
address: {
street: "456 New Avenue"
zipcode: 10117
cityTown: "Berlin"
nationalCode: "DE"
}
}
}
]
}
}
]
) {
rtId
attributes(first: 10) {
items {
attributeName
value
}
}
}
}
}
}
RecordArray-Attribute aktualisieren
RecordArray-Aktualisierungen ersetzen das gesamte Array. Um Elemente hinzuzufügen, geben Sie alle bestehenden Elemente plus die neuen an.
Typisierte Aktualisierung mit RecordArray
Fügen Sie den Notizen des Kunden eine neue Notiz hinzu:
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
notes: [
# Existing notes (must be included to keep them)
{
date: "2024-01-15T10:30:00Z"
text: "Initial contact - interested in premium plan"
author: "Sales Team"
category: "Sales"
}
{
date: "2024-01-20T14:00:00Z"
text: "Contract signed"
author: "Account Manager"
category: "Contract"
}
# New note
{
date: "2024-03-01T09:00:00Z"
text: "Customer requested support for billing inquiry"
author: "Support Team"
category: "Support"
}
]
}
}
]
) {
rtId
notes {
date
text
author
category
}
}
}
}
}
Generische Aktualisierung mit RecordArray
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
ckTypeId: "OctoSdkDemo/Customer"
attributes: [
{
attributeName: "notes"
value: [
{
date: "2024-01-15T10:30:00Z"
text: "Initial contact"
author: "Sales Team"
category: "Sales"
}
{
date: "2024-03-01T09:00:00Z"
text: "New support request"
author: "Support Team"
category: "Support"
}
]
}
]
}
}
]
) {
rtId
attributes(first: 10) {
items {
attributeName
value
}
}
}
}
}
}
Binary-Attribute aktualisieren
Binary-Attribute speichern inline-Binärdaten als Byte-Arrays. Aktualisierungen ersetzen die gesamten Binärdaten.
Typisierte Aktualisierung mit Binary
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
# Update profilePicture with new image data (PNG header bytes as example)
profilePicture: [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82]
}
}
]
) {
rtId
profilePicture
}
}
}
}
Generische Aktualisierung mit Binary
mutation {
runtime {
runtimeEntities {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
ckTypeId: "OctoSdkDemo/Customer"
attributes: [
{
attributeName: "profilePicture"
value: [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82]
}
]
}
}
]
) {
rtId
attributes(first: 10) {
items {
attributeName
value
}
}
}
}
}
}
Binary-Attribute leeren
Um Binärdaten zu entfernen, setzen Sie das Attribut auf null:
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
profilePicture: null # Remove profilePicture
}
}
]
) {
rtId
profilePicture
}
}
}
}
Record- und RecordArray-Attribute leeren
Um ein Record- oder RecordArray-Attribut zu leeren, setzen Sie es auf null:
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
bankAccount: null # Remove bank account
notes: null # Clear all notes
}
}
]
) {
rtId
bankAccount {
iban
}
notes {
text
}
}
}
}
}
Mehrere komplexe Attribute aktualisieren
Sie können mehrere komplexe Attribute in einer einzigen Mutation aktualisieren:
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
customerStatus: ACTIVE
phoneNumberMobile: "+49 171 9999999"
# Update contact Record
contact: {
legalEntityType: NATURAL_PERSON
firstName: "Max"
lastName: "Mustermann"
email: "max.mustermann@updated.com"
address: {
street: "Neue Straße 100"
zipcode: 10119
cityTown: "Berlin"
nationalCode: "DE"
}
}
# Add bank account Record
bankAccount: {
iban: "DE89370400440532013000"
swiftCode: "COBADEFFXXX"
accountHolder: "Max Mustermann"
}
# Update notes RecordArray
notes: [
{
date: "2024-01-10T09:00:00Z"
text: "Customer data updated"
author: "Admin"
category: "Update"
}
]
}
}
]
) {
rtId
customerStatus
phoneNumberMobile
contact {
firstName
lastName
email
address {
street
cityTown
}
}
bankAccount {
iban
accountHolder
}
notes {
date
text
author
}
}
}
}
}
Partielle Record-Aktualisierungen
Record-Attribute unterstützen keine partiellen Aktualisierungen. Beim Aktualisieren eines Records müssen Sie alle erforderlichen Felder angeben. Optionale Felder, die nicht angegeben werden, werden geleert.
Wenn Sie nur bestimmte Felder innerhalb eines Records aktualisieren möchten, fragen Sie zunächst die aktuellen Werte ab, führen Sie Ihre Änderungen zusammen und senden Sie dann den vollständigen Record:
# Step 1: Query current values
query {
runtime {
octoSdkDemoCustomers(rtIds: ["693c5b93464d7d9e1396cf1c"]) {
items {
contact {
legalEntityType
firstName
lastName
email
address {
street
zipcode
cityTown
nationalCode
}
}
}
}
}
}
# Step 2: Update with merged values (only changing email)
mutation {
runtime {
octoSdkDemoCustomers {
update(
entities: [
{
rtId: "693c5b93464d7d9e1396cf1c"
item: {
contact: {
legalEntityType: NATURAL_PERSON # Keep original
firstName: "John" # Keep original
lastName: "Doe" # Keep original
email: "john.doe@newemail.com" # Updated value
address: {
street: "123 Main Street" # Keep original
zipcode: 10115 # Keep original
cityTown: "Berlin" # Keep original
nationalCode: "DE" # Keep original
}
}
}
}
]
) {
rtId
contact {
firstName
lastName
email
address {
street
cityTown
}
}
}
}
}
}