Create

GraphQL ermöglicht das Abfragen und Mutieren von Daten. Mutationen sind Operationen wie Erstellen, Aktualisieren und Löschen. Dieses Kapitel beschreibt, wie Daten erstellt werden können.

API-Ansätze

OctoMesh bietet zwei Möglichkeiten, Entitäten zu erstellen:

Approach	Endpoint	Use Case
Typed	runtime.[typeName].create	Stark typisiert, IDE-Autovervollständigung, Validierung zur Kompilierzeit
Generic	runtime.runtimeEntities.create	Dynamische Typbehandlung, flexible Attributangabe

---

Generische Create-Mutation

Die generische Mutation runtimeEntities.create ermöglicht das Erstellen von Entitäten jeden Typs, indem die ckTypeId dynamisch angegeben wird. Dies ist nützlich, wenn der Typ zur Kompilierzeit nicht bekannt ist oder wenn dynamische Anwendungen erstellt werden.

Grundlegendes generisches Create

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "Basic/TreeNode"
            attributes: [
              { attributeName: "name", value: "My Node" }
            ]
          }
        ]
      ) {
        rtId
      }
    }
  }
}

Das Ergebnis lautet:

{
  "data": {
    "runtime": {
      "runtimeEntities": {
        "create": [
          {
            "rtId": "69692194d66195e5364c310f"
          }
        ]
      }
    }
  }
}

Generisches Create mit Assoziationen

Sie können Entitäten mit Assoziationen zu bestehenden Entitäten erstellen:

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "Basic/TreeNode"
            attributes: [
              { attributeName: "name", value: "Child Node" }
            ]
            associations: {
              roleName: "parent"
              targets: [
                {
                  modOption: CREATE
                  target: {
                    ckTypeId: "Basic/Tree"
                    rtId: "65dc6d24cc529cdc46c84fca"
                  }
                }
              ]
            }
          }
        ]
      ) {
        rtId
      }
    }
  }
}

Struktur des generischen Create-Inputs

Field	Type	Required	Description
ckTypeId	String	Yes	Construction-Kit-Typ-Identifier (z. B. Basic/TreeNode)
attributes	[AttributeInput]	No	Array von Attribut-Name-Wert-Paaren
associations	AssociationInput	No	Assoziationsdefinitionen

AttributeInput:

Field	Type	Description
attributeName	String	Name des Attributs
value	SimpleScalar	Zu setzender Wert

AssociationInput:

Field	Type	Description
roleName	String	Name der Assoziationsrolle
targets	[AssociationTargetInput]	Zielentitäten für die Assoziation

AssociationTargetInput:

Field	Type	Description
modOption	ModOption	Modifikationsoption (CREATE, DELETE)
target	RtEntityId	Referenz auf die Zielentität mit rtId und ckTypeId

---

Typisierte Create-Mutation

Der typisierte Ansatz verwendet typspezifische Endpunkte mit stark typisierten Input-Objekten. Dies bietet bessere IDE-Unterstützung und Validierung zur Kompilierzeit.

Einfache Create-Mutation

Der Bereich runtime ermöglicht den Zugriff auf Entitäten fo the Runtime Model. Beginnen wir mit einem einfachen Beispiel, das den Namen aller Energiezähler abfragt.

mutation {
    runtime {
        energyCommunityCustomers {
            create(
                entities: [
                    {
                        contact:{
                            firstName: "John"
                            lastName: "Doe"
                            address: {
                                nationalCode: "AT"
                                street: "Example Avenue 99"
                                zipcode: 12345
                                cityTown: "Testville"
                            }
                        }
                        taxProcedureCreditNote: REVERSE_CHARGE
                    }
                ]
            ) {
                rtId
            }
        }
    }
}

Diese Abfrage erstellt ein Energiezähler-Objekt mit den angegebenen Daten. Das Ergebnisobjekt sieht in etwa so aus

{
  "data": {
    "runtime": {
      "energyCommunityCustomers": {
        "create": [
          {
            "rtId": "693c4cd3464d7d9e1396cf0d"
          }
        ]
      }
    }
  }
}

Create mit Variablen

