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:
| Teil | Erforderliche Grants |
|---|---|
| Objektdefinition lesen und anlegen | objects:configuration:read, objects:configuration:create |
| Datensätze lesen, anlegen und ändern | objects:records:read, objects:records:create, objects:records:update |
| Optionaler Webhook | webhooks: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
ETagcachen und Clients bei geänderter Revision neu generieren; lock_versionverwenden, 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.