Datenspeicher API

ENTWURF — Nur für interne Entwicklerteams

Diese API-Referenz ist für interne Entwicklerteams bestimmt.

Übersicht

Was es ist: Die Datenspeicher-API bietet direkten Zugriff auf die Entitäts- und Edge-Speicherschicht von Hydden. Sie unterstützt das Abrufen von Sammlungsmetadaten, die Abfrage von Entitäten mit Filterung und Verlauf, das Erstellen/Aktualisieren/Löschen von Entitäten und Edges sowie die Verwaltung der Datenspeicher-Modulkonfiguration. Für Backup-/Wiederherstellungsoperationen siehe die Backup & Wiederherstellung API.

Quelle: src/datastore/rest/rest.go

Basispfad

/internal/v1/datastore

Authentifizierung

Alle Endpunkte erfordern JWT-Cookie- oder API-Token-Authentifizierung.

Endpunkte

Methode	Pfad	Beschreibung
GET	/internal/v1/datastore/info	Sammlungsspeicher-Informationen abrufen
GET	/internal/v1/datastore/shard/info	Shard-Replikationsinformationen abrufen
POST	/internal/v1/datastore/fetch	Entitäten mit Filterung und Transformation abrufen
GET	/internal/v1/datastore/entity/:target/:id	Eine einzelne Entität abrufen
PUT	/internal/v1/datastore/entity/:target/:id	Eine Entität erstellen oder aktualisieren
DELETE	/internal/v1/datastore/entity/:target/:id	Eine Entität löschen
PUT	/internal/v1/datastore/edge/:target/:from/:to	Einen Edge (Beziehung) erstellen oder aktualisieren
GET	/internal/v1/datastore/module/config	Datenspeicher-Modulkonfiguration abrufen
POST	/internal/v1/datastore/module/config	Datenspeicher-Modulkonfiguration aktualisieren

---

GET /internal/v1/datastore/info

Informationen über Sammlungsdatenspeicher abrufen, einschließlich Ansichtszeiten, Entitätsanzahlen und Replikationsknoten-Details.

Anfrage:

GET /internal/v1/datastore/info
Authorization: Bearer <token>

Antwort (200):

{
  "viewTime": 1707700800000,
  "maxTime": 1707700800000,
  "stores": [
    {
      "id": "ds-uuid",
      "viewTime": 1707700800000,
      "count": 4521,
      "nodes": [
        { "id": "node-1", "name": "Primary", "cloud": false, "online": true, "count": 4521 }
      ],
      "tombstoned": false,
      "name": "Corporate AD",
      "platform": "Active Directory",
      "version": 42
    }
  ],
  "historical": false,
  "node": "node-1",
  "cached": false,
  "version": 42
}

Antwortfelder (CollectionInfo):

Feld	Typ	Beschreibung
viewTime	int64	Aktueller Ansichtszeitstempel (ms)
maxTime	int64	Maximal verfügbarer Zeitstempel
stores	array	Sammlungsspeicher-Einträge
stores[].id	string	Datenquellen-ID
stores[].count	int64	Anzahl der Entitäten in diesem Speicher
stores[].name	string	Anzeigename der Datenquelle
stores[].platform	string	Plattformtyp (Active Directory, Azure AD usw.)
stores[].nodes	array	Replikationsknoten, die diesen Speicher halten
stores[].tombstoned	bool	Ob der Speicher soft-gelöscht ist
historical	bool	Ob historische Daten angezeigt werden
node	string	Antwortende Knoten-ID
cached	bool	Ob die Antwort aus dem Cache stammt

---

GET /internal/v1/datastore/shard/info

Shard-Verteilungs- und Replikationsinformationen über alle Knoten abrufen.

Anfrage:

GET /internal/v1/datastore/shard/info
Authorization: Bearer <token>

Antwort (200):