Für die programmatische Verwendung wird empfohlen, GraphQL-Variablen zu nutzen:

mutation createCustomers($entities: [EnergyCommunityCustomerInput]!) {
    runtime {
        energyCommunityCustomers {
            create(entities: $entities) {
                rtId
            }
        }
    }
}

Variablen:

{
  "entities": [
    {
      "contact": {
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "nationalCode": "AT",
          "street": "Example Avenue 99",
          "zipcode": 12345,
          "cityTown": "Testville"
        }
      },
      "taxProcedureCreditNote": "REVERSE_CHARGE"
    }
  ]
}

Batch-Create

Mehrere Entitäten können in einer einzigen Anfrage erstellt werden, indem mehrere Einträge im entities-Array angegeben werden:

mutation {
    runtime {
        energyCommunityCustomers {
            create(
                entities: [
                    {
                        state: ACTIVE
                        contact:{
                            firstName: "John"
                            lastName: "Doe"
                            address: {
                                nationalCode: "AT"
                                street: "Example Avenue 99"
                                zipcode: 1010
                                cityTown: "Wien"
                            }
                        }
                        taxProcedureCreditNote: REVERSE_CHARGE
                    },
                    {
                        state: ACTIVE
                        contact:{
                            firstName: "Jane"
                            lastName: "Smith"
                            address: {
                                nationalCode: "DE"
                                street: "Sample Street 42"
                                zipcode: 10115
                                cityTown: "Berlin"
                            }
                        }
                        taxProcedureCreditNote: NO_TAX_PROCEDURE
                    },
                    {
                        state: ACTIVE
                        contact:{
                            firstName: "Max"
                            lastName: "Mustermann"
                            address: {
                                nationalCode: "AT"
                                street: "Musterstraße 12"
                                zipcode: 4020
                                cityTown: "Linz"
                            }
                        }
                        taxProcedureCreditNote: REVERSE_CHARGE
                    },
                    {
                        state: INACTIVE
                        contact:{
                            firstName: "Erika"
                            lastName: "Musterfrau"
                            address: {
                                nationalCode: "DE"
                                street: "Beispielweg 7"
                                zipcode: 80331
                                cityTown: "München"
                            }
                        }
                        taxProcedureCreditNote: NO_TAX_PROCEDURE
                    },
                    {
                        state: INACTIVE
                        contact:{
                            firstName: "Paul"
                            lastName: "Example"
                            address: {
                                nationalCode: "CH"
                                street: "Testgasse 5"
                                zipcode: 8001
                                cityTown: "Zürich"
                            }
                        }
                        taxProcedureCreditNote: REVERSE_CHARGE
                    }
                ]
            ) {
                rtId
            }
        }
    }
}

Dadurch werden zwei separate Entitäten in einem einzigen Mutationsaufruf erstellt. Das Ergebnis sieht in etwa so aus

{
  "data": {
    "runtime": {
      "energyCommunityCustomers": {
        "create": [
          {
            "rtId": "693c4cd3464d7d9e1396cf0d"
          },
          {
            "rtId": "693c4cd3464d7d9e1396cf0e"
          }
        ]
      }
    }
  }
}

Create mit Assoziationen

Wenn Sie Entitäten erstellen, die Assoziationen zu anderen Entitäten besitzen, können Sie die assoziierten Entitäten über ihre rtId und ckTypeId angeben.

mutation {
  runtime {
    energyCommunityOperatingFacilitys {
      create(
        entities: [
          {
            state: ACTIVE
            facilityType: HOUSEHOLD
            name: "Demo"
            address: {
              nationalCode: "AT"
              street: "Example Avenue 99"
              zipcode: 1010
              cityTown: "Wien"
            },
            parent:[{modOption:CREATE, target: {rtId:"5fc8fda18b2fc75f925e21ac", ckTypeId: "Basic/TreeNode"}}]
            customer: [{modOption:CREATE, target:{rtId:"693c4cd3464d7d9e1396cf0d", ckTypeId: "EnergyCommunity/Customer"}}]
          }
        ]
      ) {
        rtId
      }
    }
  }
}

Diese Mutation erstellt eine OperatingFacility-Entität und assoziiert sie mit einer bestehenden TreeNode- und Customer-Entität.

