問合せパラメータ

アイデンティティ・ドメインREST APIへのリクエストに問合せパラメータを含めることができます。これらのパラメータは、特定の属性や属性値を含むリソースの検索、および出力のソートやページインに役立ちます。

問合せパラメータについて

問合せを使用して出力をフィルタし、次のことを実行できます。

ノート

問合せフィルタ機能はRESTサービスに依存します。SCIMのないRESTサービスは、使用する詳細フィルタおよびパラメータをサポートしていない可能性があります。

指定の属性を含むリソース、または属性に対して指定の値が設定されたリソースのみをリストします。
レスポンス本文で返される属性を制限します。
指定の属性で出力をソートします。
返されるリソースの数を制限します。
コレクションのリソースのリスト内で、リクエストを開始する位置を指定します。

問合せパラメータは通常、検索メソッドで使用されます。

GET: 検索結果のフィルタ用。「GETでの問合せパラメータ」を参照してください。
POST: リクエスト本文にパラメータを使用した検索結果のフィルタ用(セキュリティ上の理由)。「POST/.searchリクエスト本文での問合せパラメータ」を参照してください。

GETでの問合せパラメータ

/Usersや/Groupsなどのリソース・エンドポイントでGETリクエストを使用して検索を実行する場合、問合せをURLに指定します。URLに(?)を追加し、その後に問合せを続けます。

ノート

