Die Lookup-API in DQE One Standalone verwenden

Sobald Sie Datensätze mit einem Index Records-Process indiziert haben (siehe Create and launch a process in DQE One Standalone), können Ihre eigenen Anwendungen diesen Index in Echtzeit über eine kleine REST-API abfragen — um eine Autovervollständigungssuche zu betreiben oder vor dem Anlegen eines neuen Datensatzes auf Dubletten zu prüfen.

Authentifizierung

Alle 4 Endpunkte unten verwenden dieselben Zugangsdaten wie der MCP-Server und der Rest der REST-API von DQE One Standalone: HTTP Basic Auth mit Ihrer Konto-E-Mail und Ihrem API-Token.

# Linux / macOS
echo -n "you@example.com:your_api_token" | base64

# Windows PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("you@example.com:your_api_token"))

Finden oder erneuern Sie Ihr Token unter My Account > API Token. Senden Sie es als Authorization: Basic <Base64-Wert> bei jeder Anfrage.

Verwenden Sie die Zugangsdaten eines echten, existierenden Kontos — ein wohlgeformter Header mit Bezug auf eine nicht existierende E-Mail-Adresse liefert derzeit einen Serverfehler statt einer sauberen "nicht autorisiert"-Antwort.

Diese Endpunkte erlauben auch Cross-Origin-Anfragen, Sie können sie also direkt aus einem Browser heraus aufrufen (zum Beispiel, um ein Live-Suchfeld mit Vorschlägen beim Tippen zu bauen). Falls Sie das tun, beachten Sie, dass Ihr API-Token dann für jeden sichtbar wäre, der die Seite untersucht — für alles über ein internes, vertrauenswürdiges Werkzeug hinaus rufen Sie diese Endpunkte stattdessen von Ihrem eigenen Backend aus auf und behalten das Token serverseitig.

Welcher Endpunkt wofür

GET /api/searchGolden existiert ebenfalls und nimmt dieselben Parameter wie searchRecords entgegen — führt derzeit aber genau dieselbe wörtliche/phonetische Suche aus, keine Dubletten-Matching-Suche. Trotz des Namens liefert es keinen Golden Record zurück und wendet keine Matching-Regeln an. Verwenden Sie dafür lookupGolden.

Den abzufragenden Index bestimmen

Jeder Endpunkt muss wissen, welche Daten eines Index-Records-Process durchsucht werden sollen. Geben Sie eines von beiden an:

• pid — die Id des Index-Records-Process.
• recordType — der Name des Objekts/der Tabelle, die er indiziert (z. B. ein Salesforce- oder Dynamics-Objektname). Standalone löst dies zum zuletzt erstellten, veröffentlichten, nicht archivierten Index-Records-Process auf, der dieses Objekt indiziert — passt keiner, erhalten Sie einen Fehler statt eines stillen Rückfalls auf etwas anderes.

Wird keines von beiden angegeben, schlägt die Anfrage fehl mit {"status":"error","error":"Either 'pid' or 'recordType' must be provided"}.

GET /api/searchRecords

Parameter (Query-String):

Liefert ein JSON-Array übereinstimmender Datensätze — jeder davon ist der vollständige Satz der zum Indizierungszeitpunkt gespeicherten Felder, begrenzt auf 50 Ergebnisse (keine Seitenaufteilung). Es gibt keine Distanzbewertung: ein Datensatz erfüllt eine der folgenden Suchstufen, oder er tut es nicht.

Standalone probiert jede Stufe der Reihe nach durch und stoppt, sobald eine davon genug Ergebnisse liefert:

1. Eine exakte Übereinstimmung eines ganzen Worts.
2. Eine Teil-/Präfix-Übereinstimmung (nützlich, während die Person noch tippt).
3. Eine französischsprachige phonetische Übereinstimmung.
4. Eine generische phonetische Übereinstimmung.

In der Praxis bedeutet das, dass ein kurzer oder leicht falsch geschriebener Suchbegriff trotzdem den richtigen Datensatz liefern kann — es bedeutet aber auch, dass eine Suche gelegentlich einen phonetisch ähnlichen Datensatz liefern kann, der nicht der gemeinte ist (z. B. kann die Suche nach "Dupont" auch "Dupond" liefern).

Beispiel:

curl -G "https://your-standalone-url/api/searchRecords" \
  --data-urlencode "search=Dupont" \
  --data-urlencode "recordType=Contact" \
  -H "Authorization: Basic <Base64-Wert>"

POST /api/lookupRecords