Das Ergebnis sieht in etwa so aus

{
  "data": {
    "runtime": {
      "energyCommunityOperatingFacilitys": {
        "create": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c"
          }
        ]
      }
    }
  }
}

---

Spezielle Scalar-Typen

TimeSpan-Attribute

TimeSpan-Attribute speichern Dauer-/Zeitintervallwerte. In GraphQL werden TimeSpan-Werte als Sekunden (Dezimalzahl) dargestellt.

Example Model

Die folgenden Beispiele verwenden den Typ OctoSdkDemo/MeteringPoint aus dem Construction Kit Octo.Sdk.Demo, der Folgendes enthält:

• dataTransmissionInterval - TimeSpan (Dauer in Sekunden)

Typisiertes Create mit TimeSpan

mutation {
  runtime {
    octoSdkDemoMeteringPoints {
      create(
        entities: [
          {
            name: "Main Building Meter"
            meteringPointNumber: "MP-2024-001"
            meterReading: 12500
            operatingStatus: OK
            # TimeSpan: 15 minutes = 900 seconds
            dataTransmissionInterval: 900
            # MeteringPoint requires a parent association
            parent: [{modOption: CREATE, target: {ckTypeId: "Basic/TreeNode", rtId: "65dc6d24cc529cdc46c84fcb"}}]
          }
        ]
      ) {
        rtId
        name
        meteringPointNumber
        dataTransmissionInterval
      }
    }
  }
}

Generisches Create mit TimeSpan

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "OctoSdkDemo/MeteringPoint"
            attributes: [
              { attributeName: "name", value: "Warehouse Meter" }
              { attributeName: "meteringPointNumber", value: "MP-2024-002" }
              { attributeName: "meterReading", value: 8750 }
              { attributeName: "operatingStatus", value: "OK" }
              # TimeSpan: 1 hour = 3600 seconds
              { attributeName: "dataTransmissionInterval", value: 3600 }
            ]
            # MeteringPoint requires a parent association
            associations: {
              roleName: "parent"
              targets: [{
                modOption: CREATE
                target: { ckTypeId: "Basic/TreeNode", rtId: "65dc6d24cc529cdc46c84fcb" }
              }]
            }
          }
        ]
      ) {
        rtId
        attributes(first: 10) {
          items {
            attributeName
            value
          }
        }
      }
    }
  }
}

Gängige TimeSpan-Werte

Duration	Seconds	Use Case
1 Minute	60	Hochfrequente Überwachung
5 Minuten	300	Standardüberwachung
15 Minuten	900	Energiezähler-Intervalle
1 Stunde	3600	Stündliche Berichte
1 Tag	86400	Tägliche Aggregation

---

Komplexe Attributtypen

OctoMesh unterstützt komplexe Attributtypen, die strukturierte Daten innerhalb von Entitäten ermöglichen. Dazu gehören die Typen Record, RecordArray, Binary und BinaryLinked.

Example Model

Die folgenden Beispiele verwenden den Typ OctoSdkDemo/Customer aus dem Construction Kit Octo.Sdk.Demo, der alle komplexen Attributtypen enthält:

• contact - Record (mit verschachteltem address-Record)
• bankAccount - Record
• customerStatus - Enum
• notes - RecordArray von CustomerNote
• profilePicture - Binary (Inline-Binärdaten)
• contractDocument - BinaryLinked (Verweis auf externe Datei)

Record-Attribute

Record-Attribute speichern strukturierte Daten als eingebettete Objekte. Sie werden im Construction Kit definiert und enthalten ihren eigenen Satz von Attributen. Records können verschachtelt werden (z. B. enthält Contact einen Address-Record).

Typisiertes Create mit Record

