Abfrageparameter

Sie können Abfrageparameter in Anforderungen an die REST-API der Identitätsdomains aufnehmen. Diese Parameter sind nützlich, um Ressourcen mit bestimmten Attributen oder Attributwerten zu finden und um die Ausgabe zu sortieren und zu paginieren.

Abfrageparameter

Mit einer Abfrage können Sie die Ausgabe filtern, um:

Hinweis

Abfragefilterfunktionen hängen vom REST-Service ab. REST-Services ohne SCIM unterstützen möglicherweise die erweiterte Filterung und Parameter nicht, die Sie verwenden möchten.

Listen Sie nur Ressourcen auf, die angegebene Attribute enthalten oder die angegebene Werte für Attribute aufweisen.
Beschränken Sie die im Antworttext zurückgegebenen Attribute.
Sortieren Sie die Ausgabe nach einem angegebenen Attribut in aufsteigender oder absteigender Reihenfolge.
Begrenzen Sie die Anzahl der zurückgegebenen Ressourcen.
Geben Sie an, wo in der Liste der Ressourcen in der Sammlung die Anforderung gestartet werden soll.

Abfrageparameter werden in der Regel mit Suchmethoden verwendet:

GET: Zum Filtern von Suchergebnissen. Siehe Abfrageparameter mit GET.
POST: Zum Filtern von Suchergebnissen anhand der Parameter im Anforderungsbody (aus Sicherheitsgründen). Siehe Abfrageparameter mit POST/.search-Anforderungstext.

Abfrageparameter mit GET

Wenn Sie eine Suche mit einer GET-Anforderung für einen Ressourcenendpunkt wie /Users oder /Groups ausführen, setzen Sie die Abfrage in die URL. Hängen Sie ein Fragezeichen (?) an die URL an, gefolgt von der Abfrage.

Hinweis