{
  "replicas": 2,
  "stores": 12,
  "total": 45230,
  "nodes": [
    {
      "id": "node-1",
      "name": "Primary",
      "cloud": false,
      "online": true,
      "count": 45230,
      "stores": [],
      "version": 42
    }
  ],
  "node": "node-1",
  "cached": false
}

Antwortfelder (ReplicationInfo):

Feld	Typ	Beschreibung
replicas	int64	Konfigurierter Replikationsfaktor
stores	int64	Gesamtanzahl der Sammlungsspeicher
total	int64	Gesamtanzahl der Entitäten über alle Speicher
nodes	array	Replikationsknoten mit Status und Entitätsanzahlen
nodes[].online	bool	Ob der Knoten derzeit erreichbar ist
nodes[].cloud	bool	Ob es sich um einen Cloud-Knoten handelt

---

POST /internal/v1/datastore/fetch

Entitäten aus einem Sammlungsspeicher mit optionaler Filterung und Transformation abrufen. Ergebnisse werden als JSON-Array gestreamt.

Anfrage:

POST /internal/v1/datastore/fetch
Content-Type: application/json
Authorization: Bearer <token>

{
  "dataSourceId": "ds-uuid",
  "entity": {
    "entityType": "identity.user",
    "time": 1707700800000
  }
}

Abfrageparameter:

Parameter	Typ	Beschreibung
limit	int	Maximale Anzahl zurückzugebender Entitäten
filter	string	Filterausdruck, der auf Entitäten angewendet wird
transform	string	Transformationsfunktion, die auf Ergebnisse angewendet wird

Antwort (200): Streaming-JSON-Array von Entitäten (Chunked-Transfer-Encoding).

[
  {
    "uniqueId": "acct-uuid-1",
    "entityType": "identity.user",
    "displayName": "John Doe",
    "email": "john.doe@company.com"
  }
]

---

GET /internal/v1/datastore/entity/:target/:id

Eine einzelne Entität anhand der Datenquellen-ID und Entitäts-ID abrufen, mit optionalem Verlauf.

Anfrage:

GET /internal/v1/datastore/entity/:target/:id
Authorization: Bearer <token>

Pfadparameter:

Parameter	Beschreibung
target	Datenquellen-ID
id	Entitäts-ID (Base64-kodiert)

Abfrageparameter:

Parameter	Typ	Beschreibung
history	bool	Entitäts-Änderungsverlauf einschließen (Standard: false)
layer	int[]	Bestimmte Datenschichten zum Abrufen (wiederholbar)

Antwort (200):

{
  "id": "acct-uuid",
  "dataSourceId": "ds-uuid",
  "type": "identity.user",
  "entity": {
    "displayName": "John Doe",
    "email": "john.doe@company.com",
    "upn": "jdoe@corp.local"
  },
  "time": 1707700800000,
  "tombstoned": false,
  "version": 5,
  "storeVersion": 42,
  "layers": [1, 2],
  "history": [
    {
      "time": 1707614400000,
      "tombstoned": false,
      "entity": {},
      "layers": [1]
    }
  ]
}

Antwortfelder (TargetEntity):

Feld	Typ	Beschreibung
id	string	Eindeutige Entitäts-ID
dataSourceId	string	Datenquellen-ID
type	string	Entitätstyp-Identifikator
entity	object	Deserialisierte Entitätsdaten
time	int64	Zeitstempel der letzten Änderung (ms)
tombstoned	bool	Ob die Entität soft-gelöscht ist
version	uint64	Versionsnummer der Entität
storeVersion	uint64	Version des Sammlungsspeichers
layers	int64[]	Vorhandene Datenschichten für diese Entität
history	array	Historische Versionen (bei ?history=true)

---

PUT /internal/v1/datastore/entity/:target/:id

Eine Entität im Datenspeicher erstellen oder aktualisieren.

Anfrage:

PUT /internal/v1/datastore/entity/:target/:id?type=identity.user
Content-Type: application/json
Authorization: Bearer <token>

Pfadparameter:

