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

  • [アーティクル]

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

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

クエリ パラメーターは$filter、メンバー、memberOf、transitiveMembers、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 は、一致 するコレクションのメンバーを表します。

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

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

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

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

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

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

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

注: ユーザーなどのディレクトリ オブジェクトの場合、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 **
会社名が定義されていない (つまり、値ではない) または Microsoft のすべてのユーザーを null 一覧表示します。 取得~/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 クエリ パラメーターを使用するための構文

次の記事では、OData クエリ パラメーターとその関連演算子を $filter 使用するための構文を示します。 この例はガイダンス専用に提供されており、 のアプリケーション $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 **
not と endswith ~/users?$filter=not(endswith(mail, 'contoso.com')) **
not ~/users?$filter=not(startswith(mail, 'A')) **
not ~/users?$filter=not(companyName eq 'Contoso E.A.') **
not と in ~/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') **
not と endswith ~/groups?$filter=not(endswith(mail,'contoso.com')) **
not ~/groups?$filter=not(startswith(mail,'Pineview')) **
not と eq ~/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') **
not と eq ~/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')) **

関連コンテンツ