Zeichen in einer URL, die sich außerhalb des ASCII-Zeichensatzes befinden, wie Leerzeichen und Anführungszeichen, müssen URL-codiert sein. Beispiele sind URL-codierte Zeichen. Das + ersetzt Leerzeichen und %22 ersetzt Anführungszeichen (").

https://<domainURL>/admin/v1/Users?attributes=email&filter=userName+co+%22jensen%22

So suchen Sie alle Gruppen und AppRoles, die mit einem bestimmten Benutzer verknüpft sind:

https://<domainURL>/admin/v1/Users/1e895413c68d42c7bc006d0033794c1e?attributes=groups,urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:appRoles

Abfrageparameter mit POST/.search-Anforderungstext

Sie können Suchen mit einer POST-Anforderung an einem Ressourcenendpunkt erstellen, der auf /.search endet. In diesem Fall legen Sie die Abfrage im Request Body ab. Bei der Suche nach sensiblen Informationen, wie Benutzernamen, bei denen die sensiblen Informationen zusammen mit anderen Daten übermittelt werden, verwenden Sie diese Methode (aus Sicherheitsgründen).

Dieses Beispiel zeigt den Anforderungstext einer POST-Methode, die für den Endpunkt /Users/.search ausgeführt wird. Gibt die ersten 10 Benutzereinträge mit displayName zurück, beginnend mit smith und meta.resourceType gleich User.

{ 
"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"attributes": ["displayName","userName"], 
"filter": "(displayName sw \"smith\")", "startIndex": 1, "count": 10
}

Der Parameter attributes kann mit allen Methoden außer DELETE verwendet werden. Die anderen Abfrageparameter sind nur für Suchmethoden relevant und werden von anderen Methoden ignoriert.


HTTP-Abfrageparameter	Beschreibung
`attributes=attribute1,attribute2`	Gibt eine mehrwertige Liste von Zeichenfolgen an, die den Namen der Ressourcenattribute angeben, die in der Antwort zurückgegeben werden sollen. Dieser Abfrageparameter akzeptiert auch die Erweiterungsschema-ID als gültigen Attributnamen. Wenn Sie die Erweiterungsschema-ID in die Attribute aufnehmen, werden alle darin enthaltenen Standardattribute zurückgegeben.
`attributeSets`	Die Suche gibt eine Gruppe von Attributen in der Antwort zurück, anstatt jedes Attribut einzeln anzugeben. Dieser Abfrageparameter akzeptiert durch Komma getrennte Werte aus den folgenden Parametern: all (gibt alle Attribute zurück) immer (gibt alle im Schema als immer gekennzeichneten Attribute zurück) default (gibt alle Standardattribute zurück) Anforderung (gibt alle als Anforderung im Schema markierten Attribute zurück) Bei diesen Werten wird nicht zwischen Groß- und Kleinschreibung unterschieden. Wenn sowohl `attributes` als auch `attributeSets` in der Anforderung angegeben sind, werden die Werte von beiden in der Antwort zurückgegeben.
`count=N`	Gibt die maximale Anzahl an Suchergebnissen pro Seite an. Geben Sie eine nicht-negative Zahl zum Abrufen einer Antwort an. Eine negative Zahl ist standardmäßig 50 und gibt die ersten 50 Ressourcen zurück.
`startIndex=N`	Gibt den Startseitenindex an. Dies ist der 1-basierte Index des ersten Abfrageergebnisses. Ein Wert kleiner als 1 wird als 1 interpretiert.
`filter=Expression`	Die Suche gibt alle Ressourcen im angegebenen Endpunkt zurück, für den der Ausdruck "true" ist. Weitere Informationen finden Sie unter Filterabfrageparameter verwenden.
`sortBy=attribute`	Gibt den Attributnamen an, nach dem die Antwort sortiert werden soll.
`sortOrder=ascending` \| `sortOrder=descending`	Gibt die Reihenfolge an, in der der der Parameter `sortBy` angewendet wird. Wenn Sie einen Wert für `sortBy` angeben und keinen `sortOrder` angeben, lautet der Standardwert für `sortOrder` `ascending.`

Filterabfrageparameter verwenden

Sie können die Abfrage filter in Suchen verwenden, die Sie mit der Methode GET ausführen. Das Format einer Filterabfrage lautet:

filter=Expression

Ein Filter muss mindestens einen gültigen Ausdruck enthalten. Jeder Ausdruck enthält einen Attributnamen gefolgt von einem Attributoperator und einem optionalen Wert. Durchsuchbare Attribute variieren von einer Ressource zur anderen. Diese werden in den Themen für diese GET-Anforderungen behandelt.

Die folgende URL enthält eine Filterabfrage für Benutzer mit dem Attribut userName, das jensen: enthält

https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22


Attributoperator	Beschreibung	Verhalten
`eq`	Gleich	Die Attribut- und Operatorwerte müssen für eine Übereinstimmung identisch sein.
`ne`	Nicht gleich	Die Attribut- und Operatorwerte sind nicht identisch.
`co`	Enthält	Der gesamte Operatorwert muss eine Teilzeichenfolge des Attributwerts für eine Übereinstimmung sein.
`sw`	Beginnt mit	Der gesamte Operatorwert muss eine Teilzeichenfolge des Attributwertes sein, beginnend am Anfang des Attributwertes. Dieses Kriterium wird erfüllt, wenn die beiden Zeichenfolgen identisch sind.
`ew`	Endet mit	Der gesamte Operatorwert muss eine Teilzeichenfolge des Attributwertes sein, die am Ende des Attributwertes übereinstimmt. Dieses Kriterium wird erfüllt, wenn die beiden Zeichenfolgen identisch sind.
`pr`	Vorhanden (hat Wert)	Wenn das Attribut einen nicht leeren Wert hat oder einen nicht leeren Knoten für komplexe Attribute enthält, gibt es eine Übereinstimmung.
`gt`	Größer als	Wenn der Attributwert größer als der Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikografischen Vergleich. Bei `DateTime`-Typen handelt es sich um einen chronologischen Vergleich.
`ge`	Größer als oder gleich	Wenn der Attributwert größer oder gleich dem Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikografischen Vergleich. Bei `DateTime`-Typen handelt es sich um einen chronologischen Vergleich.
`lt`	Kleiner als	Wenn der Attributwert kleiner als der Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikografischen Vergleich. Bei `DateTime`-Typen handelt es sich um einen chronologischen Vergleich.
`le`	Kleiner als oder gleich	Wenn der Attributwert kleiner oder gleich dem Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikografischen Vergleich. Bei `DateTime`-Typen handelt es sich um einen chronologischen Vergleich.

Sie können mehrere Ausdrücke kombinieren, indem Sie die logischen Operatoren and und or verwenden und einen Ausdruck negieren, indem Sie ihm den Attributoperator not. voranstellen Verwenden Sie Klammern () für Prioritätsgruppierung und eckige Klammern [] für die Gruppierung komplexer Attributfilter.

Beispiele für Abfrageparameterfilter

Verwenden Sie die folgenden Abfrageparameterbeispiele als Ausgangspunkt für Abfragen in einer Identitätsdomain.

Benutzerbeispiele

Um nach Benutzern zu suchen, deren Attribut userName gleich example ist, verwenden Sie diesen Filter:

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22

Dieses Filterbeispiel sucht nach einem Benutzer mit einer userName, die jensen: enthält

https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22

In diesem Filterbeispiel wird nach einem Benutzer mit einer userName gesucht, die entweder example enthält oder mit my: beginnt

https://<domainURL>/admin/v1/Users?filter=userName+co+%22example%22+or+userName+sw+%22my%22

In diesem Filterbeispiel wird nach einem Benutzer mit dem Unterattribut familyName von name gesucht, der jensen: enthält

https://<domainURL>/admin/v1/Users?filter=name.familyName+co+%22jensen%22

Dieses komplexe URL-Abfragebeispiel gibt alle Benutzer zurück, deren userName gleich example ist, listet die Attribute emails.value und name.familyName im JSON-Antwortbody auf und gibt maximal acht Benutzer pro Ausgabeseite zurück.

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22&attributes=emails.value,name.familyName&count=8

In diesem Filterbeispiel wird nach Benutzern gesucht, die den Filterparameter in GET verwenden.

https://<domainURL>/admin/v1/Users/?filter=phoneNumbers.value co "415"

Dieses Filterbeispiel gibt Benutzer zurück, die das durchsuchbare benutzerdefinierte Attribut Nickname aufweisen. Weitere Informationen zu durchsuchbaren benutzerdefinierten Attributen finden Sie unter Benutzerschemas anpassen und Schemas anpassen.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname pr)

