Deutsch

English

Deutsch

English

Appearance

Entitätsverwaltungs-API ​

ENTWURF — Nur für interne Entwickler

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

Übersicht ​

Was es ist: Die Entitätsverwaltungs-API bietet Low-Level-Zugriff auf den Entitätsindex, der alle erkannten Identitäten, Konten, Gruppen und deren Beziehungen (Kanten) verfolgt. Diese API unterstützt das Erstellen von Indexspeichern, das Abfragen indizierter Entitäten mit Filterung und Paginierung sowie die Verwaltung von Kanten zwischen Entitäten.

Quelle: src/entman/rest/rest.go

Basispfad ​

/internal/v1/entity/index

Authentifizierung ​

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

Endpunkte ​

MethodePfadBeschreibungAuthentifizierung erforderlich
POST/internal/v1/entity/index/storeEinen neuen Entitätsindex-Speicher erstellenJWT + API-Token
POST/internal/v1/entity/index/store/queryEntitätsindex-Einträge mit Filterung abfragenJWT + API-Token
POST/internal/v1/entity/index/edge/addBeziehungskanten hinzufügenJWT + API-Token
POST/internal/v1/entity/index/edge/delBeziehungskanten löschenJWT + API-Token
POST/internal/v1/entity/index/entity/addEntitäten zum Index hinzufügenJWT + API-Token
POST/internal/v1/entity/index/entity/delEntitäten aus dem Index löschenJWT + API-Token

POST /internal/v1/entity/index/store ​

Einen neuen Entitäts-Mapper-Speicher erstellen. Ein Speicher stellt eine indizierte Ansicht von Entitäten zu einem bestimmten Zeitpunkt dar und wird für Zuordnungsoperationen verwendet.

Anfrage:

http
POST /internal/v1/entity/index/store
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "viewTime": 1707700800000
}

Anfragefelder:

FeldTypBeschreibung
idstringSpeicherbezeichner
viewTimeint64Zeitpunkt-Zeitstempel (ms) für den Entitäts-Snapshot

Antwort (200): Gibt den erstellten MapperStore mit ausgefüllten Replikationsknoten-Metadaten zurück.

POST /internal/v1/entity/index/store/query ​

Entitäten im Indexspeicher mit Filterung, Paginierung und Zuordnungsstatusinformationen abfragen.

Anfrage:

http
POST /internal/v1/entity/index/store/query
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "type": "identity.user",
  "skip": 0,
  "limit": 100,
  "filter": {
    "search": "john",
    "all": false,
    "isMappedCurrent": true,
    "isMappedOther": false,
    "isUnmapped": false
  },
  "mappedTo": "edge.identity.account",
  "tombstoned": false,
  "classifications": true,
  "mappingRules": false
}

Abfragefelder:

FeldTypBeschreibung
idstringAbzufragende Speicher-ID
typestringEntitätstyp-Filter (z. B. identity.user, identity.group)
skipint64Anzahl der zu überspringenden Einträge (Paginierungs-Offset)
limitint64Maximale Anzahl zurückzugebender Einträge (Standard: 100)
filter.searchstringFreitextsuche über Entitätsfelder
filter.allboolAlle Entitäten unabhängig vom Zuordnungsstatus zurückgeben
filter.isMappedCurrentboolIm aktuellen Speicher zugeordnete Entitäten einschließen
filter.isMappedOtherboolIn anderen Speichern zugeordnete Entitäten einschließen
filter.isUnmappedboolNur nicht zugeordnete Entitäten einschließen
mappedTostringNach ausgehendem Kantentyp filtern
mappedFromstringNach eingehendem Kantentyp filtern
uniqueIdstringEine bestimmte Entität anhand der eindeutigen ID abrufen
tombstonedboolGelöschte (soft-deleted) Einträge einschließen
tombstonedMappingsboolGelöschte Zuordnungen einschließen
classificationsboolKlassifizierungsdaten einschließen
mappingRulesboolÜbereinstimmende Zuordnungsregeln einschließen

Antwort (200):

