$filter クエリ パラメーターを使用する
[アーティクル]
04/19/2024
5 人の共同作成者
フィードバック
この記事の内容
Microsoft Graph では、コレクションのサブセットを取得するために、 $filter
OData クエリ パラメーターがサポートされています。
$filter
で指定された式はコレクション内の各リソースに対して評価され、式がtrue
と評価される項目のみが応答に含まれます。 式が false
または null
に評価されるリソース、またはアクセス許可のために使用できない参照プロパティは、応答から省略されます。
$filter
クエリ パラメーターは、メンバー 、memberOf 、transitiveMembers、transitiveMemberOf などのリレーションシップに対しても 適用できます。 たとえば、"自分がメンバーになっているすべてのセキュリティ グループを取得する" とします。
フィルター式でサポートされる演算子と関数
Microsoft Graph では、次の演算子と関数の使用がサポートされています。 ただし、個々のリソースとそのプロパティまたはリレーションシップによるサポートは異なる場合があります。 さらに、一部のプロパティとリレーションシップでは、高度なクエリ でのみ$filter
がサポートされます。 詳細については、特定のリソース ドキュメントを参照し、これらの演算子と関数を使用する方法の例については、 フィルター OData クエリ パラメーター を使用するための構文を参照してください。
演算子の種類
オペレーター
近接演算子
等しい (eq
) 等しくない (ne
) 論理否定 ( not
) 次に含まれる (in
) Has (has
)
手記: in
演算子を使用する場合、要求は既定でフィルター句の 15 式に制限され、高度なクエリ機能 を使用する場合は URL の長さが 2,048 文字に制限されます。
関係演算子
未満 (lt
) より大きい (gt
) 以下 (le
) 以上 (ge
)
ラムダ演算子
条件演算子
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')";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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')";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.filter('imAddresses/any(i:i eq \'admin@contoso.com\')')
.get();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?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();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
graph_client = GraphServiceClient(credentials, scopes)
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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
user
リソースの assignedLicenses プロパティには、assignedLicense オブジェクトのコレクションが含まれています。これは、skuId と disabledPlans という 2 つのプロパティを持つ複合型です。 次のクエリでは、 skuId 184efa21-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)";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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)";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
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();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?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();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
graph_client = GraphServiceClient(credentials, scopes)
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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
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
// 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");
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// 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");
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
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();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?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();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" -CountVariable CountVar -ConsistencyLevel eventual
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
graph_client = GraphServiceClient(credentials, scopes)
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)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
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
**
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'))
**
関連コンテンツ