mutation {
  runtime {
    octoSdkDemoCustomers {
      create(
        entities: [
          {
            customerStatus: ACTIVE
            dateOfBirth: "1985-03-15T00:00:00Z"
            contact: {
              legalEntityType: NATURAL_PERSON
              firstName: "John"
              lastName: "Doe"
              email: "john.doe@example.com"
              address: {
                street: "123 Main Street"
                zipcode: 10115
                cityTown: "Berlin"
                nationalCode: "DE"
              }
            }
            bankAccount: {
              iban: "DE89370400440532013000"
              swiftCode: "COBADEFFXXX"
              accountHolder: "John Doe"
            }
          }
        ]
      ) {
        rtId
        customerStatus
        contact {
          firstName
          lastName
          email
          address {
            street
            cityTown
          }
        }
        bankAccount {
          iban
          accountHolder
        }
      }
    }
  }
}

Generisches Create mit Record

Bei Verwendung der generischen API werden Record-Werte als verschachtelte Objekte im Feld value übergeben:

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "OctoSdkDemo/Customer"
            attributes: [
              { attributeName: "customerStatus", value: "ACTIVE" }
              { attributeName: "dateOfBirth", value: "1985-03-15T00:00:00Z" }
              {
                attributeName: "contact"
                value: {
                  legalEntityType: "NATURAL_PERSON"
                  firstName: "John"
                  lastName: "Doe"
                  email: "john.doe@example.com"
                  address: {
                    street: "123 Main Street"
                    zipcode: 10115
                    cityTown: "Berlin"
                    nationalCode: "DE"
                  }
                }
              }
            ]
          }
        ]
      ) {
        rtId
        attributes(first: 10) {
          items {
            attributeName
            value
          }
        }
      }
    }
  }
}

Nested Records

Record-Attribute können weitere Record-Attribute enthalten (verschachtelte Records). Im obigen Beispiel enthält der contact-Record einen address-Record. Diese Verschachtelung funktioniert mit beidem:

• Inline-Literale: Verschachtelte Objekte direkt in der GraphQL-Mutation
• Variablen: Verschachtelte Objekte, die über JSON-Variablen übergeben werden

Die Struktur muss der Modelldefinition des Construction Kit entsprechen.

RecordArray-Attribute

RecordArray-Attribute speichern Arrays strukturierter Records, nützlich für Listen von Notizen, Historieneinträgen oder anderen wiederkehrenden Strukturen.

Typisiertes Create mit RecordArray

Der Typ OctoSdkDemo/Customer besitzt ein Attribut notes, das ein Array von CustomerNote-Records speichert:

mutation {
  runtime {
    octoSdkDemoCustomers {
      create(
        entities: [
          {
            customerStatus: ACTIVE
            contact: {
              legalEntityType: NATURAL_PERSON
              firstName: "Jane"
              lastName: "Smith"
              address: {
                street: "456 Oak Avenue"
                zipcode: 80331
                cityTown: "Munich"
                nationalCode: "DE"
              }
            }
            notes: [
              {
                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"
              }
              {
                date: "2024-02-01T09:00:00Z"
                text: "Onboarding completed successfully"
                author: "Support Team"
                category: "Onboarding"
              }
            ]
          }
        ]
      ) {
        rtId
        contact {
          firstName
          lastName
        }
        notes {
          date
          text
          author
          category
        }
      }
    }
  }
}

Generisches Create mit RecordArray

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "OctoSdkDemo/Customer"
            attributes: [
              { attributeName: "customerStatus", value: "ACTIVE" }
              {
                attributeName: "contact"
                value: {
                  legalEntityType: "NATURAL_PERSON"
                  firstName: "Jane"
                  lastName: "Smith"
                  address: {
                    street: "456 Oak Avenue"
                    zipcode: 80331
                    cityTown: "Munich"
                    nationalCode: "DE"
                  }
                }
              }
              {
                attributeName: "notes"
                value: [
                  {
                    date: "2024-01-15T10:30:00Z"
                    text: "Initial contact"
                    author: "Sales Team"
                    category: "Sales"
                  }
                  {
                    date: "2024-01-20T14:00:00Z"
                    text: "Contract signed"
                    author: "Account Manager"
                  }
                ]
              }
            ]
          }
        ]
      ) {
        rtId
        attributes(first: 10) {
          items {
            attributeName
            value
          }
        }
      }
    }
  }
}

Binary-Attribute

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

When to use Binary vs BinaryLinked

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

Binärdaten in GraphQL verstehen

