クエリパラメーターを使用して Microsoft Graph 応答をカスタマイズする

2025-07-02

クエリパラメーターは、返されるデータを正確に制御することで、Microsoft Graph API応答を最適化するのに役立ちます。使用可能なすべてのプロパティとデータを取得する代わりに、クエリパラメーターを使用して次のことができます。

必要なレコードのみを取得するために結果をフィルター処理する
特定のプロパティを選択して応答サイズを小さくし、パフォーマンスを向上させる
ユーザーエクスペリエンスを向上させるデータの並べ替えとページ分割
関連リソースを拡張して、1 つの要求で接続されたデータを取得する

この記事では、 OData システムクエリオプションやその他の Microsoft Graph クエリパラメーターを効果的に使用する方法について説明します。構文を学習し、実際の例を参照し、アプリケーションのパフォーマンスを向上させる効率的なクエリを構築するためのベストプラクティスを確認します。

特定のクエリパラメーターのサポートは API 操作によって異なり、 v1.0 エンドポイントと ベータ エンドポイントによって異なる場合があります。

ヒント

ベータ エンドポイントでは、$ プレフィックスは省略可能です。たとえば、$filter とせずに、filter と指定することもできます。 v1.0 エンドポイントでは、$ プレフィックスは API のサブセットに対してのみ省略可能です。 わかりやすくするために、常にすべてのバージョンに $ を含めます。

OData のシステムクエリオプション

Microsoft Graph API 操作は、次の OData のシステムクエリオプションの 1 つ以上をサポートする可能性があります。これらのクエリオプションは OData V4 クエリ言語と互換性があり、 GET 操作でのみサポートされます。

Graph エクスプローラーで試す例を選択します。

名前	説明	例
$count	一致するリソースの合計数を返します。	`/me/messages?$top=2&$count=true`
$expand	関連リソースを返します。	`/groups?$expand=members`
$filter	結果 (行) をフィルターします。	`/users?$filter=startswith(givenName,'J')`
$format	指定したメディア形式で結果を返します。	`/users?$format=json`
$orderby	結果を並べます。	`/users?$orderby=displayName desc`
$search	検索条件に基づいて結果を返します。	`/me/messages?$search=pizza`
$select	プロパティ (列) をフィルターします。	`/users?$select=givenName,surname`
$skip	結果セット内の項目をスキップします。また、ページングを実装するために一部の API で使用され、 `$top` で使用して結果を手動でページできます。	`/me/messages?$skip=11`
$top	結果のページサイズを設定します。	`/users?$top=2`

API とそのプロパティがサポートする OData システムクエリオプションを見つけるには、リソースページの "プロパティ" テーブルと、API の LIST 操作と GET 操作の "省略可能なクエリパラメーター" セクションを参照してください。

その他のクエリパラメーター

名前	説明	例
$skipToken	複数のページにまたがる結果セットの結果の次のページを返します。 (一部の API では、代わりに `$skip` を使用します)。	`/users?$skiptoken=X%274453707402000100000017...`

その他の OData URL の機能

次の OData 4.0 の機能は、クエリパラメーターではなく URL セグメントです。

Name	説明	例
$count	コレクションの整数の合計を返します。	`GET /users/$count` `GET /groups/{id}/members/$count` ユーザー数を取得する
$ref	コレクションに対するエンティティメンバーシップーを更新します。	`POST /groups/{id}/members/$ref` グループにメンバーを追加する
$value	項目のバイナリ値を取得または更新します。	`GET /me/photo/$value` ユーザー、グループ、またはチームの写真を取得する
$batch	複数の HTTP 要求をバッチ要求に結合します。	`POST /$batch` JSON バッチ処理

クエリパラメーターのエンコード

RFC 3986 に従ってクエリパラメーターの値をパーセントエンコードします。クエリ文字列内のすべての予約文字は、パーセントエンコードする必要があります。多くの HTTP クライアント、ブラウザー、ツール (Graph エクスプローラーなど) がこのエンコードを自動的に処理します。クエリが失敗した場合、クエリパラメーターの値を適切にエンコードできない可能性があります。場合によっては、値を二重エンコードする必要があります。

注:

v1.0 エンドポイントの$search式でアンパサンド (&) シンボルをエンコードする際に既知の問題があります。この問題と推奨される回避策の詳細については、「既知の問題: エンコードされたアンパサンド (&) 文字でディレクトリオブジェクトの$searchが失敗する」を参照してください。

たとえば、エンコードされていない URL は次のようになります。

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')


// 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 = "startswith(givenName, 'J')";
});



mgc users list --filter "startswith(givenName, 'J')"



// 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 := "startswith(givenName, 'J')"

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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.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 = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


# 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 = "startswith(givenName, 'J')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

正しくエンコードされた URL は次のようになります。

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')


// 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 = "startswith(givenName, 'J')";
});



mgc users list --filter "startswith(givenName, 'J')"



// 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 := "startswith(givenName, 'J')"

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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.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 = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


# 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 = "startswith(givenName, 'J')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

二重エンコード URL は次のようになります。

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29


// 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 = "startswith(givenName, 'J')";
});



mgc users list --filter "startswith(givenName, 'J')"



// 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 := "startswith(givenName, 'J')"

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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.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 = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


# 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 = "startswith(givenName, 'J')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

一重引用符のエスケープ

単一引用符を使用する要求の場合、パラメーター値に単一引用符も含まれている場合は、二重エスケープする必要があります。それ以外の場合、構文が無効なため、要求は失敗します。この例では、文字列値の let''s meet for lunch? では一重引用符がエスケープされています。

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'


// 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.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});



mgc users messages list --user-id {user-id} --filter "subject eq 'let''s meet for lunch?'"



// 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 := "subject eq 'let''s meet for lunch?'"

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('subject eq \'let\'\'s meet for lunch?\'')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "subject eq 'let''s meet for lunch?'";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "subject eq 'let''s meet for lunch?'"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		filter = "subject eq 'let''s meet for lunch?'",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

カウント

$count クエリパラメーターを使用して、コレクション内または式に一致する項目の合計数を取得します。 $countは、次の方法で使用できます。

構文を持つクエリ文字列パラメーターとして、コレクション内のアイテムの合計数と Microsoft Graph から返されるデータ値のページを含める $count=true 。たとえば、「 users?$count=true 」のように入力します。
コレクションの整数の合計のみを取得する URL セグメントとして。たとえば、「 users/$count 」のように入力します。
等値演算子を持つ $filter 式では、フィルター処理されたプロパティが空のコレクションであるデータのコレクションを取得します。「 $filter クエリパラメーターを使用してオブジェクトのコレクションをフィルター処理する」を参照してください。

注:

directoryObject から派生したリソースでは、$count は詳細クエリでのみサポートされます。ディレクトリオブジェクトの高度なクエリ機能に関するページを参照してください。
Azure AD B2C テナントでは、 $count の使用はサポートされていません。

たとえば、次の要求は、現在のユーザーの連絡先コレクションと、@odata.count プロパティの連絡先コレクション内のアイテムの数の両方を返します。

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true


// 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.Me.Contacts.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Count = true;
});



mgc users contacts list --user-id {user-id} --count "true"



// 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
)


requestCount := true

requestParameters := &graphusers.ItemContactsRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphusers.ItemContactsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
	requestConfiguration.queryParameters.count = true;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let contacts = await client.api('/me/contacts')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Contacts\ContactsRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.PersonalContacts

# A UPN can also be used as -UserId.
Get-MgUserContact -UserId $userId -CountVariable CountVar


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.contacts.contacts_request_builder import ContactsRequestBuilder
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 = ContactsRequestBuilder.ContactsRequestBuilderGetQueryParameters(
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.contacts.get(request_configuration = request_configuration)

ディレクトリオブジェクト ( つまり、directoryObject から派生するリソース) の場合、 $count クエリパラメーターは高度なクエリでのみサポートされます。

展開

Microsoft Graph リソースの多くは、宣言されているリソースのプロパティと、他のリソースとのリレーションシップの両方を公開します。これらのリレーションシップは、参照プロパティまたはナビゲーションプロパティとも呼ばれ、1 つのリソースまたはリソースのコレクションのいずれかを参照することができます。たとえば、ユーザーのメールフォルダー、マネージャー、直属の部下は、すべてリレーションシップとして公開されます。

$expand クエリ文字列パラメーターを使用して、展開されているリソース、または単一のリレーションシップ (ナビゲーションプロパティ) で参照されているコレクションを結果に含めることができます。一部の API では、1 つの要求で展開できるリレーションシップは 1 つだけです。

次の例では、ドライブ内のトップレベルの子項目と共に、ルートドライブ情報を取得します。

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children


// 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.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});



mgc drives root get --drive-id {drive-id} --expand "children"



// 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"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.ItemRootRequestBuilderGetQueryParameters{
	Expand: [] string {"children"},
}
configuration := &graphdrives.ItemRootRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"children"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Root\RootRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new RootRequestBuilderGetRequestConfiguration();
$queryParameters = RootRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["children"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->root()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
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 = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
		expand = ["children"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)

一部のリソースコレクションでは、 $select パラメーターを追加することで、展開されたリソースで返されるプロパティを指定することもできます。次の例では、前の例と同じクエリを実行しますが、 $select ステートメントを使用して、展開された子項目に対して返されるプロパティを id プロパティと name プロパティに制限します。

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)


