Mithilfe der API-Methode imx/sessions/<Name des API-Projektes> können Sie den Status der Sitzung abfragen. In der Antwort erhalten Sie folgende Informationen:
Zulässige Authentifizierungsmodule und zugehörige Parameter das jeweilige API-Projekt
Art der sekundären Anmeldung
Sie können die folgenden Arten von API-Methoden definieren.
Entity-Methoden arbeiten mit kleinen Teilen des Objektmodells, um Daten aus der Datenbank zu lesen beziehungsweise in diese zu schreiben. Wenn Sie eine Entity-Methode erstellen müssen Sie nur Tabellen- und Spaltennamen sowie gegebenenfalls eine Filterbedingung (WHERE-Klausel) angeben. Die interne Abarbeitung wird durch den API Server übernommen. Das Schema der Eingabe- und Ausgabedaten ist ebenfalls fest vorgegeben.
Beispiele zur Definition von Entity-Methoden finden Sie im SDK unter Sdk01_Basics\01-BasicQueryMethod.cs.
Benutzerdefinierte Methoden sind Methoden, deren Abarbeitung, Eingabe- und Ausgabedaten Sie im Code vollständig definieren. Dieser Typ bietet daher die größte Flexibilität.
Beispiele zur Definition von benutzerdefinierten Methoden finden Sie im SDK unter Sdk01_Basics\03-CustomMethod.cs.
SQL-Methoden sind Methoden, die Daten aus einer vordefinierten SQL-Abfrage über die API zur Verfügung stellen. Die Parameter einer Anfrage legen Sie als SQL-Parameter an.
Beispiele zur Definition von SQL-Methoden finden Sie im SDK unter Sdk01_Basics\02-BasicSqlMethod.cs.
In diesem Kapitel finden Sie nützliche Hinweise und Informationen für die Erstellung und Verwendung von Entity-Methoden.
HINWEIS: Entity-basierte Methoden arbeiten standardmäßig mit einer Limitierung, um unabsichtliches Laden extrem großer Datenmengen zu vermeiden.
Mithilfe der folgenden Abfrage-Parameter können Sie die Anzahl der zurückgegebenen Datensätze begrenzen, um mehrere Datensätze in aufeinanderfolgenden Antworten zu erhalten:
| Abfrage-Parameter | Standardwert | Beschreibung |
|---|---|---|
| PageSize | 20 |
Legen Sie fest, wie viele Datensätze in der Antwort maximal enthalten sein dürfen. Wenn Sie nur die Gesamtanzahl ermitteln, aber keine einzelnen Datensätze erhalten möchten, verwenden Sie den Wert -1. |
| StartIndex | 0 |
Legen Sie fest, ab welchem Datensatz die Ergebnisse in der Antwort zurückgegeben werden. Dieser Parameter ist nullbasiert (das erste Element wird mit dem Wert 0 angesprochen). |
Beispiel
Die folgende Anfrage gibt 50 Personen zurück und beginnt dabei bei der 101. Person:
https://<Host-Name>/ApiServer/portal/person?PageSize=50&StartIndex=100
Mithilfe des Abfrage-Parameters OrderBy können Sie die Ergebnisse einer zurückgegebenen Antwort sortieren. Mit diesem Parameter können Sie nach den Spaltennamen der zugrundeliegenden Datenbanktabelle sortieren.
Beispiele
Die folgende Anfrage gibt Personen aufsteigend sortiert nach Vorname zurück:
https://<Host-Name>/ApiServer/portal/person?OrderBy=FirstName
Personen absteigend sortiert nach Vorname:
https://<Host-Name>/ApiServer/portal/person?OrderBy=FirstName%20DESC
Mithilfe des Abfrage-Parameters filter können Sie die Ergebnisse einer zurückgegebenen Antwort filtern. Ein solcher Filter besteht aus einem JSON-formatierten String, der die folgenden Filterbedingungen enthalten muss:
CompareOp: der Vergleichsoperator, der den Inhalt der gewählten Spalte mit einem Sollwert vergleicht
Die folgenden Vergleichsoperatoren sind zulässig:
Equal: Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte mit dem Vergleichswert übereinstimmen.
NotEqual: Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte NICHT mit dem Vergleichswert übereinstimmen.
LowerThan: Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte kleiner sind als der Vergleichswert.
LowerOrEqual: Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte kleiner oder gleich dem Vergleichswert sind.
GreaterOrEqual: Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte größer oder gleich dem Vergleichswert sind.
Like: Erfordert die Verwendung eines Prozentzeichens (%) als Platzhalterzeichen. Sie können bis zu zwei Prozentzeichen in dem Wert angeben. Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte mit dem Pattern-Vergleichswert übereinstimmen.
NotLike: Erfordert die Verwendung eines Prozentzeichens (%) als Platzhalterzeichen. Sie können bis zu zwei Prozentzeichen in dem Wert angeben. Die Ergebnisse beinhalten nur Datensätze, bei denen die Daten in der Spalte NICHT mit dem Pattern-Vergleichswert übereinstimmen.
BitsSet: Der Wert wird mit einem Vergleichswert über den logischen Operator & verglichen. Das Ergebnis muss ungleich 0 sein.
BitsNotSet: Der Wert wird Wert mit einem Vergleichswert über den logischen Operator & verglichen. Das Ergebnis muss gleich 0 sein.
Value1: Vergleichswert der mit dem Inhalt der Spalte verglichen werden soll
Value2: Wird dieser zweite Vergleichswert übergeben, so wird der Wert für CompareOp ignoriert und alle Werte, die größer gleich Value1 und kleiner gleich Value2 sind, werden ermittelt.
Beispiel
Die folgende Anfrage gibt aller Identitäten mit dem Nachnamen "Smith" zurück:
https://<Host-Name>/ApiServer/portal/person/all?filter=[{ColumnName: 'LastName', CompareOp: 'Equal', Value1: 'Smith'}]
Mithilfe des Pfad-Parameters group können Sie die Ergebnisse einer zurückgegebenen Antwort gruppieren. Dabei können Sie mithilfe des Abfrage-Parameters by angeben, nach welchem Attribut gruppiert werden soll. Zusätzlich können Sie mithilfe des Abfrage-Parameters withcount festlegen (Werte: true oder false), ob die Anzahl der Objekte für jede Gruppe berechnet werden soll. Dies kann die Ausführungszeit verlängern.
HINWEIS: Die API-Methode muss Gruppierungen unterstützen (mithilfe des Parameters EnableGrouping).
Das Ergebnis der Abfrage enthält eine Filterbedingung, die Sie als URL-Parameter als Filter übergeben können.
Beispiel
Die folgende Anfrage ermittelt die Menge aller Identitäten gruppiert nach primärem Standort:
https://<Host-Name>/ApiServer/portal/person/all/group?by=UID_Locality&withcount=true
Antwort:
{ |
{ |
"Display": "(No value: Primary location)", |
"Filters": [ |
{ |
"ColumnName": "UID_Locality", |
"CompareOp": 0 |
} |
], |
"Count": 42 |
}, |
{ |
"Display": "Berlin", |
"Filters": [ |
{ |
"ColumnName": "UID_Locality", |
"CompareOp": 0, |
"Value1": "c644f672-566b-4ab0-bac0-2ad07b6cf457" |
} |
], |
"Count": 12 |
} |
} |
Einige Tabellen des Datenmodells sind als Baumstruktur definiert (beispielsweise Department). Daten aus solchen Tabellen können aus einer bestimmten Hierarchie-Ebene geladen werden.
Mithilfe des Abfrage-Parameters parentKey des übergeordneten Objekts können Sie die Hierarchie-Ebene bestimmen.
Beispiel
Die folgende Anfrage ermittelt die Servicekategorien direkt unterhalb der Servicekategorie Access Lifecycle:
https://<Host-Name>/ApiServer/portal/servicecategories?parentKey=QER-f33d9f6ec3e744a3ab69a474c10f6ff4
Die folgende Anfrage ermittelt die Servicekategorien, die keine übergeordnete Servicekategorie haben:
https://<Host-Name>/ApiServer/portal/servicecategories?parentKey=
Die folgende Anfrage ermittelt alle Servicekategorien unabhängig von ihrer Hierarchie:
https://<Host-Name>/ApiServer/portal/servicecategories
Mithilfe des Pfad-Parameters noRecursive können Sie festlegen, ob die Daten als flache Liste abgefragt wird (Werte: true oder false).
Beispiel
https://<Host-Name>/ApiServer/portal/servicecategories?noRecursive=true
Mithilfe des Abfrage-Parameters withProperties können Sie festlegen, welche zusätzlichen Informationen aus bestimmten Tabellenspalten in der zurückgegebenen Antwort enthalten sein sollen.
HINWEIS: Um Tabellenspalten für diese Abfragen freizugeben, aktivieren Sie im Designer für die entsprechenden Spalten in den Spalteneigenschaften die Option Anzeige in Assistenten.
TIPP: Sie können die Namen mehrerer Spalten kommasepariert angeben.
Beispiel
Die folgende Anfrage ermittelt die Menge aller Identitäten und gibt zusätzlich deren bevorzugten Namen und Titel zurück:
https://<Host-Name>/ApiServer/portal/person/all?withProperties=PreferredName,Title
Antwort:
{ |
"TotalCount": 105950, |
"TableName": "Person", |
"Entities": [ |
{ |
"Display": "100, User (USER1)", |
"LongDisplay": "100, User (USER1)", |
"Keys": [ |
"bbf3f8e6-b719-4ec7-be35-cbd6383ef370" |
], |
"Columns": { |
"DefaultEmailAddress": { |
"Value": "USER1@qs.ber", |
"IsReadOnly": true |
}, |
"IdentityType": { |
"Value": "Primary", |
"IsReadOnly": true, |
"DisplayValue": "Primary identity" |
}, |
"PreferredName": { |
"Value": "Johnny", |
"IsReadOnly": true |
}, |
"Title": { |
"Value": "Dr.", |
"IsReadOnly": true |
}, |
"XObjectKey": { |
"Value": "<Key><T>Person</T><P>bbf3f8e6-b719-4ec7-be35-cbd6383ef370</P></Key>", |
"IsReadOnly": true |
} |
} |
} |
HTTP-Anfragen können die folgenden HTTP-Methoden verwenden:
GET: Diese Methode ruft Daten vom Anwendungsserver ab.
PUT: Diese Methode ändert Daten auf dem Anwendungsserver.
POST: Diese Methode erstellt Daten auf dem Anwendungsserver.
DELETE: Diese Methode löscht Daten auf dem Anwendungsserver.
© ALL RIGHTS RESERVED. Nutzungsbedingungen Datenschutz Cookie Preference Center