Dieses Filterbeispiel gibt Benutzer zurück, deren durchsuchbares benutzerdefiniertes Attribut mit einer Textzeichenfolge übereinstimmt. Weitere Informationen zu durchsuchbaren benutzerdefinierten Attributen finden Sie unter Benutzerschemas anpassen und Schemas anpassen.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname eq "aabbccc")

Beispiele für Telefonnummern

In diesem Filterbeispiel wird nach Benutzern gesucht, deren Telefonnummer mit "+1"* beginnt.

Hinweis

Funktioniert nur mit POST-Vorgängen.


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"filter": "phoneNumbers.value sw \"+1\""
}

In diesem Filterbeispiel wird nach Benutzern gesucht, deren private Telefonnummer die Zeichenfolge "503" enthält.


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],  
"filter": "phoneNumbers[type eq \"home\"].value co \"503\""
}

Oder


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"filter": "phoneNumbers[type eq \"home\" and value co \"503\"]"
}

In diesem Filterbeispiel wird nach Benutzern mit Telefonnummernvariationen gesucht.

Hinweis

Der SCIM-Filterparameter unterstützt keine RegEx-Muster. Sie müssen alle möglichen Variationen enthalten haben. Verwenden Sie das folgende Beispiel, um zu beginnen.


POST https://<domainURL>/admin/v1/Users/.search 
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"phoneNumbers.value eq \"+1 9xxxx xxxxx\" or phoneNumbers.value eq \"+19xxxx xxxxx\" or phoneNUmbers.value eq \"+19xxxxxxxxx\""
}

Beispiele für Anwendungsrollen

In diesem Filterbeispiel werden alle Benutzer gesucht, die über eine bestimmte AppRole verfügen:

https://<domainURL>/admin/v1/Users?filter=urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:approles.value+eq+<idOfAppRole>

Dieses Filterbeispiel gibt Elemente der AppRole mit der approleid zurück.


GET https://<domainURL>/admin/v1/AppRoles/{{approleid}}?attributes=members

Dieses Filterbeispiel gibt AppRoles für eine bestimmte Anwendung zurück, die appid verwendet.


GET https://<domainURL>/admin/v1/AppRoles?filter=app.value eq "{{appid}}"

Oracle Cloud Infrastructure - Dokumentation

Abfrageparameter

Abfrageparameter

Abfrageparameter mit GET

Abfrageparameter mit POST/.search-Anforderungstext

Filterabfrageparameter verwenden

Beispiele für Abfrageparameterfilter

Benutzerbeispiele

Beispiele für Telefonnummern

Beispiele für Anwendungsrollen