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

2024-12-30

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

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

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

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

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

演算子の種類	オペレーター
近接演算子	等しい (`eq`) 等しくない (`ne`) 論理否定 ( `not` ) 次に含まれる (`in`) Has (`has`) 手記：`in`演算子と`eq`演算子の制限事項については、既知の問題のクエリパラメーターの制限事項に関するページを参照してください。
関係演算子	未満 (`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')


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestFilter := "imAddresses/any(i:i eq 'admin@contoso.com')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('imAddresses/any(i:i eq \'admin@contoso.com\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "imAddresses/any(i:i eq 'admin@contoso.com')"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "imAddresses/any(i:i eq 'admin@contoso.com')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

user リソースの assignedLicenses プロパティには、assignedLicense オブジェクトのコレクションが含まれています。これは、skuId と disabledPlans という 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)


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestFilter := "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))"
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('NOT(imAddresses/any(i:i eq \'admin@contoso.com\'))')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))",
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

`all` 演算子

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

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

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

注:

^**でマークされた例は、高度なクエリ機能でのみサポートされます。
HTTP メソッドをクリックして、Graph エクスプローラーの例を試します。

説明	例
複数のプロパティ間で 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'` `~/groups?$filter=isAssignableToRole eq true`
`not`	`~/users?$filter=not(userType eq 'Member')`^**
`ne`	`~/users?$filter=companyName ne null`^ `~/groups?$filter=isAssignableToRole ne true`^
`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`演算子と`eq`演算子の制限事項については、既知の問題のクエリパラメーターの制限事項に関するページを参照してください。
`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'))`^**

ディレクトリオブジェクトに対する高度なクエリ機能

次の方法で共有

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

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

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

any 演算子

all 演算子

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

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