Binärdaten werden in GraphQL als Array von Ganzzahlen (0-255) dargestellt. Beim Erstellen oder Aktualisieren von Entitäten übergeben Sie die Binärdaten als JSON-Array von Byte-Werten.

Typisiertes Create mit Binary

mutation {
  runtime {
    octoSdkDemoCustomers {
      create(
        entities: [
          {
            customerStatus: ACTIVE
            contact: {
              legalEntityType: NATURAL_PERSON
              firstName: "John"
              lastName: "Doe"
              address: {
                street: "123 Main Street"
                zipcode: 10115
                cityTown: "Berlin"
                nationalCode: "DE"
              }
            }
            # Binary attribute - profile picture (PNG header bytes as example)
            profilePicture: [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82]
          }
        ]
      ) {
        rtId
        contact {
          firstName
          lastName
        }
        profilePicture
      }
    }
  }
}

Generisches Create mit Binary

mutation {
  runtime {
    runtimeEntities {
      create(
        entities: [
          {
            ckTypeId: "OctoSdkDemo/Customer"
            attributes: [
              { attributeName: "customerStatus", value: "ACTIVE" }
              {
                attributeName: "contact"
                value: {
                  legalEntityType: "NATURAL_PERSON"
                  firstName: "John"
                  lastName: "Doe"
                  address: {
                    street: "123 Main Street"
                    zipcode: 10115
                    cityTown: "Berlin"
                    nationalCode: "DE"
                  }
                }
              }
              {
                attributeName: "profilePicture"
                value: [137, 80, 78, 71, 13, 10, 26, 10]
              }
            ]
          }
        ]
      ) {
        rtId
        attributes(first: 10) {
          items {
            attributeName
            value
          }
        }
      }
    }
  }
}

Arbeiten mit Binärdaten im Code

JavaScript/TypeScript:

// Convert a file to byte array
async function fileToByteArray(file) {
  const arrayBuffer = await file.arrayBuffer();
  return Array.from(new Uint8Array(arrayBuffer));
}

// Convert Base64 to byte array
function base64ToByteArray(base64) {
  const binaryString = atob(base64);
  return Array.from(binaryString, char => char.charCodeAt(0));
}

// Usage with GraphQL mutation
const file = document.getElementById('profilePictureInput').files[0];
const profilePictureBytes = await fileToByteArray(file);

await client.mutate({
  mutation: CREATE_CUSTOMER,
  variables: {
    entities: [{
      customerStatus: "ACTIVE",
      contact: { /* ... */ },
      profilePicture: profilePictureBytes
    }]
  }
});

C# / .NET:

// Convert file to byte array for GraphQL
byte[] profilePictureBytes = await File.ReadAllBytesAsync("profile.png");

// The SDK handles byte[] automatically
var customer = new CustomerInput
{
    CustomerStatus = CustomerStatus.Active,
    Contact = new ContactInput { /* ... */ },
    Thumbnail = profilePictureBytes
};

Binary-Attribute abfragen

Binärdaten werden als Array von Ganzzahlen zurückgegeben:

query {
  runtime {
    octoSdkDemoCustomers(first: 10) {
      items {
        rtId
        contact {
          firstName
          lastName
        }
        profilePicture
      }
    }
  }
}

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, 73, 72, 68, 82]
          }
        ]
      }
    }
  }
}

Antwort in JavaScript in ein nutzbares Format umwandeln:

// Convert byte array to Base64 for display
function byteArrayToBase64(bytes) {
  const binaryString = String.fromCharCode(...bytes);
  return btoa(binaryString);
}

// Display as image
const base64 = byteArrayToBase64(customer.profilePicture);
const imgSrc = `data:image/png;base64,${base64}`;

BinaryLinked-Attribute

BinaryLinked-Attribute speichern Verweise auf Binärdateien (Bilder, Dokumente usw.). Dateien können auf zwei Arten hochgeladen werden:

1. GraphQL Multipart Request – Für Datei-Uploads aus Browsern oder Clients (empfohlen für große Dateien)
2. Base64-Zeichenketten oder Byte-Arrays – Für die programmatische Verwendung, wenn Binärdaten bereits im Speicher vorliegen