URL内のASCII文字セット外の文字(空白や引用符など)は、URLエンコードする必要があります。URLエンコード文字の例が示されています。空白は+に置換され、引用符(")は%22に置換されます。

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

特定のユーザーに関連付けられているすべてのグループおよびAppRolesを検索するには:

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

POST /.searchリクエスト本文での問合せパラメータ

POSTリクエストを使用する検索は、/.searchで終わるリソース・エンドポイントに対して作成できます。この場合、リクエスト本文に問合せを挿入します。ユーザー名などの機密情報を検索するとき、その機密情報が他のデータとともに送信される場合は、セキュリティ上の理由からこのメソッドを使用します。

この例は、エンドポイント/Users/.searchで実行されるPOSTメソッドのリクエスト本文を示しています。displayNameがsmithで始まり、meta.resourceTypeがUser.に等しい最初の10のユーザー・エントリを返します

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

attributesパラメータは、DELETEを除くすべてのメソッドとともに使用できます。その他の問合せパラメータは検索メソッドでのみ有効で、その他のメソッドでは無視されます。


HTTP問合せパラメータ	説明
`attributes=attribute1,attribute2`	レスポンスで返されるリソース属性の名前を示す文字列の複数値リストを指定します。この問合せパラメータは、拡張スキーマIDも有効な属性名として受け入れます。属性に拡張スキーマIDを含めると、その中のすべてのデフォルト属性が返されます。
`attributeSets`	検索では、各属性を個別に指定するかわりに、レスポンス内の属性のグループが返されます。この問合せパラメータは、次のパラメータからカンマ区切りの値を受け入れます: all (すべての属性を返します) always (スキーマ内でalwaysとしてマークされているすべての属性を返します) default (すべてのデフォルト属性を返します) request (スキーマでrequestとしてマークされているすべての属性を返します) これらの値では大/小文字は区別されません。リクエストで`attributes`と`attributeSets`の両方を指定すると、両方の値がレスポンスに戻されます。
`count=N`	ページごとの検索結果の最大数を示します。レスポンスを取得する数を指定します。負の数を指定すると50にデフォルト設定され、最初の50のリソースが返されます。
`startIndex=N`	開始ページ索引を指定します。これは、最初の問合せ結果の1から始まる索引です。1未満の値は1と解釈されます。
`filter=Expression`	検索では、式がtrueである指定のエンドポイントのリソースをすべて返します。詳細は、フィルタ問合せパラメータの使用を参照してください。
`sortBy=attribute`	レスポンスのソート基準になる属性名を指定します。
`sortOrder=ascending` \| `sortOrder=descending`	`sortBy`パラメータが適用される順序を指定します。`sortBy`の値を指定し、`sortOrder`を指定しなかった場合、`sortOrder`はデフォルトで`ascending.`になります。

フィルタ問合せパラメータの使用

GETメソッドを使用して実行する検索で、filter問合せを使用できます。フィルタ問合せの形式は次のとおりです。

filter=Expression

フィルタには1つ以上の有効な式が含まれる必要があります。各式には属性名が含まれ、その後に属性演算子とオプション値が続きます。検索可能な属性はリソースによって異なります。この項では、GETリクエストについて説明します。

次のURLには、属性userNameにjensen:が含まれるユーザーのフィルタ問合せが含まれています。

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


属性演算子	説明	動作
`eq`	=	一致するには属性と演算子の値が等しい必要があります。
`ne`	以下	属性と演算子の値が一致しません。
`co`	内容	一致するには、演算子値全体が属性値のサブ文字列である必要があります。
`sw`	開始	演算子値全体が属性値のサブ文字列で、属性値の先頭から開始される必要があります。2つの文字列が等しい場合、この基準は満たされます。
`ew`	終了	演算子値全体が属性値のサブ文字列で、その演算子値が属性値の最後に一致する必要があります。2つの文字列が等しい場合、この基準は満たされます。
`pr`	次が存在(値がある)	属性に空でない値がある場合、または複合属性に空でないノードが含まれている場合は、一致があります。
`gt`	>	属性値が演算子値より大きい場合は一致になります。実際の比較は属性タイプによって決まります。文字列属性タイプの場合、これは辞書への掲載順に比較され、`DateTime`タイプの場合、時系列順に比較されます。
`ge`	以上	属性値が演算子値以上の場合は一致になります。実際の比較は属性タイプによって決まります。文字列属性タイプの場合、これは辞書への掲載順に比較され、`DateTime`タイプの場合、時系列順に比較されます。
`lt`	以下	属性値が演算子値未満の場合は一致になります。実際の比較は属性タイプによって決まります。文字列属性タイプの場合、これは辞書への掲載順に比較され、`DateTime`タイプの場合、時系列順に比較されます。
`le`	以下	属性値が演算子値以下の場合は一致になります。実際の比較は属性タイプによって決まります。文字列属性タイプの場合、これは辞書への掲載順に比較され、`DateTime`タイプの場合、時系列順に比較されます。

複数の式を結合するには、論理演算子andおよびorを使用し、その前に属性演算子not.を指定して式を否定します。優先グループにはカッコ()を使用し、複合属性のフィルタ・グループには角カッコ[]を使用します。

問合せパラメータ・フィルタの例

アイデンティティ・ドメイン内の問合せの開始点として、次の問合せパラメータの例を使用します。

ユーザーの例

属性userNameがexampleに等しいユーザーを検索するには、このフィルタを使用します。

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

このフィルタ例では、jensen:を含むuserNameを持つユーザーを検索します。

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

このフィルタ例では、exampleを含む、またはmy:で始まるuserNameを持つユーザーを検索します。

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

このフィルタ例では、jensen:を含むnameのfamilyNameサブ属性を持つユーザーを検索します。

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

この複雑なURL問合せの例は、userNameがexampleと等しいすべてのユーザーを返し、JSONレスポンス本文に属性emails.valueおよびname.familyNameをリストして、出力のページごとに最大8人のユーザーを返します。

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

このフィルタ例では、GETのフィルタ・パラメータを使用してユーザーを検索します。

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

このフィルタ例では、検索可能なカスタム属性Nicknameを持つユーザーを返します。検索可能なカスタム属性についてさらに学習するには、「ユーザー・スキーマのカスタマイズ」および「スキーマのカスタマイズ」を参照してください。

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

このフィルタ例では、検索可能なカスタム属性がテキスト文字列と一致するユーザーを返します。検索可能なカスタム属性についてさらに学習するには、「ユーザー・スキーマのカスタマイズ」および「スキーマのカスタマイズ」を参照してください。

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

電話番号の例

このフィルタ例では、電話番号が「+1」*で始まるユーザーを検索します。

ノート

POST操作でのみ機能します。


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

このフィルタ例では、自宅電話番号に文字列「503」が含まれるユーザーを検索します。


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\""
}


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\"]"
}

このフィルタ例では、電話番号のバリエーションがあるユーザーを検索します。

ノート

SCIMフィルタ・パラメータは、RegExパターンをサポートしていません。可能性のあるすべてのバリエーションが含まれている必要があります。次の例を使用して開始します。


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\""
}

アプリケーション・ロールの例

このフィルタの例では、特定のAppRoleを持つすべてのユーザーを検索します:

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

このフィルタ例では、approleidを使用してAppRoleのメンバーを返します。


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

このフィルタ例では、appidを使用する特定のアプリケーションのAppRolesを返します。


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

Oracle Cloud Infrastructureドキュメント