Zum Hauptinhalt springen

Ihr erster Tourfold-Datenfluss

Dieser Ablauf baut eine kleine, aber vollständige Integration rund um ein Anlagenregister auf. Sie definieren das Schema, legen einen Datensatz an, finden ihn über einen fachlichen Schlüssel, fragen ihn über beide API-Stile ab und beobachten optional die nächste Änderung über einen signierten Webhook.

Führen Sie die Schritte in einem Entwicklungs-Workspace aus: Die erste Schreiboperation legt eine echte Objektdefinition an.

Voraussetzungen​

Verwenden Sie einen OAuth-Client für Server-zu-Server-Zugriffe oder ein Benutzer-Token. Für den vollständigen Ablauf braucht der Aufrufer diese Grants:

TeilErforderliche Grants
Objektdefinition lesen und anlegenobjects:configuration:read, objects:configuration:create
Datensätze lesen, anlegen und ändernobjects:records:read, objects:records:create, objects:records:update
Optionaler Webhookwebhooks:create

Setzen Sie zwei Shell-Variablen. In einer echten Umgebung gehört das Token nicht in die Shell-Historie; eine interaktive Eingabe oder ein Secret Manager ist sicherer als der hier gezeigte Platzhalter.

export TOURFOLD_API="https://api.tourfold.com/api/v2"
export TOURFOLD_TOKEN="YOUR_ACCESS_TOKEN"

Falls Sie noch ein Zugriffstoken benötigen, beginnen Sie mit der Authentifizierung.

1. Vorhandenes Datenmodell ansehen​

Der Objektkatalog ist die gemeinsame Discovery-Oberfläche für REST und GraphQL. Er enthält Standardobjekte, Systemprojektionen und Definitionen Ihres Workspaces.

curl -fsS "$TOURFOLD_API/definitions/objects?size=100" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
| jq '.items[] | {id, slug}'

Ein Objekt bleibt als Metadaten sichtbar, auch wenn der Aufrufer seine Datensätze nicht lesen darf.

2. Ein Anlagenobjekt definieren​

Diese Definition besitzt einen eindeutigen fachlichen Schlüssel, einen Boolean mit Standardwert und eine kontrollierte Kategorie. Slugs sind die Feldnamen in Datensatz-JSON und im generierten GraphQL-Schema; lokalisierte Namen sind Beschriftungen für die Oberfläche.

curl -fsS -X POST "$TOURFOLD_API/objects" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "equipment",
"name": {
"en": {"singular": "Equipment item", "plural": "Equipment"},
"de": {"singular": "Anlage", "plural": "Anlagen"}
},
"display_template": "{{name}} ({{asset_tag}})",
"attributes": [
{
"slug": "name",
"type": "text",
"name": {"en": "Name", "de": "Name"},
"config": {"is_required": true, "max_length": 160}
},
{
"slug": "asset_tag",
"type": "text",
"name": {"en": "Asset tag", "de": "Anlagenkennzeichen"},
"config": {"is_required": true, "is_unique": true, "max_length": 40}
},
{
"slug": "category",
"type": "select",
"name": {"en": "Category", "de": "Kategorie"},
"options": [
{"value": "hvac", "title": "HVAC"},
{"value": "elevator", "title": "Elevator"},
{"value": "lighting", "title": "Lighting"}
]
},
{
"slug": "operational",
"type": "boolean",
"name": {"en": "Operational", "de": "Betriebsbereit"},
"config": {"default": true}
}
]
}' | jq '{id, slug, lock_version, attributes: [.attributes[] | {id, slug, type}]}'

Tourfold vergibt unveränderliche UUIDs für das Objekt, seine Attribute und die Select-Optionen. Speichern Sie diese IDs, wenn Ihre Integration Schemaänderungen verwaltet; damit unterscheiden Sie eine Umbenennung von Löschen und Neuanlegen. lock_version schützt spätere Schema-Schreibvorgänge vor verlorenen Änderungen.

Wenn equipment bereits existiert, löschen Sie es nicht blind. Prüfen Sie die Definition und verwenden Sie entweder einen anderen Slug oder den Leitfaden zur Schemaentwicklung.

3. Einen Datensatz anlegen​

Datensatzwerte werden über die gerade definierten Attribut-Slugs adressiert. Fehlt ein Feld, setzt Tourfold gegebenenfalls dessen Standardwert ein.

RECORD_ID=$(
curl -fsS -X POST "$TOURFOLD_API/objects/equipment/records" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"category": "hvac"
}
}' | tee /dev/stderr | jq -r '.id'
)