Der Typ OctoSdkDemo/Customer besitzt ein Attribut contractDocument zum Speichern von Vertrags-PDFs.

Option 1: Dateien über GraphQL Multipart Request hochladen

Binärdateien werden mit der GraphQL Multipart Request Specification hochgeladen. Dies ermöglicht Datei-Uploads direkt innerhalb einer GraphQL-Mutation.

Beispiel mit curl:

curl -X POST "https://api.example.com/{tenantId}/graphql" \
  -H "Authorization: Bearer {token}" \
  -F 'operations={"query":"mutation($entities: [OctoSdkDemoCustomerInput!]!) { runtime { octoSdkDemoCustomers { create(entities: $entities) { rtId contractDocument { binaryId filename } } } } }","variables":{"entities":[{"customerStatus":"ACTIVE","contact":{"legalEntityType":"NATURAL_PERSON","firstName":"John","lastName":"Doe","address":{"street":"Main St","zipcode":10115,"cityTown":"Berlin","nationalCode":"DE"}},"contractDocument":null}]}}' \
  -F 'map={"0":["variables.entities.0.contractDocument"]}' \
  -F '0=@contract.pdf'

Die Multipart-Anfrage besteht aus drei Teilen:

1. operations – Die GraphQL-Abfrage/-Mutation mit Variablen (Datei-Variablen auf null gesetzt)
2. map – Ordnet Datei-Indizes den Variablenpfaden zu
3. 0, 1, … – Die eigentlichen Dateidaten

Beispiel mit JavaScript (Apollo Client mit apollo-upload-client):

import { createUploadLink } from 'apollo-upload-client';
import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  link: createUploadLink({ uri: 'https://api.example.com/{tenantId}/graphql' }),
  cache: new InMemoryCache()
});

const CREATE_CUSTOMER = gql`
  mutation CreateCustomer($entities: [OctoSdkDemoCustomerInput!]!) {
    runtime {
      octoSdkDemoCustomers {
        create(entities: $entities) {
          rtId
          contact {
            firstName
            lastName
          }
          contractDocument {
            binaryId
            filename
            contentType
            size
            downloadUri
          }
        }
      }
    }
  }
`;

// File from input element
const file = document.getElementById('contractFile').files[0];

await client.mutate({
  mutation: CREATE_CUSTOMER,
  variables: {
    entities: [{
      customerStatus: "ACTIVE",
      contact: {
        legalEntityType: "NATURAL_PERSON",
        firstName: "John",
        lastName: "Doe",
        address: {
          street: "123 Main Street",
          zipcode: 10115,
          cityTown: "Berlin",
          nationalCode: "DE"
        }
      },
      contractDocument: file  // Pass the File object directly
    }]
  }
});

Option 2: Base64-Zeichenketten oder Byte-Arrays verwenden

Für programmatische Anwendungsfälle, in denen Sie Binärdaten im Speicher haben (keine Datei), können Sie BinaryLinked-Daten übergeben als:

• Base64-kodierte Zeichenketten – Bei der Arbeit mit APIs oder kodierten Daten
• Byte-Arrays – Bei der Arbeit mit rohen Binärdaten im Code

TypeScript/JavaScript mit Base64:

const CREATE_CUSTOMER = gql`
  mutation CreateCustomer($entities: [OctoSdkDemoCustomerInput!]!) {
    runtime {
      octoSdkDemoCustomers {
        create(entities: $entities) {
          rtId
          contractDocument {
            binaryId
            filename
            downloadUri
          }
        }
      }
    }
  }
`;

// Binary data as Base64 string (e.g., from an API response)
const pdfBase64 = "JVBERi0xLjQKJeLjz9MKMyAwIG9i..."; // Base64-encoded PDF

await client.mutate({
  mutation: CREATE_CUSTOMER,
  variables: {
    entities: [{
      customerStatus: "ACTIVE",
      contact: { /* ... */ },
      contractDocument: pdfBase64  // Pass Base64 string directly
    }]
  }
});

C# / .NET mit Byte-Array:

// Read PDF into byte array
byte[] pdfBytes = await File.ReadAllBytesAsync("contract.pdf");

