Oracle Cloud Infrastructure - Dokumentation

Abfrageparameter

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

Informationen zu Abfrageparametern

Mit einer Abfrage können Sie die Ausgabe wie folgt filtern:

Hinweis

Die Filterfunktionen für Abfragen hängen vom REST-Service ab. REST-Services ohne SCIM unterstützen möglicherweise nicht die erweiterten Filter und Parameter, die Sie verwenden möchten.

  • Listen Sie nur Ressourcen auf, die bestimmte Attribute enthalten oder die bestimmte Werte für Attribute aufweisen.

  • Begrenzen Sie die im Antwortbody zurückgegebenen Attribute.

  • Die Ausgabe nach einem angegebenen Attribut in aufsteigender oder absteigender Reihenfolge sortieren.

  • Begrenzen Sie die Anzahl der zurückgegebenen Ressourcen.

  • Geben Sie an, wo die Anforderung in der Liste der Ressourcen in der Collection gestartet werden soll.

Abfrageparameter werden in der Regel mit Suchmethoden verwendet:

Abfrageparameter mit GET

Wenn Sie eine Suche mit einer GET-Anforderung an einem Ressourcenendpunkt wie /Users oder /Groups ausführen, fügen Sie die Abfrage in die URL ein. 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 werden mit URL-codierten Zeichen bereitgestellt. 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 fügen Sie die Abfrage in den Anforderungstext ein. Verwenden Sie diese Methode (aus Sicherheitsgründen) bei der Suche nach vertraulichen Informationen, wie Benutzernamen, bei denen die vertraulichen Informationen zusammen mit anderen Daten übermittelt werden.

Dieses Beispiel zeigt den Anforderungsbody einer POST-Methode, die für den Endpunkt /Users/.search ausgeführt wird. Gibt die ersten 10 Benutzereinträge zurück, wobei displayName mit smith beginnt und meta.resourceType gleich User. ist 
{ 
"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 mit Ausnahme von 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 mit Zeichenfolgen an, die die Namen der Ressourcenattribute angibt, 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 kommagetrennte Werte aus den folgenden Parametern:

  • alle (gibt alle Attribute zurück)

  • Always (gibt alle Attribute zurück, die wie immer im Schema markiert sind)

  • Standard (gibt alle Standardattribute zurück)

  • Anforderung (gibt alle Attribute zurück, die als Anforderung im Schema markiert sind)

Bei diesen Werten wird nicht zwischen Groß- und Kleinschreibung unterschieden. Wenn in der Anforderung sowohl attributes als auch attributeSets angegeben sind, werden die Werte aus beiden in der Antwort zurückgegeben.
count=N Gibt die maximale Anzahl von Suchergebnissen pro Seite an. Geben Sie eine nicht negative Zahl an, um eine Antwort abzurufen. Eine negative Zahl wird standardmäßig auf 50 gesetzt und gibt die ersten 50 Ressourcen zurück.
startIndex=N Gibt den Index der Startseite 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 die der Ausdruck wahr ist. Weitere Informationen finden Sie in 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 keine 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 Ressource zu Ressource. 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

Hinweis

Zeichen in einer URL, die sich außerhalb des ASCII-Zeichensatzes befinden, wie Leerzeichen und Anführungszeichen, müssen URL-codiert sein. Beispiele werden mit URL-codierten Zeichen bereitgestellt. Das + ersetzt Leerzeichen und %22 ersetzt Anführungszeichen (").
https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22
Attributoperator Beschreibung Verhalten
eq Entspricht 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 Attributwerts sein, beginnend am Anfang des Attributwerts. Dieses Kriterium wird erfüllt, wenn die beiden Zeichenfolgen identisch sind.
ew Endet mit Der gesamte Operatorwert muss eine Teilzeichenfolge des Attributwerts sein und am Ende des Attributwerts übereinstimmen. Dieses Kriterium wird erfüllt, wenn die beiden Zeichenfolgen identisch sind.
pr Vorhanden (hat Wert) Wenn das Attribut einen nicht leeren Wert aufweist 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 lexikographischen Vergleich. Bei DateTime-Typen handelt es sich um einen chronologischen Vergleich.
ge größer oder gleich Wenn der Attributwert größer/gleich dem Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikographischen 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 lexikographischen Vergleich. Bei DateTime-Typen handelt es sich um einen chronologischen Vergleich.
le Kleiner als oder gleich Wenn der Attributwert kleiner/gleich dem Operatorwert ist, gibt es eine Übereinstimmung. Der tatsächliche Vergleich hängt vom Attributtyp ab. Bei Zeichenfolgenattributtypen handelt es sich um einen lexikographischen Vergleich. Bei DateTime-Typen handelt es sich um einen chronologischen Vergleich.

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

Beispiele für Abfrageparameterfilter

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

Hinweis

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

Beispiele für Benutzer

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

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

In diesem Filterbeispiel wird nach einem Benutzer mit einer userName gesucht, 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, das jensen: enthält

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

Dieses komplexe URL-Abfragebeispiel gibt alle Benutzer mit einem userName-Wert von example zurück, 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 werden Benutzer mit dem Filterparameter in GET gesucht.

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

Dieses Filterbeispiel gibt Benutzer zurück, die das durchsuchbare benutzerdefinierte Attribut Nickname haben. 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

Dieses Filterbeispiel sucht nach Benutzern, 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 aufgenommen 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\""
}

Anwendungsrollenbeispiele

In diesem Filterbeispiel werden alle Benutzer mit einer bestimmten AppRole gesucht:

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 mit dem appid zurück.


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