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 Seite | Rückseite | Relation |
|---|---|---|
| Einfach | Einfach | Eins-zu-eins |
| Einfach | Mehrfach | Viele Wartungsanfragen können auf eine Anlage verweisen |
| Mehrfach | Einfach | Eine Quelle kann viele Ziele verknüpfen; jedes Ziel akzeptiert eine Quelle |
| Mehrfach | Mehrfach | Viele-zu-viele |
| Einfach | Kein reverse | Viele Quellen können auf dasselbe Ziel verweisen |
| Mehrfach | Kein reverse | Viele-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:
- Das Attribut mit
config.reversebesitzt das Relationsschema. - Tourfold materialisiert das benannte Rückseitenattribut auf dem Zielobjekt.
- Die Rückseite trägt
is_system_managed: trueundis_readonly: trueund verweist zum Besitzerobjekt zurück. - 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.
nullleert eine To-one-Beziehung,[]eine To-many-Beziehung, sofernis_requireddies erlaubt.- Bestehende Clients dürfen weiterhin Arrays für To-one senden; höchstens ein Ziel ist erlaubt.
Auch
[]für To-one undnullfü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 }
}
}
}
| Benutzer | Lesen | Neue Verknüpfung |
|---|---|---|
| Aktiv | Name, ohne status | Akzeptiert |
| Deaktiviert | Name mit status: "inactive" | Akzeptiert, damit historische Datensätze frühere Mitarbeitende behalten können |
| Gelöscht | Name mit status: "deleted"; ohne display_name, wenn die Löschung die Person anonymisiert hat | 422 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.reversedes Besitzers umbenennen oder neu beschriften. - Kardinalität über die Besitzerdeklaration ändern.
- Beidseitige Relation löschen, indem das Besitzerattribut gelöscht oder beim Bulk-
PUTdes 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
PUTdes 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.