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

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

ヒント

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

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

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

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

注: OData 4.0 は、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

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

名前 説明
$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

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

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

エンコードされていない 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')

一重引用符のエスケープ

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

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

count パラメーター

$count クエリ パラメーターを使用し、Microsoft Graph から返されるデータ値のページにコレクション内の項目数の合計を含めます。

注意

$count はコレクションの整数の合計を取得するための URL セグメントとして使用することもできます。 directoryObject から派生したリソースでは、詳細クエリでのみサポートされます。 Azure AD ディレクトリ オブジェクトの詳細クエリ機能をご覧ください。

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 から派生した Azure AD リソースの場合、$expand は通常、展開されているリレーションシップに対し最大 20 個のアイテムを返し、@odata.nextLink はありません。 その他の既知の問題を参照してください。

filter パラメーター

$filter クエリ パラメーターを使用して、コレクションのサブセットのみを取得します。 $filter クエリ パラメーターを使用して、members、memberOf、transitiveMembers、transitiveMemberOf などのリレーションシップを取得することもできます。 たとえば、自分がメンバーになっているすべてのセキュリティ グループを取得します。

以下の例では、表示名が ”J” という文字で始まるユーザーを検索します:

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

$filter 演算子へのサポートは、お使いの Microsoft Graph API によって異なります。 通常、次の論理演算子がサポートされています。

演算子の種類 オペレーター
近接演算子
  • 等しいeq
  • 等しくないne
  • not の否定
  • in
関係演算子
  • より小さいlt
  • より大きいgt
  • 以下le
  • 以上ge
ラムダ演算子
  • 任意any
  • すべてall
条件演算子
  • および and
  • または or
関数
  • startsWith で始まる
  • endsWith で終わる
  • contains を含む

注: これらの演算子のサポートはエンティティによって異なり、一部のプロパティは 詳細クエリでのみ $filter をサポートします。 詳細については、特定のエンティティのドキュメントを参照してください。

ラムダ演算子を使用したフィルター

OData は、any および all 演算子を定義して、複数値のプロパティ、つまり、文字列型などのプリミティブ値のコレクションまたはエンティティのコレクションの一致を評価します。

any 演算子は、コレクションの各メンバーにブール式を繰り返し適用し、式がコレクションの すべてのメンバー に対して true である場合は true を返し、そうでない場合は false を返します。 any 演算子の構文は次のとおりです。

$filter=param/any(var:var/subparam eq 'value-to-match')

場所

  • param は、値のコレクションまたはエンティティのコレクションを含むプロパティです。
  • var:var は、反復中にコレクションの現在の要素を保持する範囲変数です。 この変数には、adele:adelex:x など、ほとんどすべての名前を付けることができます。
  • クエリをエンティティのコレクションに適用する場合は、subparam が必要です。 これは、値が一致する複合型のプロパティを表します。
  • value-to-match は、照合するコレクションのメンバーを表します。

たとえば、ユーザー リソースの imAddresses プロパティには、プリミティブ型文字列のコレクションが含まれています。 次のクエリは、imAddress が admin@contoso.com のユーザーのみを取得します。

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(s:s eq 'admin@contoso.com')

たとえば、ユーザー リソースの assignedLicenses プロパティには、assignedLicense オブジェクトのコレクションが含まれます。これは、skuIddisabledPlans の 2 つのプロパティを持つ複合型です。 次のクエリは、skuId 184efa21-98c3-4e5d-95ab-d07053a96e67 で識別されるライセンスが割り当てられているユーザーのみを取得します。

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

any 句内の式の結果を否定するには、ne 演算子ではなく NOT 演算子を使用します。 たとえば、次のクエリは、admin@contoso.comimAddress が割り当てられていないユーザーのみを取得します。

注: ユーザーなどのディレクトリ オブジェクトの場合、NOT演算子とne演算子は、高度なクエリでのみサポートされます。

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(s:s eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

all 演算子は、コレクションの各メンバーにブール式を適用し、式がコレクションの すべてのメンバー に対して true である場合は true を返し、そうでない場合は false を返します。 どのプロパティでもサポートされていません。

フィルター クエリ 演算子を使用した例

次の表では、$filter クエリ パラメーターの使用例を示します。 $filter 構文の詳細については、「OData プロトコル」を参照してください。

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

説明
複数のプロパティ間で Mary という名前を持つすべてのユーザーを取得します。 GET ../users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
メール ドメインが 'hotmail.com' と等しいすべてのユーザーを取得する
GET ../users?$count=true&$filter=endsWith(mail,'@hotmail.com')。 これは詳細クエリです。
2017 年 7 月 1 日以降に開始する、サインイン ユーザーのイベントすべてを取得します。 GET ../me/events?$filter=start/dateTime ge '2017-07-01T08:00'
サインイン ユーザーが受信した特定のアドレスからの電子メールすべてを取得します。 GET ../me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
2017 年 4 月にサインイン ユーザーが受信した電子メールすべてを取得します。 GET ../me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
サインイン ユーザーの受信トレイから未読メールをすべて取得します。 GET ../me/mailFolders/inbox/messages?$filter=isRead eq false
小売部門と販売部門のすべてのユーザーを取得します。
GET ../users?$filter=department in ('Retail', 'Sales')
一時停止状態にある特定のサービス プランを持つユーザーを一覧表示します。
GET ../users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true。 これは詳細クエリです。
組織内のすべての Microsoft 365 以外のグループを一覧表示します。
GET ../groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true。 これは詳細クエリです。
会社名が未定義ではない (つまり、null 値ではない) ユーザーまたは Microsoft のすべてのユーザーを一覧表示します。
GET ../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true。 これは詳細クエリです。
会社名が未定義または Microsoft のいずれかであるすべてのユーザーを一覧表示します。
GET ../users?$filter=companyName in (null, 'Microsoft')&$count=true。 これは詳細クエリです。
OData キャストを使用して、返されたオブジェクト数を含む、「a」で始まる表示名のグループの推移性のメンバーシップを取得します。
GET ../me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')。 これは詳細クエリです。

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

複合型のエンティティでも並べ替えができます。次の要求では、メッセージを取得し、それらを emailAddress という複合型である from プロパティの address フィールドで並べ替えます。

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 のクエリ パラメーターの組み合わせは、ディレクトリ オブジェクトでサポートされています。 Azure AD ディレクトリ オブジェクトの詳細クエリ機能をご覧ください。

search パラメーター

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

select パラメーター

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

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

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

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

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

skip パラメーター

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

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

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

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

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 ヘッダーは、既定では後続のページ リクエストに含まれていません。 後続のページで明示的に設定する必要があります。

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

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

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

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

関連項目