問合せパラメータ

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

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

問合せを使用して、出力にフィルタを適用できます。

ノート

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

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

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

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リクエスト本文を使用した問合せパラメータ

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

この例は、エンドポイント/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

このフィルタの例は、userNameにexampleが含まれるか、はmyで始まるユーザーを検索します:

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

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

このフィルタの例では、特定のアプリケーション・ロールを持つすべてのユーザーを検索します:

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ドキュメント