json
{
  "total": 4521,
  "last": 100,
  "mapped": 4200,
  "unmapped": 321,
  "entry": [
    {
      "id": 1,
      "dataSourceId": "ds-uuid",
      "dataSource": "Corporate AD",
      "uniqueId": "acct-uuid",
      "entityType": "identity.user",
      "entitySearch": "john doe jdoe",
      "platform": "Active Directory",
      "entity": { },
      "mapping": [
        {
          "uniqueId": "owner-uuid",
          "edgeType": "edge.identity.account",
          "time": 1707700800000,
          "tombstoned": false
        }
      ],
      "mapped": true,
      "tombstoned": false,
      "time": 1707700800000,
      "mappings": 1
    }
  ]
}

Antwortfelder:

FeldTypBeschreibung
totalint64Gesamtzahl übereinstimmender Einträge
lastint64Index des letzten zurückgegebenen Eintrags
mappedint64Anzahl zugeordneter Einträge, die dem Filter entsprechen
unmappedint64Anzahl nicht zugeordneter Einträge, die dem Filter entsprechen
entry[].entityobjectDie vollständigen Entitätsdaten (aus Protobuf deserialisiert)
entry[].mappingarrayAktive Kantenzuordnungen für diese Entität

POST /internal/v1/entity/index/edge/add ​

Beziehungskanten zwischen Entitäten im Index hinzufügen. Kanten repräsentieren Verbindungen wie Konto-zu-Besitzer-Zuordnungen oder Gruppenmitgliedschaften.

Anfrage:

http
POST /internal/v1/entity/index/edge/add
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "type": "edge.identity.account",
  "edge": [
    { "from": "owner-uuid-1", "to": "account-uuid-1" },
    { "from": "owner-uuid-1", "to": "account-uuid-2" }
  ]
}

Anfragefelder:

FeldTypBeschreibung
idstringSpeicher-ID
typestringKantentyp (z. B. edge.identity.account, edge.identity.manager)
edge[].fromstringEindeutige ID der Quellentität
edge[].tostringEindeutige ID der Zielentität

Antwort (200): Gibt die gleiche EdgeRequest-Struktur zurück und bestätigt die hinzugefügten Kanten.

POST /internal/v1/entity/index/edge/del ​

Beziehungskanten aus dem Entitätsindex entfernen. Verwendet die gleiche Anfragestruktur wie Kanten hinzufügen.

Anfrage:

http
POST /internal/v1/entity/index/edge/del
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "type": "edge.identity.account",
  "edge": [
    { "from": "owner-uuid-1", "to": "account-uuid-1" }
  ]
}

Antwort (200): Gibt die EdgeRequest zurück und bestätigt die gelöschten Kanten.

POST /internal/v1/entity/index/entity/add ​

Entitäten zum Indexspeicher hinzufügen. Entitäten werden aus ihren Protobuf-Definitionen serialisiert.

Anfrage:

http
POST /internal/v1/entity/index/entity/add
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "type": "identity.user",
  "entity": [
    {
      "id": "entity-uuid-1",
      "entity": {
        "displayName": "John Doe",
        "email": "john.doe@company.com"
      }
    }
  ]
}

Anfragefelder:

FeldTypBeschreibung
idstringSpeicher-ID
typestringEntitätstyp (wird über die Protobuf-Registry nachgeschlagen)
entity[].idstringEindeutige Entitäts-ID
entity[].entityobjectEntitätsdaten, die dem Protobuf-Schema für den Typ entsprechen

Antwort (200): Gibt die EntityRequest zurück und bestätigt die hinzugefügten Entitäten.

POST /internal/v1/entity/index/entity/del ​

Entitäten aus dem Indexspeicher entfernen.

Anfrage:

http
POST /internal/v1/entity/index/entity/del
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "id": "store-uuid",
  "type": "identity.user",
  "entity": [
    { "id": "entity-uuid-1" }
  ]
}

Antwort (200): Gibt die EntityRequest zurück und bestätigt die gelöschten Entitäten.

Fehlerantworten ​

StatusBeschreibung
400Ungültiger Anfragekörper, fehlende Pflichtfelder oder unbekannter Entitätstyp
403Authentifizierung fehlgeschlagen oder unzureichende Berechtigungen
404Speicher oder Entität nicht gefunden
500Interner Serverfehler

Verwandte Themen ​

Hydden Documentation and Training Hub

Copyright © 2026 Hydden