英語で読む

次の方法で共有


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

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

ヒント

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

クエリ パラメーターには、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

JSON バッチ処理

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

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

注意

v1.0 エンドポイントの$search式のアンパサンド (&) シンボルのエンコードに関連する既知の問題があります。 この問題と推奨される回避策の詳細については、「既知の 問題: エンコードされたアンパサンド (&) 文字でディレクトリ オブジェクトの$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 の使用はサポートされていません。

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

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

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

expand パラメーター

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

$expand クエリ文字列パラメーターを使用して、展開されているリソース、または単一のリレーションシップ (ナビゲーション プロパティ) で参照されているコレクションを結果に含めることができます。 一部の API では、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 クエリ パラメーターでは、さまざまな形式 (atomxmljsonなど) がサポートされていますが、結果がすべての形式で返されるわけではありません。

orderby パラメーター

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

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

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

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

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

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

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

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

注意

$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 で、既定のプロパティのサブセットまたはスーパーセットを指定できます。

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

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

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

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

重要

通常は、$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 は、$skip パラメーターを含む URL を持つ @odata.nextLink プロパティを返します。 この URL を使用して、結果の次のページに戻れます。 詳細については、「ページング」を参照してください。

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

skipToken パラメーター

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

注意

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

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

top パラメーター

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

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

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

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

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

注意

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

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