クエリ パラメーターを使用して応答をカスタマイズする
[アーティクル]
08/22/2023
21 人の共同作成者
フィードバック
この記事の内容
Microsoft Graph はオプションのクエリ パラメーターをサポートしており、応答で返されるデータの量を指定したり制御したりするために使用できます。 正確なクエリ パラメーターのサポートは、API 操作ごとに異なり、API によっては、v1.0 とベータ版エンドポイントかでも異なることがあります。
ヒント
ベータ版エンドポイントでは、$
プレフィックスが省略可能です。 たとえば、filter
とせずに、$filter
と指定することもできます。
v1 エンドポイントでは、API のサブセットに対してのみ$
プレフィックスが省略可能です。 要するに、v1 エンドポイントを使用している場合は、常に$
が含まれます。
クエリ パラメーターには、OData のシステム クエリ オプション または他のクエリ パラメーターを使用できます。
OData のシステム クエリ オプション
Microsoft Graph API 操作は、次の OData のシステム クエリ オプションの 1 つ以上をサポートする可能性があります。 これらのクエリ オプションは OData V4 クエリ言語 と互換性があり、GET 操作でのみサポートされます。
例をクリックして Graph エクスプローラー で試行します。
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')
// 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')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
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 = "startswith(givenName, 'J')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.filter('startswith(givenName, \'J\')')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
正しくエンコードされた 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')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
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 = "startswith(givenName, 'J')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.filter('startswith(givenName, \'J\')')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
二重エンコード 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')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName, 'J')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
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 = "startswith(givenName, 'J')";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.filter('startswith(givenName, \'J\')')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "startswith(givenName, 'J')"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "startswith(givenName, 'J')",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
一重引用符のエスケープ
一重引用符を使用する依頼の場合、いずれかのパラメーター値にも一重引用符が含まれている場合は、それらを二重エスケープにする必要があります。 そうでないと、無効な構文とみなされ、依頼が失敗します。 この例では、文字列値の 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?'";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "subject eq 'let''s meet for lunch?'"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "subject eq 'let''s meet for lunch?'"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.filter('subject eq \'let\'\'s meet for lunch?\'')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
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?'"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
filter = "subject eq 'let''s meet for lunch?'",
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
count パラメーター
$count
クエリ パラメーターを使用して、コレクション内の項目の合計数または一致する式の数を取得します。 $count
は次のように使用されます。
Microsoft Graph から返されるデータ値のページと共にコレクション内の項目の合計数を含める構文 $count=true
を持つクエリ文字列パラメーターとして。 たとえば、「 users?$count=true
」のように入力します。
コレクションの整数の合計を取得するため、URL セグメント として使用します。 たとえば、「 users/$count
」のように入力します。
フィルター処理されたプロパティが空のコレクションになるデータのコレクションを取得するため、等価演算子を含む $filter
式で使用されます。 「 $filter クエリ パラメーターを使用してオブジェクトのコレクションをフィルター処理する」を 参照してください。
たとえば、次のような要求では、現在のユーザーの contact コレクションと、@odata.count
プロパティ内の contact コレクションのアイテム数の両方が返されます。
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;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users contacts list --user-id {user-id} --count "true"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestCount := true
requestParameters := &graphusers.ItemContactsRequestBuilderGetQueryParameters{
Count: &requestCount,
}
configuration := &graphusers.ItemContactsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
contacts, err := graphClient.Me().Contacts().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);
ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
requestConfiguration.queryParameters.count = true;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let contacts = await client.api('/me/contacts')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->contacts()->get($requestConfiguration)->wait();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.PersonalContacts
# A UPN can also be used as -UserId.
Get-MgUserContact -UserId $userId -CountVariable CountVar
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.contacts.contacts_request_builder import ContactsRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = ContactsRequestBuilder.ContactsRequestBuilderGetQueryParameters(
count = True,
)
request_configuration = ContactsRequestBuilder.ContactsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.contacts.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
$count
クエリ パラメーターは、directoryObject から派生する、以下の頻繁に使用されるリソースのコレクションとそのリレーションシップでサポートされており、詳細クエリ でのみサポートされます。
expand パラメーター
Microsoft Graph リソースの多くは、宣言されているリソースのプロパティと、他のリソースとのリレーションシップの両方を公開します。 これらのリレーションシップは、参照プロパティまたはナビゲーション プロパティとも呼ばれ、1 つのリソースまたはリソースのコレクションのいずれかを参照することができます。 たとえば、ユーザーのメール フォルダー、マネージャー、直属の部下は、すべてリレーションシップとして公開されます。
通常、単一の要求では、リソースの複数のプロパティ、またはリソースのリレーションシップの 1 つのいずれかに対してクエリを実行できますが、両方は行えません。 $expand
クエリ文字列パラメーターを使用して、展開されているリソース、または単一のリレーションシップ (ナビゲーション プロパティ) で参照されているコレクションを結果に含めることができます。 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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives root get --drive-id {drive-id} --expand "children"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
Expand: [] string {"children"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
root, err := graphClient.Drives().ByDriveId("drive-id").Root().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);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let driveItem = await client.api('/me/drive/root')
.expand('children')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Files
Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
expand = ["children"],
)
request_configuration = RootRequestBuilder.RootRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
一部のリソース コレクションでは、パラメーターを追加することで、展開されたリソースで返されるプロパティを $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)" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives root get --drive-id {drive-id} --expand "children(\$select=id,name)"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
Expand: [] string {"children($select=id,name)"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
root, err := graphClient.Drives().ByDriveId("drive-id").Root().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);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let driveItem = await client.api('/me/drive/root')
.expand('children($select=id,name)')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Files
Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children(`$select=id,name)"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
expand = ["children($select=id,name)"],
)
request_configuration = RootRequestBuilder.RootRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
注:
すべてのリレーションシップとリソースで、$expand
クエリ パラメーターがサポートされているわけではありません。 たとえば、ユーザーの directReports 、manager 、および memberOf リレーションシップを展開することはできますが、そのイベント 、メッセージ 、または写真 のリレーションシップを展開することはできません。 すべてのリソースまたはリレーションシップで、$select
を使用して展開されたアイテムがサポートされているわけではありません。
ユーザー やグループ など、directoryObject から派生するMicrosoft Entraリソースでは、通常、$expand
展開されたリレーションシップに対して最大 20 個の項目が返され、@odata.nextLink はありません。 詳細については、「 クエリ パラメーターの制限事項 」を参照してください。
$expand
は、現在、高度なクエリ ではサポートされていません。
filter パラメーター
$filter
クエリ パラメーターを使用して、コレクションのサブセットのみを取得します。 の使用 $filter
に関するガイダンスについては、「 $filter クエリ パラメーターを使用してオブジェクトのコレクションをフィルター処理する」を 参照してください。
$format
クエリ パラメーターを使用して、Microsoft Graph から返される項目のメディア形式を指定します。
たとえば、次の要求では組織のユーザーが JSON 形式で返されます。
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";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFormat := "json"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Format: &requestFormat,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
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.format = "json";
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->format = "json";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Format "json"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
format = "json",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
注:
$format
クエリ パラメーターは、さまざまな形式 (atom、xml、json など) をサポートしていますが、結果がすべての形式で返されるわけではありません。
orderby パラメーター
$orderby
クエリ パラメーターを使用して、Microsof Graph から返される項目の並べ替え順序を指定します。 既定の順序は昇順です。
たとえば、次の要求では組織のユーザーが表示名順で返されます。
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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --orderby "displayName"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Orderby: [] string {"displayName"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
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.orderby = new String []{"displayName"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.orderby('displayName')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Users
Get-MgUser -Sort "displayName"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
orderby = ["displayName"],
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
複合型のエンティティでも並べ替えが可能です。 次の要求は、メッセージを取得し、複合型 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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --orderby "from/emailAddress/address"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/address"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.orderby('from/emailAddress/address')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Sort "from/emailAddress/address"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
orderby = ["from/emailAddress/address"],
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
昇順または降順で結果を並べ替えるには、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
// 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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users mail-folders messages list --user-id {user-id} --mail-folder-id {mailFolder-id} --orderby "from/emailAddress/name desc,subject"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.ItemMailFolderItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphusers.ItemMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().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);
MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/mailFolders/Inbox/messages')
.orderby('from/emailAddress/name desc,subject')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
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"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.mailFolders.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
orderby = ["from/emailAddress/name desc","subject"],
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.mail_folders.by_mail_folder_id('mailFolder-id').messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
注:
$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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "Subject eq 'welcome' and importance eq 'normal'" --orderby "subject,importance,receivedDateTime desc"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "Subject eq 'welcome' and importance eq 'normal'"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
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"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
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"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
filter = "Subject eq 'welcome' and importance eq 'normal'",
orderby = ["subject","importance","receivedDateTime desc"],
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
search パラメーター
$search
クエリ パラメーターを使用して、要求の結果を検索条件と一致するものに制限します。 その構文と動作は、API 操作ごとに異なります。 さまざまなリソースにわたる $search
の構文を確認するには、「$search クエリ パラメーターを使用して検索条件に一致させる 」を参照してください。
select パラメーター
$select
クエリ パラメーターを使用して、個別リソースまたはリソースのコレクションの既定値とは異なるプロパティのセットを返します。 $select
で、既定のプロパティのサブセットまたはスーパーセットを指定できます。
プロパティ データの量を制限せずに GET 要求$select
を行う場合、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" };
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --select "from,subject"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"from","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.select('from,subject')
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "from,subject"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["from","subject"],
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
重要
通常は、$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;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users events list --user-id {user-id} --skip "20" --orderby "createdDateTime"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestSkip := int32(20)
requestParameters := &graphusers.ItemEventsRequestBuilderGetQueryParameters{
Orderby: [] string {"createdDateTime"},
Skip: &requestSkip,
}
configuration := &graphusers.ItemEventsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
events, err := graphClient.Me().Events().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);
EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
requestConfiguration.queryParameters.skip = 20;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let events = await client.api('/me/events')
.orderby('createdDateTime')
.skip(20)
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$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();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Calendar
# A UPN can also be used as -UserId.
Get-MgUserEvent -UserId $userId -Sort "createdDateTime" -Skip 20
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.events.events_request_builder import EventsRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = EventsRequestBuilder.EventsRequestBuilderGetQueryParameters(
orderby = ["createdDateTime"],
skip = 20,
)
request_configuration = EventsRequestBuilder.EventsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.events.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
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
// 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;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --top "5"
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestTop := int32(5)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Top: &requestTop,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.top = 5;
});
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.top(5)
.get();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
<?php
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Top 5
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
top = 5,
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照 してください。
注:
ディレクトリ オブジェクトに対する詳細クエリに必要な ConsistencyLevel ヘッダーは、既定では後続のページ リクエストに含まれていません。 後続のページで明示的に設定する必要があります。
クエリ パラメーターのエラー処理
一部の要求では、指定したクエリ パラメーターがサポートされていない場合にエラー メッセージが返されます。 たとえば、リレーションシップでは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"
}
}
}
ただし、要求で指定されたクエリ パラメーターが警告なしで失敗する可能性があるため、注意が必要です。 これは、クエリ パラメーターがサポートされていない場合や、クエリ パラメーターの組み合わせがサポートされていない場合に起こり得ます。 その場合、要求によって返されたデータを調べ、指定したクエリ パラメーターに期待どおりの効果があったかどうかを確認する必要があります。
関連コンテンツ