Die Antwort führt Systemmetadaten auf oberster Ebene und typisierte Werte unter data. Für die Select-Option kommt die kanonische UUID zurück, obwohl der Schreibzugriff den lesbaren Wert hvac verwendet hat.

4. Über den fachlichen Schlüssel lesen​

Da asset_tag eindeutig ist, kann das Feld einen Datensatz adressieren, ohne dass seine UUID bereits bekannt ist:

curl -fsS \
"$TOURFOLD_API/objects/equipment/records/by/asset_tag?attribute_value=AFS-RTU-17" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
| jq

Dieser Endpoint eignet sich für einen einzelnen Treffer. Mengen fragen Sie über den strukturierten Query-Endpoint ab:

curl -fsS -X POST "$TOURFOLD_API/objects/equipment/records/query" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"operational": {"eq": true},
"category": {"in": ["hvac"]}
},
"sort": ["name:asc"],
"page": 0,
"size": 20
}' | jq '.items'

5. Dasselbe Modell mit GraphQL abfragen​

GraphQL ist eine Leseoberfläche, die aus dem Objektkatalog dieses Workspaces erzeugt wird. Laden Sie das tatsächliche Schema herunter, bevor Sie Abfragen schreiben oder Code generieren:

curl -fsS "$TOURFOLD_API/graphql/schema" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-o tourfold-schema.graphql

Der Root equipment und seine Felder existieren jetzt aufgrund der Objektdefinition:

curl -fsS -X POST "$TOURFOLD_API/graphql" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Accept: application/graphql-response+json" \
-H "Content-Type: application/json" \
-d '{
"query": "query EquipmentForSync { equipment(where: { asset_tag: { _eq: \"AFS-RTU-17\" } }, first: 1) { edges { node { id name asset_tag category operational lock_version } } } }",
"operationName": "EquipmentForSync"
}' | jq

REST und GraphQL verwenden absichtlich dieselben Slugs, schreiben Operatoren aber leicht unterschiedlich: REST nutzt eq, GraphQL _eq. Schreiben Sie über REST; GraphQL eignet sich für verbundene Lesezugriffe, die sonst mehrere Aufrufe benötigen würden.

6. Optional: die nächste Änderung beobachten​

Legen Sie einen Webhook-Endpoint erst an, wenn sein öffentlicher HTTPS-Empfänger Signaturen nach Standard Webhooks prüft. Das Endpoint-Secret wird einmalig zurückgegeben; speichern Sie es sofort.

curl -fsS -X POST "$TOURFOLD_API/webhook-endpoints" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Equipment development receiver",
"endpoint_url": "https://integration.example.invalid/tourfold/webhooks",
"signature_scheme": "HMAC_SHA256",
"enabled": true,
"retry": true,
"subscriptions": ["object.equipment.*"]
}' | jq

Ändern Sie danach den Datensatz. Ein ausgelassener Schlüssel bleibt unverändert, der gelieferte Wert wird zusammengeführt. Wenn Ihr Prozess Compare-and-set benötigt, können Sie lock_version mitsenden.

curl -fsS -X PATCH "$TOURFOLD_API/objects/equipment/records/$RECORD_ID" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{"data":{"operational":false}}' | jq

Der Empfänger erhält object.equipment.updated. Entdoppeln Sie über webhook-id, prüfen Sie die Signatur über die unveränderten Request-Bytes, reihen Sie die Arbeit dauerhaft ein und antworten Sie innerhalb von fünf Sekunden mit 2xx. Einzelheiten stehen im vollständigen Webhook-Leitfaden für den Produktivbetrieb.

Vom Beispiel zur produktiven Integration​

Vor dem Produktivbetrieb:

  • unveränderliche IDs zusammen mit lesbaren Slugs speichern;
  • das GraphQL-Schema samt ETag cachen und Clients bei geänderter Revision neu generieren;
  • lock_version verwenden, wenn mehrere Prozesse dasselbe Schema oder denselben Datensatz ändern;
  • Batch-Erstellung als atomar und Webhook-Zustellung als At-least-once behandeln;
  • bei RFC-9457-Fehlern auf type, nie auf menschenlesbaren Text verzweigen; und
  • Schemaänderungen in einem getrennten Workspace testen, bevor sie auf Produktivdaten wirken.

Als Nächstes folgen die Leitfäden zu Schemaentwicklung und Synchronisierung.