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

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 つとして考えられます。 場合によっては、値を二重エンコードする必要があります。

注:

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

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

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

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

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

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

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

一重引用符のエスケープ

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

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

count パラメーター

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

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

注:

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

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

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

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

expand パラメーター

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

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

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

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

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

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

注:

  • すべてのリレーションシップとリソースで、$expand クエリ パラメーターがサポートされているわけではありません。 たとえば、ユーザーの directReportsmanager、および memberOf リレーションシップを展開することはできますが、そのイベントメッセージ、または写真のリレーションシップを展開することはできません。 すべてのリソースまたはリレーションシップで、$select を使用して展開されたアイテムがサポートされているわけではありません。

  • ユーザーグループなど、directoryObject から派生するMicrosoft Entraリソースでは、通常、$expand展開されたリレーションシップに対して最大 20 個の項目が返され、@odata.nextLink はありません。 詳細については、「 クエリ パラメーターの制限事項」を参照してください。

  • $expand は、現在、高度なクエリではサポートされていません。

filter パラメーター

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

format パラメーター

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

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

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

注:

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

orderby パラメーター

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

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

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

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

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

昇順または降順で結果を並べ替えるには、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

注:

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

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

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

注:

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

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

重要

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

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

skip パラメーター

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

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

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

注:

ディレクトリ オブジェクトに対する詳細クエリに必要な 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"
        }
    }
}

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