// Or from a stream
using var stream = new MemoryStream();
await someStream.CopyToAsync(stream);
byte[] pdfBytes = stream.ToArray();

// The SDK handles byte[] serialization automatically
var customer = new CustomerInput
{
    CustomerStatus = CustomerStatus.Active,
    Contact = new ContactInput { /* ... */ },
    ContractDocument = pdfBytes  // Pass byte array
};

Metadata Differences

Bei Verwendung von Base64/Byte-Arrays (Option 2) werden die Datei-Metadaten automatisch generiert:

• filename: {attributeName}.bin
• contentType: application/octet-stream

Für korrekte Metadaten (Dateiname, Content-Type) verwenden Sie den Multipart-Datei-Upload (Option 1).

Dateien über REST-API herunterladen

Binärdateien können über den REST-Endpunkt mit der binaryId aus der Abfrageantwort heruntergeladen werden:

GET /{tenantId}/v1/largeBinaries?largeBinaryId={binaryId}

Das Feld downloadUri in Abfragen enthält bereits die vollständige URL zur bequemen Nutzung.

BinaryLinked-Attribute abfragen

Wenn Sie Entitäten mit BinaryLinked-Attributen abfragen, erhalten Sie Metadaten und eine Download-URI:

query {
  runtime {
    octoSdkDemoCustomers(first: 10) {
      items {
        rtId
        contact {
          firstName
          lastName
        }
        contractDocument {
          binaryId
          filename
          contentType
          size
          downloadUri
        }
      }
    }
  }
}

Antwort:

{
  "data": {
    "runtime": {
      "octoSdkDemoCustomers": {
        "items": [
          {
            "rtId": "693c5b93464d7d9e1396cf1c",
            "contact": {
              "firstName": "John",
              "lastName": "Doe"
            },
            "contractDocument": {
              "binaryId": "693c5b93464d7d9e1396cf20",
              "filename": "contract-doe-2024.pdf",
              "contentType": "application/pdf",
              "size": 245678,
              "downloadUri": "https://api.example.com/tenant1/v1/largeBinaries?largeBinaryId=693c5b93464d7d9e1396cf20"
            }
          }
        ]
      }
    }
  }
}

Kombiniertes Beispiel mit allen komplexen Typen

Erstellen eines Kunden mit allen komplexen Attributtypen (Record, RecordArray, BinaryLinked):

mutation {
  runtime {
    octoSdkDemoCustomers {
      create(
        entities: [
          {
            customerStatus: ACTIVE
            dateOfBirth: "1980-06-15T00:00:00Z"
            phoneNumberMobile: "+49 170 1234567"
            phoneNumberLandLine: "+49 30 9876543"
            # Record attribute with nested Record
            contact: {
              legalEntityType: NATURAL_PERSON
              salutation: "Mr."
              firstName: "Max"
              lastName: "Mustermann"
              email: "max.mustermann@example.com"
              address: {
                street: "Musterstraße 42"
                zipcode: 10115
                cityTown: "Berlin"
                nationalCode: "DE"
              }
            }
            # Another Record attribute
            bankAccount: {
              iban: "DE89370400440532013000"
              swiftCode: "COBADEFFXXX"
              accountHolder: "Max Mustermann"
            }
            # RecordArray attribute
            notes: [
              {
                date: "2024-01-10T09:00:00Z"
                text: "Customer registered via web portal"
                author: "System"
                category: "Registration"
              }
              {
                date: "2024-01-12T11:30:00Z"
                text: "Identity verification completed"
                author: "Compliance Team"
                category: "Verification"
              }
              {
                date: "2024-01-15T14:00:00Z"
                text: "Contract signed and activated"
                author: "Sales Manager"
                category: "Contract"
              }
            ]
            # BinaryLinked attribute (uploaded via multipart request)
            # contractDocument: <file>
          }
        ]
      ) {
        rtId
        customerStatus
        dateOfBirth
        contact {
          firstName
          lastName
          email
          address {
            street
            cityTown
            nationalCode
          }
        }
        bankAccount {
          iban
          accountHolder
        }
        notes {
          date
          text
          author
          category
        }
        contractDocument {
          binaryId
          filename
          downloadUri
        }
      }
    }
  }
}