Zum Hauptinhalt springen

Relationen

Ein relationship-Attribut verbindet Datensätze eines Objekts mit Datensätzen von genau einem Zielobjekt. Relationen sind nicht polymorph: Die Objektdefinition verwendet ein einzelnes config.target, das als Objekt-Slug oder UUID angegeben wird.

Relation deklarieren​

Dieses Attribut gehört zu maintenance_request und verweist auf equipment:

{
"slug": "equipment",
"type": "relationship",
"name": {
"en": "Equipment",
"de": "Anlage"
},
"config": {
"target": "equipment",
"is_multiselect": false,
"is_required": true,
"reverse": {
"slug": "maintenance_requests",
"name": {
"en": "Maintenance requests",
"de": "Wartungsanfragen"
},
"is_multiselect": true
}
}
}

Das Attribut kann direkt in createObject oder schrittweise mit addAttribute angelegt werden.

Beim Schreiben akzeptiert target den Slug oder die unveränderliche UUID des Zielobjekts. Beim Lesen wird die Referenz aufgelöst:

{
"target": {
"id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
"slug": "equipment"
},
"is_multiselect": false,
"is_required": true,
"reverse": {
"slug": "maintenance_requests",
"name": { "en": "Maintenance requests", "de": "Wartungsanfragen" },
"is_multiselect": true
}
}

Kardinalität​

Beide Seiten legen unabhängig fest, ob sie mehrere Verknüpfungen zulassen:

Deklarierende SeiteRückseiteRelation
EinfachEinfachEins-zu-eins
EinfachMehrfachViele Wartungsanfragen können auf eine Anlage verweisen
MehrfachEinfachEine Quelle kann viele Ziele verknüpfen; jedes Ziel akzeptiert eine Quelle
MehrfachMehrfachViele-zu-viele
EinfachKein reverseViele Quellen können auf dasselbe Ziel verweisen
MehrfachKein reverseViele-zu-viele

Ohne reverse-Deklaration begrenzt die Zielseite nicht, wie viele Datensätze auf dasselbe Ziel verweisen. Eine einseitige Begrenzung auf der Zielseite (eins-zu-eins oder eine Quelle je Ziel) erfordert eine deklarierte Rückseite mit is_multiselect: false.

Ein To-one-Feld akzeptiert eine UUID/Referenz oder null, ein To-many-Feld ein Array. Bestehende To-one-Arrayeingaben bleiben mit höchstens einem Eintrag gültig. is_required: true auf dem deklarierenden Attribut verlangt mindestens eine Verknüpfung; die Rückseitendeklaration besitzt kein eigenes Required-Flag. Kardinalität und Required-Regel des Besitzers werden bei jeder Änderung einer Kante über die Besitzerseite durchgesetzt.

Ein schreibbarer Besitzer, eine schreibgeschützte Projektion​

Eine beidseitige Relation besitzt bewusst asymmetrischen Schemabesitz:

  1. Das Attribut mit config.reverse besitzt das Relationsschema.
  2. Tourfold materialisiert das benannte Rückseitenattribut auf dem Zielobjekt.
  3. Die Rückseite trägt is_system_managed: true und is_readonly: true und verweist zum Besitzerobjekt zurück.
  4. Die Rückseite enthält keine weitere reverse-Deklaration.

Das Besitzerattribut ist die einzige Schreibautorität für die Kante. Eine Änderung von maintenance_request.equipment ändert die Relation; ein Schreibversuch auf equipment.maintenance_requests liefert 422 relationship-reverse-managed. Die Rückseite bleibt für Datensatzabrufe, die Paginierung verbundener Datensätze, GraphQL-Traversierung, Filterung und unterstützte Sortierung verfügbar.

Dadurch kann ein Ersetzungsdokument auf der Zielseite keine von einem anderen Objekt deklarierten Kanten löschen, und wiederholte Schreibvorgänge bleiben deterministisch.

Verknüpfungen schreiben​

Schreiben Sie bei To-one-Beziehungen eine einzelne Datensatz-UUID oder ein Referenzobjekt. Bei To-many-Beziehungen verwenden Sie Arrays dieser Werte. Die beiden To-one-Formen sind gleichwertig:

{
"data": {
"equipment": "6f3d2a10-0000-4000-8000-000000000117"
}
}
{
"data": {
"equipment": {
"record_id": "6f3d2a10-0000-4000-8000-000000000117"
}
}
}

Das konfigurierte Zielobjekt ist implizit. Enthält ein zurückgeschriebenes Objekt zusätzlich object und display_name, validiert der Server die Datensatz-ID gegen config.target und ignoriert die Anzeigedaten als Eingabe.

Für PATCH auf dem Objekt, dem das Relationsattribut gehört, gilt:

  • Ein To-one-Wert ersetzt die einzelne Verknüpfung; ein To-many-Array ersetzt die vollständige Verknüpfungsmenge.
  • null leert eine To-one-Beziehung, [] eine To-many-Beziehung, sofern is_required dies erlaubt.
  • Bestehende Clients dürfen weiterhin Arrays für To-one senden; höchstens ein Ziel ist erlaubt. Auch [] für To-one und null für To-many bleiben zum Leeren gültig.
  • Ein ausgelassener Relationsschlüssel erhält die aktuellen Verknüpfungen.

Beim atomaren Batch-Anlegen kann {"ref": "anfrageinterner-schlüssel"} auf einen Datensatz im selben Request verweisen.

Das Schreiben eines Relationswerts (beim Anlegen, Batch-Anlegen oder PATCH, einschließlich des Leerens mit null oder []) setzt neben write-Zugriff auf die besitzende Definition auch read-Zugriff auf die Zieldefinition voraus. Fehlt der Lesezugriff auf die Zieldefinition, antwortet der Schreibvorgang mit 403 access-denied; lassen Sie den Relationsschlüssel bei PATCH weg, um andere Felder zu ändern und bestehende Verknüpfungen unverändert zu lassen.

Das verwaltete Rückseitenattribut ist schreibgeschützt. Um eine Kante in einem zielseitigen Ablauf hinzuzufügen oder zu entfernen, ändern Sie das deklarierende Attribut des entsprechenden Besitzerdatensatzes.

Verknüpfungen lesen​

Eingebettete Relationswerte liefern aufgelöste kompakte Referenzen:

{
"data": {
"equipment": {
"record_id": "6f3d2a10-0000-4000-8000-000000000117",
"object": "equipment",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)"
}
}
}

To-one-Beziehungen liefern ein einzelnes Referenzobjekt oder ausdrücklich null, wenn keine Verknüpfung besteht. Nicht lesbare Beziehungen werden weggelassen. To-many-Beziehungen verwenden {items, page} mit höchstens 50 kompakten Datensatzansichten und der vollständigen lesbaren Gesamtzahl. Der folgende Ausschnitt zeigt eine vollständige Sammlung mit einem Eintrag. Größere Sammlungen laden Sie über den paginierten Related-Endpoint. Schreibzugriffe verwenden weiterhin Arrays von IDs oder Referenzen; senden Sie den Leseumschlag nicht als Schreibwert zurück.