Body: ein JSON-Objekt aus Feld/Wert-Paaren, auf die abgeglichen werden soll, plus pid oder recordType (entweder im Body oder als Query-Parameter), zum Beispiel:

{
  "pid": 12,
  "LastName": "Dupont",
  "Email": "a@b.com"
}

Beispiel:

curl -X POST "https://your-standalone-url/api/lookupRecords" \
  -H "Authorization: Basic <Base64-Wert>" \
  -H "Content-Type: application/json" \
  -d '{"recordType": "Contact", "LastName": "Dupont", "Email": "a@b.com"}'

Liefert ein JSON-Array aller Kandidaten-Datensätze, die die Matching-Regeln Ihres RuleSets als mögliche Übereinstimmung betrachten — keine Begrenzung der Ergebnisanzahl und keine Sortierung/Bewertung je Datensatz. Betrachten Sie dies als eine Shortlist, die Sie selbst eingrenzen, nicht als endgültige Antwort.

POST /api/lookupGolden — Echtzeit-Dublettenprüfung

Derselbe Request-Body wie bei lookupRecords. Dies ist der einzige Endpunkt, der eine vollständige Bewertung anwendet — er verwendet dieselben Matching-Algorithmen und die im Matching-Tab Ihres RuleSets konfigurierten Threshold-Einstellungen wieder.

curl -X POST "https://your-standalone-url/api/lookupGolden" \
  -H "Authorization: Basic <Base64-Wert>" \
  -H "Content-Type: application/json" \
  -d '{"recordType": "Contact", "LastName": "Dupont", "Email": "a@b.com"}'

Antwort, wenn eine Übereinstimmung gefunden wird:

{
  "certainty": 0.92,
  "matched_by": "Name + Email",
  "record": { "LastName": "Dupont", "Email": "a@b.com", ... }
}

• certainty — ein Wert von 0 bis 1 (1 = exakte Übereinstimmung), abgeleitet aus dem Distanz-Score der Matching-Regel.
• matched_by — der Name der Matching-Regel, die den besten Score erzielt hat.
• record — der vollständige indizierte Datensatz. Ist bei Ihrem Index-Records-Process ein Parent-Id-Feld konfiguriert, handelt es sich hierbei um den übergeordneten Datensatz der Übereinstimmung statt um die Übereinstimmung selbst.

Stimmt nichts nah genug überein, um den Threshold irgendeiner Regel zu erfüllen, ist die Antwort ein leeres Objekt {} — behandeln Sie das als "keine Dublette gefunden".

Den Index aktuell halten

Es gibt keine inkrementelle Indizierung — jedes Mal, wenn der Index-Records-Process läuft, baut er seinen Index vollständig neu von Grund auf auf. So halten Sie die Ergebnisse aktuell:

• Führen Sie den Process manuell erneut aus, oder planen Sie ihn (siehe Schedule a process in DQE One Standalone) — die kürzeste verfügbare Häufigkeit ist alle 15 Minuten.
• Eine Änderung der Matching-Regeln des RuleSets wirkt sich sofort auf diese 4 Endpunkte aus, ohne dass etwas erneut ausgeführt werden muss — dies betrifft aber nur, wie künftige Abfragen bewertet werden, nicht die bereits indizierten Daten selbst.

Fehlerbehandlung

Fast jeder Fehler — ein fehlendes pid/recordType, ein unbekannter recordType, ein fehlerhafter Request-Body — kommt als normale HTTP-200-Antwort mit {"status":"error","error":"..."} im Body zurück. Der einzige Fall, der einen anderen HTTP-Status liefert, ist ein Authentifizierungsfehler (401). Prüfen Sie immer den Antwort-Body, nicht nur den HTTP-Statuscode.

Grenzen

• searchRecords/searchGolden liefern höchstens 50 Ergebnisse, ohne Seitenaufteilung — grenzen Sie Ihren Suchbegriff ein, wenn Sie mehr sehen müssen.
• Keiner dieser 4 Endpunkte hat eine eingebaute Ratenbegrenzung. Wenn Sie sie aus einer Integration mit hohem Traffic heraus aufrufen (zum Beispiel ein öffentlich zugängliches Suchfeld), ergänzen Sie Ihre eigene Drosselung auf Ihrer Seite, statt sich darauf zu verlassen, dass DQE One Standalone sich selbst schützt.

Verwandte Artikel

• Field Reference in DQE One Standalone
• Create and launch a process in DQE One Standalone
• Connect a data source in DQE One Standalone
• Configure a RuleSet in DQE One Standalone
• Schedule a process in DQE One Standalone