Parameter	Beschreibung
target	Datenquellen-ID
id	Entitäts-ID

Abfrageparameter:

Parameter	Typ	Erforderlich	Beschreibung
type	string	Ja	Entitätstyp (z. B. identity.user, identity.group)

Anfragekörper: JSON-Entität, die dem Protobuf-Schema für den angegebenen Typ entspricht.

{
  "displayName": "John Doe",
  "email": "john.doe@company.com"
}

Antwort (200): JSON-Echo der gespeicherten Entität.

---

DELETE /internal/v1/datastore/entity/:target/:id

Eine Entität aus dem Datenspeicher löschen (erstellt einen Tombstone-Marker).

Anfrage:

DELETE /internal/v1/datastore/entity/:target/:id
Authorization: Bearer <token>

Antwort (200): Leere Antwort bei Erfolg.

---

PUT /internal/v1/datastore/edge/:target/:from/:to

Einen Beziehungs-Edge zwischen zwei Entitäten erstellen oder aktualisieren.

Anfrage:

PUT /internal/v1/datastore/edge/:target/:from/:to?type=edge.identity.manager
Content-Type: application/json
Authorization: Bearer <token>

Pfadparameter:

Parameter	Beschreibung
target	Datenquellen-ID
from	Quell-Entitäts-ID
to	Ziel-Entitäts-ID

Abfrageparameter:

Parameter	Typ	Erforderlich	Beschreibung
type	string	Ja	Edge-Typ (muss mit edge. beginnen, z. B. edge.identity.manager, edge.identity.account)

Anfragekörper: JSON-Edge-Eigenschaften.

Antwort (200): JSON-Edge mit berechneter eindeutiger ID.

---

GET /internal/v1/datastore/module/config

Die Datenspeicher-Modulkonfiguration abrufen, einschließlich Replikationseinstellungen und Knotenzuweisungen.

Anfrage:

GET /internal/v1/datastore/module/config
Authorization: Bearer <token>

Antwort (200):

{
  "id": "datastore-module",
  "name": "Datastore",
  "replicas": 2,
  "weights": {
    "node-1": 100,
    "node-2": 100
  },
  "nodes": [
    { "id": "node-1", "name": "Primary", "tenant": "tenant-uuid" },
    { "id": "node-2", "name": "Secondary", "tenant": "tenant-uuid" }
  ],
  "version": 5,
  "site": "us-east-1",
  "refresh": false
}

Antwortfelder (ModuleConfig):

Feld	Typ	Beschreibung
id	string	Modulkonfigurations-ID
name	string	Modul-Anzeigename
replicas	int64	Replikationsfaktor
weights	map	Knoten-zu-Gewicht-Zuordnung für die Datenverteilung
nodes	array	Zugewiesene Knoten
version	uint64	Konfigurationsversion
site	string	Bereitstellungsstandort-Identifikator
refresh	bool	Ob eine Aktualisierung aussteht

---

POST /internal/v1/datastore/module/config

Die Datenspeicher-Modulkonfiguration aktualisieren.

Anfrage:

POST /internal/v1/datastore/module/config
Content-Type: application/json
Authorization: Bearer <token>

Der Anfragekörper verwendet die gleiche ModuleConfig-Struktur. Das Feld id ist erforderlich.

Antwort (200): Aktualisierte ModuleConfig.

---

Fehlerantworten

Status	Beschreibung
400	Ungültiger Anfragekörper, fehlender Typparameter oder ungültige Entitäts-ID-Kodierung
403	Authentifizierung fehlgeschlagen oder unzureichende Berechtigungen
404	Entität oder Datenquelle nicht gefunden
500	Interner Serverfehler

Verwandte Themen

• Backup & Wiederherstellung API — Datenspeicher-Backup- und Wiederherstellungsoperationen
• Entitätsverwaltung API — Entitäts-Indexoperationen
• Registry-Konfiguration API — Systemkonfigurationsspeicher