{
"data": {
"maintenance_requests": {
"items": [
{
"record_id": "7a4e2b10-0000-4000-8000-000000000201",
"object": "maintenance_request",
"display_name": "Temperatur zu hoch"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests?page=0&size=20

Seiten verknüpfter Datensätze liefern {items, page}. Jeder Eintrag umschließt die kanonische Antwort seines Eigentümers:

{
"kind": "vehicle",
"definition_id": "11111111-9999-4444-8888-111111111111",
"record": {
"id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
"definition_id": "11111111-9999-4444-8888-111111111111",
"natural_id": "BIKE-7",
"name": "Lastenrad 7",
"display_name": "Lastenrad 7",
"is_active": true,
"capacity": 0,
"seats_total": 1,
"created_at": "2023-02-14T10:00:00Z",
"updated_at": "2023-02-14T10:00:00Z",
"lock_version": 0,
"data": {"battery_wh": 750}
}
}

kind: "object" enthält stattdessen den kanonischen Objektdatensatz. Das registrierte native Ziel device verwendet kind: "device" und die kanonische Geräteantwort in record; für seine Referenzen, Seiten verknüpfter Datensätze und Erweiterungen ist devices:read erforderlich. Geräte werden weiterhin über /api/v2/devices angelegt und geändert; Routen für Objektdatensätze akzeptieren nie Geräteidentitäten. Fahrzeugziele umfassen mehrere Definitionen; der Umschlag nennt die tatsächliche Definition jedes Datensatzes. Fahrzeugquellen bieten dieselbe Sammlung unter GET /vehicles/{definition_ref}/records/{vehicle_id}/related/{attribute_ref}. Es gelten die Leseberechtigungen von Quelle und Ziel; wird das Ziel verweigert, antwortet die API mit 403, bevor eine Anzahl offengelegt wird. Eingebettete Vorschauen lassen nicht lesbare Zielreferenzen samt ihren Paginierungsmetadaten weg.

Strukturierte Abfragen verknüpfter Datensätze unterstützen derzeit Objektziele. Fahrzeug- und Geräteziele verwenden das paginierte GET; eine Abfrage verknüpfter Datensätze gegen eines dieser Ziele liefert 422 unsupported-relationship-query.

Strukturierte REST-Abfragen können durch die Relation filtern:

{
"filter": {
"maintenance_requests": {
"priority": { "eq": "urgent" }
}
}
}

Filter können über weitere Relationen bis zur gemeinsamen Grenze von vier Filterebenen fortgesetzt werden. Skalare Sortierung unterstützt genau einen Sprung über eine To-one-Relation, zum Beispiel "sort": ["manufacturer.name:asc"]; Sortierung über To-many-Relationen oder verkettete Relationen wird abgelehnt.

Um nur die verknüpfte Zielsammlung zu filtern und zu sortieren, verwenden Sie:

POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query

Der Request-Body hat dieselben Felder filter, sort, page und size wie die Datensatzabfrage auf oberster Ebene.

GraphQL kann dieselbe Kante durchlaufen und Felder beider Objekte in einer Anfrage auswählen. Siehe Abfragen verknüpfter Datensätze.

Workspace-Benutzer als Ziele​

Verwenden Sie das System-Objekt user als config.target, um Personen an einem Datensatz zu erfassen, etwa die verantwortliche Person eines Projekts und sein Team:

[
{ "slug": "owner", "type": "relationship", "name": { "en": "Owner", "de": "Verantwortlich" },
"config": { "target": "user" } },
{ "slug": "team", "type": "relationship", "name": { "en": "Team", "de": "Team" },
"config": { "target": "user", "is_multiselect": true } }
]

Benutzer-IDs werden genau wie andere Relationswerte geschrieben. Lesende Aufrufe liefern dieselbe kompakte Referenz, mit einem optionalen status für Personen, die keine aktuellen Mitglieder mehr sind:

{
"data": {
"owner": { "record_id": "5f000000-0000-4000-8000-000000000002", "object": "user", "display_name": "Ada Lovelace" },
"team": {
"items": [
{ "record_id": "5f000000-0000-4000-8000-000000000003", "object": "user", "display_name": "Grace Hopper", "status": "inactive" },
{ "record_id": "5f000000-0000-4000-8000-000000000004", "object": "user", "display_name": "Margaret Hamilton", "status": "deleted" }
],
"page": { "size": 50, "total_elements": 2, "total_pages": 1, "number": 0 }
}
}
}
BenutzerLesenNeue Verknüpfung
AktivName, ohne statusAkzeptiert
DeaktiviertName mit status: "inactive"Akzeptiert, damit historische Datensätze frühere Mitarbeitende behalten können
GelöschtName mit status: "deleted"; ohne display_name, wenn die Löschung die Person anonymisiert hat422 object-not-found
Servicekonto—422 object-not-found

Verknüpfungen, die ein Datensatz bereits hält, bleiben gültig. Ein unverändert zurückgesendetes Team mit einem gelöschten oder deaktivierten Mitglied wird daher akzeptiert, sodass Clients den Rest der Menge bearbeiten können.

Um Personen an einem Datensatz zu sehen, ist users:read nicht nötig. Wer den Datensatz lesen darf, sieht die Referenzen und kann Benutzer verknüpfen; Kandidaten liefert listUserDirectoryEntries (GET /api/v2/users/directory), nur mit Namen und Status. Ohne users:read können verschachtelte Filter und Sortierungen über ein Benutzerfeld nur id, firstname, lastname, active und deleted_at verwenden; andere Benutzerfelder liefern 422 unknown-filter-attribute. Vollständige Benutzerdatensätze — include-Erweiterung, Seiten verknüpfter Datensätze und Kontaktfelder — erfordern weiterhin users:read. Ohne diese Berechtigung lässt include die kompakte Referenz unerweitert, und Seiten verknüpfter Datensätze liefern 403 access-denied.

Nach dem aufrufenden Benutzer filtern Sie mit dem id-Alias me, der für jede Anfrage einzeln aufgelöst wird. Er wird von eq, ne und in (GraphQL _eq, _ne, _in) auf der id des Objekts user akzeptiert, sodass eine geteilte gespeicherte Ansicht wie „Meine Projekte“ jeder Person ihre eigenen Datensätze zeigt:

{
"filter": { "or": [ { "owner": { "id": { "eq": "me" } } }, { "team": { "id": { "eq": "me" } } } ] },
"sort": ["owner.lastname:asc", "owner.firstname:asc"]
}

Ein Aufrufer, der kein Benutzer ist, etwa ein Geräte-Token, trifft mit me keinen Benutzer. Relationen zu user können kein reverse deklarieren (422 relationship-reverse-unsupported); das System-Schema für Benutzer bleibt unverändert. Datensatz-Webhooks übermitteln den geschriebenen Relationswert unaufgelöst, wie bei jeder Relation.

Relationsschema ändern​

Strukturelle Änderungen erfolgen ausschließlich über das besitzende Attribut:

  • Rückseite über config.reverse des Besitzers umbenennen oder neu beschriften.
  • Kardinalität über die Besitzerdeklaration ändern.
  • Beidseitige Relation löschen, indem das Besitzerattribut gelöscht oder beim Bulk-PUT des Besitzers ausgelassen wird.

Die Rückseite kann ihr verwaltetes Attribut nicht direkt ändern oder löschen. Ein solcher Request liefert 422 relationship-reverse-managed mit der Identität des Besitzers.

Warum PUT auf der Rückseite die Relation nicht löscht​

PUT /definitions/objects/{definition_ref} ersetzt nur Attribute, die dem Zielobjekt selbst gehören. Eine verwaltete Rückseite ist die Projektion eines fremden Schemas. Daher gilt:

  • Wird die Rückseite beim PUT des Zielobjekts ausgelassen, bleibt sie erhalten.
  • Wird sie in das Ersetzungsdokument des Zielobjekts aufgenommen, liefert die API 422.

Andernfalls könnte das erneute Senden eines unveränderten Zielobjektdokuments unerwartet eine Relation löschen, die von einem anderen Objekt deklariert wurde. Diese Grenze macht deklaratives PUT auf beiden Seiten sicher und wiederholbar.

Löschverhalten​

  • Das Löschen eines verknüpften Datensatzes entfernt seine Relationskanten; andere Datensätze bleiben erhalten.
  • Das Löschen des besitzenden Relationsattributs entfernt Relation und verwaltete Rückseite.
  • Das Löschen des Besitzerobjekts entfernt dessen Relationsdefinitionen, die verwalteten Rückseiten auf Zielobjekten und die gespeicherten Kanten. Zielobjekte und deren Datensätze bleiben erhalten.

Destruktive Schemaänderungen sollten bewusst eingesetzt werden: Das Entfernen eines besitzenden Relationsattributs entfernt alle für diese Relation gespeicherten Verknüpfungen.

Konflikte und Validierung​

Der Rückseiten-Slug muss im Attributnamensraum des Zielobjekts frei sein. Eine Kollision mit einem eigenen Zielattribut, einer anderen Relation oder einer anderen verwalteten Rückseite liefert 422 relationship-reverse-slug-conflict mit einem Pointer auf den Rückseiten-Slug.

Ein unbekanntes Ziel, ein Datensatz des falschen Objekts, eine Kardinalitätsverletzung oder das Leeren einer erforderlichen Relation liefert ebenfalls 422 mit feldgenauem Pointer. Siehe Fehler.

Endpoint-Referenz​