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

[アーティクル]
03/09/2023

Microsoft Graph はオプションのクエリパラメーターをサポートしており、応答で返されるデータの量を指定したり制御したりするために使用できます。正確なクエリパラメーターのサポートは、API 操作ごとに異なり、API によっては、v1.0 とベータ版エンドポイントかでも異なることがあります。

ヒント

ベータ版エンドポイントでは、$プレフィックスが省略可能です。たとえば、filter とせずに、$filter と指定することもできます。 v1 エンドポイントでは、API のサブセットに対してのみ$プレフィックスが省略可能です。要するに、v1 エンドポイントを使用している場合は、常に$が含まれます。

クエリパラメーターには、OData のシステムクエリオプションまたは他のクエリパラメーターを使用できます。

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

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

例をクリックして Graph エクスプローラーで試行します。

Name	説明	例
$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`

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

クエリパラメーターの値は、 RFC 3986 に従ってパーセントエンコードする必要があります。たとえば、クエリ文字列内のすべての予約文字はパーセントエンコードする必要があります。これを行う上で役立つ HTTP クライアント、ブラウザー、およびツールが多くあります (Graph エクスプローラーなど)。クエリが失敗する場合、クエリパラメーターの値が適切にエンコードされていないことがその原因の 1 つとして考えられます。場合によっては、値を二重エンコードする必要があります。

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFilter := "startswith(givenName,%20'J')"

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

result, err := graphClient.Users().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Users

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();

$queryParameters = new UsersRequestBuilderGetQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->get($requestConfiguration);

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFilter := "startswith(givenName,%20'J')"

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

result, err := graphClient.Users().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Users

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();

$queryParameters = new UsersRequestBuilderGetQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->get($requestConfiguration);

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("startswith(givenName, 'J')")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFilter := "startswith(givenName,%20'J')"

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

result, err := graphClient.Users().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Users

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();

$queryParameters = new UsersRequestBuilderGetQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->get($requestConfiguration);

一重引用符のエスケープ

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.filter("subject eq 'let''s meet for lunch?'")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFilter := "subject eq 'let''s meet for lunch?'"

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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?'"


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

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

$requestConfiguration->queryParameters = $queryParameters;


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

count パラメーター

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

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

注:

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

たとえば、次のような要求では、現在のユーザーの contact コレクションと、@odata.count プロパティ内の contact コレクションのアイテム数の両方が返されます。

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Count = true;
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

ContactCollectionPage contacts = graphClient.me().contacts()
	.buildRequest()
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestCount := true

requestParameters := &graphconfig.MeContactsRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphconfig.MeContactsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Contacts().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.PersonalContacts

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();

$queryParameters = new ContactsRequestBuilderGetQueryParameters();
$queryParameters->count = true;

$requestConfiguration->queryParameters = $queryParameters;


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

$count クエリパラメーターは、directoryObject から派生する、以下の頻繁に使用されるリソースのコレクションとそのリレーションシップでサポートされており、詳細クエリでのみサポートされます。

expand パラメーター

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

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

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

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

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.me().drive().root()
	.buildRequest()
	.expand("children")
	.get();

Snippet not available

Snippet not available

Snippet not available

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

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

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.me().drive().root()
	.buildRequest()
	.expand("children($select=id,name)")
	.get();

Snippet not available

Snippet not available

Snippet not available

注:

すべてのリレーションシップとリソースで、$expand クエリパラメーターがサポートされているわけではありません。たとえば、ユーザーの directReports、manager、および memberOf リレーションシップを展開することはできますが、そのイベント、メッセージ、または写真のリレーションシップを展開することはできません。すべてのリソースまたはリレーションシップで、$select を使用して展開されたアイテムがサポートされているわけではありません。
ユーザーやグループのような、directoryObject から派生した Azure AD リソースの場合、$expand は通常、展開されているリレーションシップに対し最大 20 個のアイテムを返し、@odata.nextLink はありません。その他の既知の問題を参照してください。
$expand は、現在、高度なクエリではサポートされていません。

filter パラメーター

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

format パラメーター

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

たとえば、次の要求では組織のユーザーが JSON 形式で返されます。

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Format = "json";
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFormat := "json"

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Format: &requestFormat,
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Users

Get-MgUser -Format "json"


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();

$queryParameters = new UsersRequestBuilderGetQueryParameters();
$queryParameters->format = "json";

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->get($requestConfiguration);

注:

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

orderby パラメーター

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

たとえば、次の要求では組織のユーザーが表示名順で返されます。

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.orderBy("displayName")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
	Orderby: [] string {"displayName"},
}
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Users().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Users

Get-MgUser -Sort "displayName"


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();

$queryParameters = new UsersRequestBuilderGetQueryParameters();
$queryParameters->orderby = ["displayName"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->users()->get($requestConfiguration);

複合型のエンティティでも並べ替えが可能です。次の要求は、メッセージを取得し、複合型 emailAddress の from プロパティのアドレス フィールドで並べ替えます。

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.orderBy("from/emailAddress/address")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Mail

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

$queryParameters = new MessagesRequestBuilderGetQueryParameters();
$queryParameters->orderby = ["from/emailAddress/address"];

$requestConfiguration->queryParameters = $queryParameters;


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

昇順または降順で結果を並べ替えるには、asc または desc のいずれかをスペースで区切ってフィールド名の後に追加します。たとえば ?$orderby=name%20desc のようにします。順序が指定されていない場合、既定値 (昇順) が考慮されます。

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().mailFolders("Inbox").messages()
	.buildRequest()
	.orderBy("from/emailAddress/name desc,subject")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestParameters := &graphconfig.MeMailFolderItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphconfig.MeMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().MailFoldersById("mailFolder-id").Messages().Get(context.Background(), configuration)


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"


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

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

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->me()->mailFoldersById('mailFolder-id')->messages()->get($requestConfiguration);

注:

$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


var graphClient = new GraphServiceClient(requestAdapter);

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" };
});


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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.filter("Subject eq 'welcome' and importance eq 'normal'")
	.orderBy("subject,importance,receivedDateTime desc")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestFilter := "Subject eq 'welcome' and importance eq 'normal'"

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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"


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

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

$requestConfiguration->queryParameters = $queryParameters;


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

注:

$orderby と $filter のクエリパラメーターの組み合わせは、ディレクトリオブジェクトでサポートされています。 Azure AD ディレクトリオブジェクトの詳細クエリ機能をご覧ください。

search パラメーター

$search クエリパラメーターを使用して、要求の結果を検索条件と一致するものに制限します。その構文と動作は、API 操作ごとに異なります。さまざまなリソースにわたる $search の構文を確認するには、「$search クエリパラメーターを使用して検索条件に一致させる」を参照してください。

select パラメーター

$select クエリパラメーターを使用して、個別リソースまたはリソースのコレクションの既定値とは異なるプロパティのセットを返します。 $select で、既定のプロパティのサブセットまたはスーパーセットを指定できます。

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.select("from,subject")
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"from","subject"},
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Mail

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

$queryParameters = new MessagesRequestBuilderGetQueryParameters();
$queryParameters->select = ["from","subject"];

$requestConfiguration->queryParameters = $queryParameters;


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

重要

通常は、$select を使用して、クエリから返されるプロパティをお使いのアプリで必要なものだけに制限することをお勧めします。これは特に、クエリが大きな結果セットを返す可能性がある場合に該当します。行ごとに返されるプロパティを制限すれば、ネットワークの負荷を軽減し、アプリのパフォーマンスを向上させることができます。

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

skip パラメーター

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Events.GetAsync((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();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

EventCollectionPage events = graphClient.me().events()
	.buildRequest()
	.orderBy("createdDateTime")
	.skip(20)
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestSkip := int32(20)

requestParameters := &graphconfig.MeEventsRequestBuilderGetQueryParameters{
	Orderby: [] string {"createdDateTime"},
	Skip: &requestSkip,
}
configuration := &graphconfig.MeEventsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Events().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Calendar

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new EventsRequestBuilderGetRequestConfiguration();

$queryParameters = new EventsRequestBuilderGetQueryParameters();
$queryParameters->orderby = ["createdDateTime"];
$queryParameters->skip = 20;

$requestConfiguration->queryParameters = $queryParameters;


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

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

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

skipToken パラメーター

要求の中には、サーバー側のページングを使用したり、応答におけるページサイズを限定するために $top パラメーターを使用したりすることによって、複数のデータページを返すものがあります。 Microsoft Graph API の多くは、skipToken クエリパラメーターを使用して、結果の後続のページを参照します。
$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


var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Top = 5;
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
	.buildRequest()
	.top(5)
	.get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestTop := int32(5)

requestParameters := &graphconfig.MeMessagesRequestBuilderGetQueryParameters{
	Top: &requestTop,
}
configuration := &graphconfig.MeMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.Me().Messages().Get(context.Background(), configuration)


Import-Module Microsoft.Graph.Mail

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();

$queryParameters = new MessagesRequestBuilderGetQueryParameters();
$queryParameters->top = 5;

$requestConfiguration->queryParameters = $queryParameters;


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

注:

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

一部の要求では、指定したクエリパラメーターがサポートされていない場合にエラーメッセージが返されます。たとえば、リレーションシップでは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"
        }
    }
}

ただし、要求で指定されたクエリパラメーターが警告なしで失敗する可能性があるため、注意が必要です。これは、クエリパラメーターがサポートされていない場合や、クエリパラメーターの組み合わせがサポートされていない場合に起こり得ます。その場合、要求によって返されたデータを調べ、指定したクエリパラメーターに期待どおりの効果があったかどうかを確認する必要があります。

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

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

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

その他の OData URL の機能

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

一重引用符のエスケープ

count パラメーター

expand パラメーター

filter パラメーター

format パラメーター

orderby パラメーター

search パラメーター

select パラメーター

skip パラメーター

skipToken パラメーター

top パラメーター

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

関連項目

その他のリソース

その他のリソース

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

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

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

その他の OData URL の機能

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

一重引用符のエスケープ

count パラメーター

expand パラメーター

filter パラメーター

format パラメーター

orderby パラメーター

search パラメーター

select パラメーター

skip パラメーター

skipToken パラメーター

top パラメーター

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

関連項目

その他のリソース

その他のリソース

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

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

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

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

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