$filter クエリ パラメーターを使用する

Microsoft Graph では、コレクションのサブセットを取得するために、 $filterOData クエリ パラメーターがサポートされています。

$filterで指定された式はコレクション内の各リソースに対して評価され、式がtrueと評価される項目のみが応答に含まれます。 式が false または nullに評価されるリソース、またはアクセス許可のために使用できない参照プロパティは、応答から省略されます。

$filter クエリ パラメーターは、メンバーmemberOftransitiveMembers、transitiveMemberOf などのリレーションシップに対しても適用できます。 たとえば、"自分がメンバーになっているすべてのセキュリティ グループを取得する" とします。

フィルター式でサポートされる演算子と関数

Microsoft Graph では、次の演算子と関数の使用がサポートされています。 ただし、個々のリソースとそのプロパティまたはリレーションシップによるサポートは異なる場合があります。 さらに、一部のプロパティとリレーションシップでは、高度なクエリでのみ$filterがサポートされます。 詳細については、特定のリソース ドキュメントを参照し、これらの演算子と関数を使用する方法の例については、 フィルター OData クエリ パラメーター を使用するための構文を参照してください。

演算子の種類 オペレーター
近接演算子
  • 等しい (eq)
  • 等しくない (ne)
  • 論理否定 ( not )
  • 次に含まれる (in)
  • Has (has)


手記:in演算子を使用する場合、要求は既定でフィルター句の 15 式に制限され、高度なクエリ機能を使用する場合は URL の長さが 2,048 文字に制限されます。
関係演算子
  • 未満 (lt)
  • より大きい (gt)
  • 以下 (le)
  • 以上 (ge)
ラムダ演算子
  • 任意 (any)
  • すべて (all)
条件演算子
  • および (and)
  • または (or)
Functions
  • 次で始まる (startswith)
  • 次で終わる ( endswith )
  • 次を含む (contains)

ラムダ演算子を使用したフィルター

OData は、複数値プロパティの一致を評価する any 演算子と all 演算子 (String 型などのプリミティブ値のコレクションまたはリソースのコレクション) を定義します。

any 演算子

any演算子は、コレクションの各項目にブール式を反復的に適用し、式がコレクションの少なくとも 1 つの項目に対してtrueされている場合はtrueを返します。それ以外の場合は、falseを返します。 次のクエリ文字列は、 any 演算子の構文を示しています。

$filter=collection/any(property:property/subProperty eq 'value-to-match')

場所

  • collection は、値のコレクションまたは複雑なプロパティのコレクションを含むプロパティです。
  • property:property は、イテレーション中にコレクションの現在の要素を保持する範囲変数です。 この変数には、 p:p など、ほぼすべての名前を付けることができます。
  • subProperty は、クエリがエンティティのコレクションに適用される場合に必要です。 これは、一致する値を持つ複合型のプロパティを表します。
  • value-to-match は、一致 するコレクションのメンバーを表します。

C#LINQの同等の構文は次のとおりです。

collection.Any(property => property.subProperty == "value-to-match")

たとえば、user リソースの imAddresses プロパティには、String プリミティブ型のコレクションが含まれています。 次のクエリでは、少なくとも 1 つの imAddress の admin@contoso.comを持つユーザーのみが取得されます。

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(i:i eq 'admin@contoso.com')

user リソースの assignedLicenses プロパティには、assignedLicense オブジェクトのコレクションが含まれています。これは、skuIddisabledPlans という 2 つのプロパティを持つ複合型です。 次のクエリでは、 skuId184efa21-98c3-4e5d-95ab-d07053a96e67 によって識別された少なくとも 1 つの割り当て済みライセンスを持つユーザーのみを取得します。

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

any 句内の式の結果を否定するには、ne 演算子ではなく not 演算子を使用します。 たとえば、次のクエリでは、admin@contoso.comの imAddress が割り当てられていないユーザーのみが取得されます。

注: ユーザーなどのディレクトリ オブジェクトの場合、not演算子とne演算子は、高度なクエリでのみサポートされます。

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

all 演算子

all演算子は、コレクションの各メンバーにブール式を適用し、式がコレクションのすべての項目に対してtrueされている場合はtrueを返します。それ以外の場合は、falseを返します。 現時点では、Microsoft Graph ではサポートされていません。

フィルター クエリ 演算子を使用した例

次の表では、$filter クエリ パラメーターの使用例を示します。 詳細については、 OData プロトコルに関するページを参照してください。

注:

説明
複数のプロパティ間で Mary という名前を持つすべてのユーザーを取得します。 GET~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
メール ドメインが 'hotmail.com' と等しいすべてのユーザーを取得する 取得~/users?$count=true&$filter=endswith(mail,'@hotmail.com') **
ライセンスを割り当てられていないすべてのユーザーを取得する 取得~/users?$filter=assignedLicenses/$count eq 0&$count=true **
2017 年 7 月 1 日以降に開始する、サインイン ユーザーのイベントすべてを取得します。 GET~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'
手記: イベント エンティティの dateTime プロパティは String 型です。
サインイン ユーザーが受信した特定のアドレスからの電子メールすべてを取得します。 GET~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
2017 年 4 月にサインイン ユーザーが受信した電子メールすべてを取得します。 GET~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
サインイン ユーザーの受信トレイから未読メールをすべて取得します。 GET~/me/mailFolders/inbox/messages?$filter=isRead eq false
小売部門と販売部門のすべてのユーザーを取得します。 GET~/users?$filter=department in ('Retail', 'Sales')
一時停止状態にある特定のサービス プランを持つユーザーを一覧表示します。 取得~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true **
組織内のすべての Microsoft 365 以外のグループを一覧表示します。 取得~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true **
会社名が定義されていない (つまり、 null 値ではない) または Microsoft のすべてのユーザーを一覧表示します。 取得~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true **
会社名が未定義または Microsoft のいずれかであるすべてのユーザーを一覧表示します。 取得~/users?$filter=companyName in (null, 'Microsoft')&$count=true **
OData キャストを使用して、返されたオブジェクト数を含む、「a」で始まる表示名のグループの推移性のメンバーシップを取得します。 取得~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a') **

フィルター OData クエリ パラメーターを使用するための構文

次の記事では、 $filter OData クエリ パラメーターとその関連演算子を使用するための構文を示します。 この例はガイダンス専用に提供されており、 $filterのアプリケーションに関する包括的な一覧は反映されていません。

注:

  • GUID と DateTimeOffset の値は、 $filter 式では引用符で囲まれません。

** : この例は、 高度なクエリ機能でのみサポートされています。

String、Int、日付などの単一のプリミティブ型の場合

オペレーター 構文
eq ~/users?$filter=userType eq 'Member'
not ~/users?$filter=not(userType eq 'Member') **
ne ~/users?$filter=companyName ne null **
startswith ~/users?$filter=startswith(userPrincipalName, 'admin')
endswith ~/users?$filter=endswith(mail,'@outlook.com') **
in ~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')

手記:in演算子を使用するクエリ文字列の場合、要求は既定でフィルター句の 15 式に制限され、高度なクエリ機能を使用する場合は URL の長さが 2,048 文字に制限されます。
le ~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z **
ge ~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z **
notendswith ~/users?$filter=not(endswith(mail, 'contoso.com')) **
not ~/users?$filter=not(startswith(mail, 'A')) **
not ~/users?$filter=not(companyName eq 'Contoso E.A.') **
notin ~/users?$filter=not(userType in ('Member')) **
contains ~/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, './members')
has ~/identity/conditionalAccess/templates?$filter=scenarios has 'secureFoundation'

プリミティブ型のコレクションの場合

演算子 (s) 構文
eq ~/groups?$filter=groupTypes/any(c:c eq 'Unified')
not ~/groups?$filter=not(groupTypes/any(c:c eq 'Unified')) **
ne ~/users?$filter=companyName ne null **
startswith ~/users?$filter=businessPhones/any(p:startswith(p, '44')) **
endswith ~/users?$filter=endswith(mail,'@outlook.com') **
notendswith ~/groups?$filter=not(endswith(mail,'contoso.com')) **
not ~/groups?$filter=not(startswith(mail,'Pineview')) **
noteq ~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com') **
eqおよび 空のコレクションの$count ~/users?$filter=assignedLicenses/$count eq 0 **
neおよび 空のコレクションの$count ~/users?$filter=assignedLicenses/$count ne 0 **
notおよび 空のコレクションの$count ~/users?$filter=not(assignedLicenses/$count eq 0) **
$count 1 つのオブジェクトを持つコレクションの場合 ~/servicePrincipals?$filter=owners/$count eq 1 **

GUID 型の場合

演算子 (s) 構文
eq ~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47 **
not ~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47) **

GUID 型のコレクションの場合

演算子 (s) 構文
eq ~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2) **
le ~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2) **
ge ~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2) **

複合型のコレクションの場合

演算子 (s) 構文
eq ~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil') **
noteq ~/users?$filter=not(certificateUserIds/any(x:x eq '9876543210@mil')) **
startswith ~/users?$filter=certificateUserIds/any(x:startswith(x,'987654321')) **
endswith ~/users?$filter=proxyAddresses/any(p:endswith(p,'contoso.com')) **