// 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.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "children($select=id,name)" };
});



mgc drives root get --drive-id {drive-id} --expand "children(\$select=id,name)"



// 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"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.ItemRootRequestBuilderGetQueryParameters{
	Expand: [] string {"children($select=id,name)"},
}
configuration := &graphdrives.ItemRootRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children($select=id,name)')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Root\RootRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new RootRequestBuilderGetRequestConfiguration();
$queryParameters = RootRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["children(\$select=id,name)"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->root()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children(`$select=id,name)"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
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 = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
		expand = ["children($select=id,name)"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)

注:

すべてのリレーションシップとリソースで、$expand クエリパラメーターがサポートされているわけではありません。たとえば、ユーザーの directReports、 manager、 memberOf リレーションシップを展開することはできますが、 そのイベント、 メッセージ、写真のリレーションシップを展開することはできません。すべてのリソースまたはリレーションシップで、$select を使用して展開されたアイテムがサポートされているわけではありません。
ユーザーやグループなど、directoryObject から派生するMicrosoft Entraリソースでは、通常、展開されたリレーションシップに対 $expandして最大 20 個の項目が返され、@odata.nextLink はありません。詳細については、「クエリパラメーターの制限事項」を参照してください。
$expand は現在、高度なクエリではサポートされていません。

Filter

コレクションのサブセットのみを取得するには、 $filter クエリパラメーターを使用します。 $filterの使用に関するガイダンスについては、「$filter クエリパラメーターを使用してオブジェクトのコレクションをフィルター処理する」を参照してください。

フォーマット

$format クエリパラメーターを使用して、Microsoft Graph から返される項目のメディア形式を指定します。

たとえば、次の要求は、JSON 形式のorganizationのユーザーを返します。

GET https://graph.microsoft.com/v1.0/users?$format=json


// 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.Format = "json";
});



mgc users list



// 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
)


requestFormat := "json"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Format: &requestFormat,
}
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.format = "json";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();


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


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->format = "json";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Format "json"


# 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(
		format = "json",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

注:

$format クエリパラメーターでは、多くの形式 (atom、xml、jsonなど) がサポートされていますが、結果がすべての形式で返されるわけではありません。

並べ替え

$orderby クエリパラメーターを使用して、Microsof Graph から返される項目の並べ替え順序を指定します。既定の順序は昇順です。

たとえば、次の要求は、表示名で昇順に並べ替えられたorganizationのユーザーを返します。

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName


// 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.Orderby = new string []{ "displayName" };
});



mgc users list --orderby "displayName"



// 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
)

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Orderby: [] string {"displayName"},
}
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.orderby = new String []{"displayName"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.orderby('displayName')
	.get();


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


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Sort "displayName"


# 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(
		orderby = ["displayName"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

一部の API では、複合型エンティティによる並べ替えがサポートされています。次の要求は、メッセージを取得し、複合型 emailAddress の from プロパティのアドレス フィールドで並べ替えます。

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address


// 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.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});



mgc users messages list --user-id {user-id} --orderby "from/emailAddress/address"



// 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
)

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/address"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.orderby('from/emailAddress/address')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/address"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Sort "from/emailAddress/address"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		orderby = ["from/emailAddress/address"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

結果を昇順または降順で並べ替えるには、フィールド名に asc または desc をスペースで区切って追加します (たとえば、 ?$orderby=name desc (エンコードされていない)、 ?$orderby=name%20desc (URL エンコード)。並べ替え順序を指定しない場合、昇順が推論されます。

一部の API では、複数のプロパティの結果を並べ替えることができます。たとえば、次のような要求ではユーザーの受信トレイ内のメッセージを、最初は送信者の名前で降順に並べ替え (Z から A)、次に件名で昇順 (既定) に並べ替えます。

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject


// 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.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});



mgc users mail-folders messages list --user-id {user-id} --mail-folder-id {mailFolder-id} --orderby "from/emailAddress/name desc,subject"



// 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
)

requestParameters := &graphusers.MailFoldersItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphusers.MailFoldersItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/mailFolders/Inbox/messages')
	.orderby('from/emailAddress/name desc,subject')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/name desc","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->mailFolders()->byMailFolderId('mailFolder-id')->messages()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		orderby = ["from/emailAddress/name desc","subject"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.mail_folders.by_mail_folder_id('mailFolder-id').messages.get(request_configuration = request_configuration)

注:

$filterを指定すると、サービスは結果の並べ替え順序を推論します。メッセージを取得するために$orderby と $filter の両方を使用する場合は、サーバーでは常に $filter の結果の並べ替え順序が考慮されるため、特定の方法でプロパティを指定する必要があります。

次の例は、Subject と Importance の両方のプロパティでフィルター処理されてから、Subject、Importance、receivedDateTime の各プロパティで降順で並べ替えられたクエリを示しています。

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc


// 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.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
	requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});



mgc users messages list --user-id {user-id} --filter "Subject eq 'welcome' and importance eq 'normal'" --orderby "subject,importance,receivedDateTime desc"



// 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 := "Subject eq 'welcome' and importance eq 'normal'"

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "Subject eq 'welcome' and importance eq 'normal'";
	requestConfiguration.queryParameters.orderby = new String []{"subject", "importance", "receivedDateTime desc"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('Subject eq \'welcome\' and importance eq \'normal\'')
	.orderby('subject,importance,receivedDateTime desc')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "Subject eq 'welcome' and importance eq 'normal'";
$queryParameters->orderby = ["subject","importance","receivedDateTime desc"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "subject,importance,receivedDateTime desc"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		filter = "Subject eq 'welcome' and importance eq 'normal'",
		orderby = ["subject","importance","receivedDateTime desc"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

注:

$orderby と $filter のクエリパラメーターの組み合わせは、ディレクトリオブジェクトでサポートされています。ディレクトリオブジェクトの高度なクエリ機能に関するページを参照してください。

検索

$searchクエリパラメーターを使用して、要求の結果が検索条件に一致するように制限します。その構文と動作は、リソースによって異なります。詳細については、「 $search クエリパラメーターを使用して検索条件に一致する」を参照してください。

選択

$select クエリパラメーターを使用して、リソースのプロパティのサブセットを返します。 $select で、既定のプロパティのサブセットまたはスーパーセットを指定できます。

プロパティデータを制限するために$selectを使用せずに GET 要求を行う場合、Microsoft Graph には、次のような$selectを使用するためのベストプラクティスの推奨事項を提供する @microsoft.graph.tips プロパティが含まれています。

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

たとえば、サインインしているユーザーのメッセージを取得するときに、 from プロパティと subject プロパティのみを返すように指定できます。

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject


// 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.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});



mgc users messages list --user-id {user-id} --select "from,subject"



// 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
)

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"from","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.select('from,subject')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["from","subject"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "from,subject"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["from","subject"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

重要

$selectを使用して、クエリによって返されるプロパティをアプリで必要なプロパティに制限することをお勧めします。これは、大きな結果セットを返す可能性があるクエリに特に当てはまります。各行で返されるプロパティを制限すると、ネットワークの負荷が軽減され、アプリのパフォーマンスが向上します。

v1.0 では、ユーザーやグループなど、directoryObject から派生する一部のMicrosoft Entra リソースは、読み取り時にプロパティの制限された既定のサブセットを返します。これらのリソースでは、 $select を使用して、既定のセットの外部のプロパティを返す必要があります。

Skip

$skip クエリパラメーターを使用して、コレクションの開始時にスキップする項目の数を設定します。たとえば、次の要求は、作成された日付で並べ替えられたユーザーのイベントを、コレクション内の 21 番目のイベントから返します。

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20


// 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.Me.Events.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
	requestConfiguration.QueryParameters.Skip = 20;
});



mgc users events list --user-id {user-id} --skip "20" --orderby "createdDateTime"



// 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
)


requestSkip := int32(20)

requestParameters := &graphusers.ItemEventsRequestBuilderGetQueryParameters{
	Orderby: [] string {"createdDateTime"},
	Skip: &requestSkip,
}
configuration := &graphusers.ItemEventsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
	requestConfiguration.queryParameters.skip = 20;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let events = await client.api('/me/events')
	.orderby('createdDateTime')
	.skip(20)
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Events\EventsRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new EventsRequestBuilderGetRequestConfiguration();
$queryParameters = EventsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["createdDateTime"];
$queryParameters->skip = 20;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Calendar

# A UPN can also be used as -UserId.
Get-MgUserEvent -UserId $userId -Sort "createdDateTime" -Skip 20


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.events.events_request_builder import EventsRequestBuilder
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 = EventsRequestBuilder.EventsRequestBuilderGetQueryParameters(
		orderby = ["createdDateTime"],
		skip = 20,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.events.get(request_configuration = request_configuration)

Outlook のメールやカレンダーなど、いくつかの Microsoft Graph API (メッセージ、イベント、カレンダー) は、$skip を使用してページングを実装します。クエリの結果が複数のページにまたがる場合、これらの API は、$skip パラメーターを含む URL を持つ @odata.nextLink プロパティを返します。この URL を使用して、結果の次のページに戻れます。詳細については、「ページング」を参照してください。

ユーザー、グループ、アプリケーションなどのディレクトリオブジェクトは、$skipをサポートしていません。

SkipToken

一部の要求では、サーバー側のページングが原因で、または $top パラメーターを使用して応答のページサイズを制限するため、複数のページのデータが返されます。 Microsoft Graph API の多くは、skipToken クエリパラメーターを使用して、結果の後続のページを参照します。
このパラメーターには、結果の次のページを参照する不透明なトークンが含まれており、応答の @odata.nextLink プロパティに指定された URL で返されます。詳細については、「ページング」を参照してください。

注:

ディレクトリオブジェクトに対するクエリに OData Count を使用している場合 (クエリ文字列に $count=true を追加する場合)、@odata.count プロパティは最初のページにのみ存在します。

ディレクトリオブジェクトに対する高度なクエリに必要な ConsistencyLevel ヘッダーは、以降のページ要求には既定では含まれません。後続のページで明示的に設定する必要があります。

Top

$top クエリパラメーターを使用して、結果に含める項目の数を指定します。

結果セットにさらに項目が残っている場合、応答本文には @odata.nextLink パラメーターが含まれます。このパラメーターには、結果の次のページを取得するために使用できる URL が含まれています。詳細については、「ページング」を参照してください。

$top の最小値は 1 で、最大値は対応する API によって異なります。

たとえば、次の list messages 要求はユーザーのメールボックスの最初の 5 つのメッセージを返します。

GET https://graph.microsoft.com/v1.0/me/messages?$top=5


// 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.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Top = 5;
});



mgc users messages list --user-id {user-id} --top "5"



// 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
)


requestTop := int32(5)

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Top: &requestTop,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.top = 5;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.top(5)
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Top 5


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
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 = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		top = 5,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

注:

クエリパラメーターのエラー処理

一部の要求では、指定したクエリパラメーターがサポートされていない場合にエラーメッセージが返されます。たとえば、user/photoリレーションシップで$expandを使用することはできません。

https://graph.microsoft.com/v1.0/me?$expand=photo

{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

ただし、要求で指定されたクエリパラメーターがサイレントモードで失敗する場合があります。たとえば、クエリパラメーターがサポートされていない場合や、クエリパラメーターの組み合わせがサポートされていない場合です。その場合、要求によって返されたデータを調べ、指定したクエリパラメーターに期待どおりの効果があったかどうかを確認してください。

次の方法で共有

クエリ パラメーターを使用して Microsoft Graph 応答をカスタマイズする

OData のシステム クエリ オプション

その他のクエリ パラメーター