クエリ パラメーターを使用して応答をカスタマイズするUse query parameters to customize responses

Microsoft Graph はオプションのクエリ パラメーターをサポートしており、応答で返されるデータの量を指定したり制御したりするために使用できます。Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response. 正確なクエリ パラメーターのサポートは、API 操作ごとに異なり、API によっては、v1.0 とベータ版エンドポイントかでも異なることがあります。The support for the exact query parameters varies from one API operation to another, and depending on the API, can differ between the v1.0 and beta endpoints.

ヒント

ベータ版エンドポイントでは、$プレフィックスが省略可能です。On the beta endpoint, the $ prefix is optional. たとえば、filter とせずに、$filter と指定することもできます。For example, instead of $filter, you can use filter. v1 エンドポイントでは、API のサブセットに対してのみ$プレフィックスが省略可能です。On the v1 endpoint, the $ prefix is optional for only a subset of APIs. 要するに、v1 エンドポイントを使用している場合は、常に$が含まれます。For simplicity, always include $ if using the v1 endpoint.

クエリ パラメーターには、OData のシステム クエリ オプションまたは他のクエリ パラメーターを使用できます。Query parameters can be OData system query options or other query parameters.

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

Microsoft Graph API 操作は、次の OData のシステム クエリ オプションの 1 つ以上をサポートする可能性があります。A Microsoft Graph API operation might support one or more of the following OData system query options. これらのクエリ オプションは、OData V4 クエリ言語と互換性があります。These query options are compatible with the OData V4 query language.

注: OData 4.0 は、GET 操作でのみシステム クエリ オプションをサポートします。Note: OData 4.0 supports system query options in only GET operations.

例をクリックして Graph エクスプローラーで試行します。Click the examples to try them in Graph Explorer.

NameName 説明Description Example
$count$count 一致するリソースの総数を取得します。Retrieves the total count of matching resources. /me/messages?$top=2&$count=true
$expand$expand 関連リソースを取得します。Retrieves related resources. /groups?$expand=members
$filter$filter 結果 (行) をフィルターします。Filters results (rows). /users?$filter=startswith(givenName,'J')
$format$format 指定したメディア形式で結果を返します。Returns the results in the specified media format. /users?$format=json
$orderby$orderby 結果を並べます。Orders results. /users?$orderby=displayName desc
$search$search 検索条件に基づいて結果を返します。現在、messagesperson のコレクションでサポートされています。Returns results based on search criteria. Currently supported on messages and person collections. /me/messages?$search=pizza
$select$select プロパティ (列) をフィルターします。Filters properties (columns). /users?$select=givenName,surname
$skip$skip 結果セットにインデックスを作成します。また一部の API でページングを実装するために使用されており、$top と組み合わせて手動で結果をページングすることもできます。Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. /me/messages?$skip=11
$top$top 結果のページ サイズを設定します。Sets the page size of results. /users?$top=2

その他のクエリ パラメーターOther query parameters

名前Name 説明Description Example
$skipToken$skipToken 複数ページにわたる結果セットから、結果の次のページを取得します。(一部の API では代わりに $skip を使用します。)Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.) /users?$skiptoken=X%274453707402000100000017...

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

クエリ パラメーターの値はパーセント エンコードされる必要があります。The values of query parameters should be percent-encoded. これを行う上で役立つ HTTP クライアント、ブラウザー、およびツールが多くあります (Graph エクスプローラーなど)。Many HTTP clients, browsers, and tools (such as the Graph Explorer) will help you with this. クエリが失敗する場合、クエリ パラメーターの値が適切にエンコードされていないことがその原因の 1 つとして考えられます。If a query is failing, one possible cause is failure to encode the query parameter values appropriately.

エンコードされていない URL は、次のようになります。An unencoded URL looks like this:

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

正しくエンコードされている URL は、次のようになります。A properly encoded URL looks like this:

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

一重引用符のエスケープEscaping single quotes

一重引用符を使用する依頼の場合、いずれかのパラメーター値にも一重引用符が含まれている場合は、それらを二重エスケープにする必要があります。 そうでないと、無効な構文とみなされ、依頼が失敗します。For requests that use single quotes, if any parameter values also contain single quotes, those must be double escaped; otherwise, the request will fail due to invalid syntax. この例では、文字列値の let''s meet for lunch? では一重引用符がエスケープされています。In the example, the string value let''s meet for lunch? has the single quote escaped.

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

count パラメーターcount parameter

$count クエリ パラメーターを使用し、Microsoft Graph から返されるデータ値のページにコレクション内の項目数の合計を含めます。Use the $count query parameter to include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph.

たとえば、次のような要求では、現在のユーザーの contact コレクションと、@odata.count プロパティ内の contact コレクションのアイテム数の両方が返されます。For example, the following request will return both the contact collection of the current user, and the number of items in the contact collection in the @odata.count property.

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

Graph エクスプローラーで試すTry in Graph Explorer

注: $count は、usergroup のコレクションのような、directoryObject から派生したリソースのコレクションに対してはサポートされていません。Note: $count is not supported for collections of resources that derive from directoryObject like collections of users or groups.

expand パラメーターexpand parameter

Microsoft Graph リソースの多くは、宣言されているリソースのプロパティと、他のリソースとのリレーションシップの両方を公開します。Many Microsoft Graph resources expose both declared properties of the resource as well as its relationships with other resources. これらのリレーションシップは、参照プロパティまたはナビゲーション プロパティとも呼ばれ、1 つのリソースまたはリソースのコレクションのいずれかを参照することができます。These relationships are also called reference properties or navigation properties, and they can reference either a single resource or a collection of resources. たとえば、ユーザーのメール フォルダー、マネージャー、直属の部下は、すべてリレーションシップとして公開されます。For example, the mail folders, manager, and direct reports of a user are all exposed as relationships.

通常、単一の要求では、リソースの複数のプロパティ、またはリソースのリレーションシップの 1 つのいずれかに対してクエリを実行できますが、両方は行えません。$expand クエリ文字列パラメーターを使用して、展開されているリソース、または単一のリレーションシップ (ナビゲーション プロパティ) で参照されているコレクションを結果に含めることができます。Normally, you can query either the properties of a resource or one of its relationships in a single request, but not both. You can use the $expand query string parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results.

次の例では、ドライブ内のトップレベルの子項目と共に、ルート ドライブ情報を取得します。The following example gets root drive information along with the top-level child items in a drive:

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

Graph エクスプローラーで試すTry in Graph Explorer

いくつかのリソース コレクションで、$select パラメーターを追加すれば、展開されたリソースで返されるプロパティを指定することもできます。次の使用例は前の例と同じクエリを実行しますが、$select ステートメントを使用して、展開されている子項目に返されるプロパティを id プロパティと name プロパティに限定します。With some resource collections, you can also specify the properties to be returned in the expanded resources by adding a $select parameter. The following example performs the same query as the previous example but uses a $select statement to limit the properties returned for the expanded child items to the id and name properties.

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

Graph エクスプローラーで試すTry in Graph Explorer

注: すべてのリレーションシップとリソースで、$expand クエリ パラメーターがサポートされているわけではありません。たとえば、ユーザーの directReportsmanagermemberOf の各リレーションシップを展開できますが、その eventsmessagesphoto のリレーションシップは展開できません。すべてのリソースまたはリレーションシップで、$select を使用して展開されたアイテムがサポートされているわけではありません。Note: Not all relationships and resources support the $expand query parameter. For example, you can expand the directReports, manager, and memberOf relationships on a user, but you cannot expand its events, messages, or photo relationships. Not all resources or relationships support using $select on expanded items.

ユーザーグループのような、directoryObject から派生した Azure AD リソースの場合、$expandbeta でのみサポートされており、通常は展開されているリレーションシップに対し最大 20 個のアイテムを返すことができます。With Azure AD resources that derive from directoryObject, like user and group, $expand is only supported for beta and typically returns a maximum of 20 items for the expanded relationship.

filter パラメーターfilter parameter

$filter クエリ パラメーターを使用して、コレクションのサブセットのみを取得します。Use the $filter query parameter to retrieve just a subset of a collection.

たとえば、表示名が「J」という文字で始まるユーザーを検索するには、startswith を使用します。For example, to find users whose display name starts with the letter 'J', use startswith.

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

Graph エクスプローラーで試すTry in Graph Explorer

$filter 演算子へのサポートは、お使いの Microsoft Graph API によって異なります。Support for $filter operators varies across Microsoft Graph APIs. 通常、次の論理演算子がサポートされています。The following logical operators are generally supported:

  • 等しい (eq)equals (eq)
  • 等しくない (ne)not equals (ne)
  • より大きい (gt)greater than (gt)
  • 以上 (ge)greater than or equals (ge)
  • より小さい (lt)、以下 (le)less than (lt), less than or equals (le)
  • AND (and)and (and)
  • OR (or)or (or)
  • NOT (not)not (not)

startswith 文字列の演算子はたいていサポートされています。The startswith string operator is often supported. any ラムダ演算子は、一部の API でサポートされています。The any lambda operator is supported for some APIs.

注: メッセージを取得するために同じクエリ内の $filter$orderby を使用する場合は、特定の方法でプロパティを指定する 必要があります。Note: You must specify properties in certain ways when using both $filter and $orderby in the same query to get messages.

いくつかの使用例について、次の表を参照してください。For some usage examples, see the following table. $filter 構文の詳細については、「OData プロトコル」を参照してください。For more details about $filter syntax, see the OData protocol.

次の表では、$filter クエリ パラメーターの使用例を示します。The following table shows some examples that use the $filter query parameter.

注: 例をクリックして Graph エクスプローラーで試行します。Note: Click the examples to try them in Graph Explorer.

説明Description Example
複数のプロパティ間で Mary という名前を持つユーザーを検索します。Search for users with the name Mary across multiple properties. https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
2017 年 7 月 1 日以降に開始する、サインイン ユーザーのイベントすべてを取得します。Get all the signed-in user's events that start after 7/1/2017. https://graph.microsoft.com/v1.0/me/events?$filter=start/dateTime ge '2017-07-01T08:00'
サインイン ユーザーが受信した特定のアドレスからの電子メールすべてを取得します。Get all emails from a specific address received by the signed-in user. https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
2017 年 4 月にサインイン ユーザーが受信した電子メールすべてを取得します。Get all emails received by the signed-in user in April 2017. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
サインイン ユーザーの受信トレイから未読メールをすべて取得します。Get all unread mail in the signed-in user's Inbox. https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages?$filter=isRead eq false
組織内のすべての Office 365 グループの一覧List all Office 365 groups in an organization. https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/any(c:c+eq+'Unified')

注: Azure AD リソースでは、次の $filter 演算子はサポートされていません: negtgeltlenot。Microsoft Graph リソースでは現在、contains 文字列の演算子はサポートされていません。Note: The following $filter operators are not supported for Azure AD resources: ne, gt, ge, lt, le, and not. The contains string operator is currently not supported on any Microsoft Graph resources.

format パラメーターformat parameter

$format クエリ パラメーターを使用して、Microsoft Graph から返される項目のメディア形式を指定します。Use the $format query parameter to specify the media format of the items returned from Microsoft Graph.

たとえば、次の要求では組織のユーザーが JSON 形式で返されます。For example, the following request returns the users in the organization in the json format:

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

Graph エクスプローラーで試すTry in Graph Explorer

注:$format クエリ パラメーターは、さまざまな形式 (atom、xml、json など) をサポートしていますが、結果がすべての形式で返されるわけではありません。Note: The $format query parameter supports a number of formats (for example, atom, xml, and json) but results may not be returned in all formats.

orderby パラメーターorderby parameter

$orderby クエリ パラメーターを使用して、Microsof Graph から返される項目の並べ替え順序を指定します。Use the $orderby query parameter to specify the sort order of the items returned from Microsoft Graph.

たとえば、次の要求では組織のユーザーが表示名順で返されます。For example, the following request returns the users in the organization ordered by their display name:

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

Graph エクスプローラーで試すTry in Graph Explorer

複合型のエンティティでも並べ替えができます。次の要求では、メッセージを取得し、それらを emailAddress という複合型である from プロパティの address フィールドで並べ替えます。You can also sort by complex type entities. The following request gets messages and sorts them by the address field of the from property, which is of the complex type emailAddress:

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

Graph エクスプローラーで試すTry in Graph Explorer

昇順または降順で結果を並べ替えるには、asc または desc のいずれかをスペースで区切ってフィールド名の後に追加します。たとえば ?$orderby=name%20desc のようにします。To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space; for example, ?$orderby=name%20desc.

一部の API では、複数のプロパティの結果を並べ替えることができます。With some APIs, you can order results on multiple properties. たとえば、次のような要求ではユーザーの受信トレイ内のメッセージを、最初は送信者の名前で降順に並べ替え (Z から A)、次に件名で昇順 (既定) に並べ替えます。For example, the following request orders the messages in the user's Inbox, first by the name of the person who sent it in descending order (Z to A), and then by subject in ascending order (default).

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

Graph エクスプローラーで試すTry in Graph Explorer

注: $filter を指定した場合は、サーバーで結果の並べ替え順序が考慮されます。Note: When you specify $filter the server will infer a sort order for the results. メッセージを取得するために$orderby$filter の両方を使用する場合は、サーバーでは常に $filter の結果の並べ替え順序が考慮されるため、特定の方法でプロパティを指定する 必要があります。If you use both $orderby and $filter to get messages, because the server always infers a sort order for the results of a $filter, you must specify properties in certain ways.

次の例は、SubjectImportance の両方のプロパティでフィルター処理されてから、SubjectImportancereceivedDateTime の各プロパティで降順で並べ替えられたクエリを示しています。The following example shows a query filtered by the subject and importance properties, and then sorted by the subject, importance, and receivedDateTime properties in descending order.

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

Graph エクスプローラーで試すTry in Graph Explorer

注: ユーザーグループのような、directoryObject から派生した Azure AD リソースの場合、$orderby 式と $filter 式を結合することはできません。Note: With Azure AD resources that derive from directoryObject, like user and group, you cannot combine $orderby with $filter expressions.

search パラメーターsearch parameter

$search クエリ パラメーターを使用して、要求の結果を検索条件と一致するものに制限します。Use the $search query parameter to restrict the results of a request to match a search criterion.

注: 現在の検索対象は、メッセージ コレクションと人物コレクションだけです。$search 要求は最大 250 まで結果を返します。検索要求では $filter$orderby も使用できません。Note: You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request.

メッセージ コレクションで $search を使用するUsing $search on message collections

特定のメッセージ プロパティの値に基づいてメッセージを検索することができます。You can search messages based on a value in specific message properties. 検索結果は、メッセージが送信された日時で並べ替えられます。The results of the search are sorted by the date and time that the message was sent.

メッセージで検索を行うときに、特定のメッセージ プロパティを指定せずに値のみを指定した場合、検索は既定の検索プロパティである fromsubjectbody に基づいて行われます。If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.

次の例は、サインイン中のユーザーの受信トレイにあるメッセージのうち、既定の 3 つの検索プロパティのいずれかに "pizza" が含まれるメッセージをすべて返します。The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Graph エクスプローラーで試すTry in Graph Explorer

また、キーワード クエリ言語 (KQL) 構文で認識される、以下の表のメッセージ プロパティ名を指定して、メッセージの検索をすることもできます。Alternatively, you can search messages by specifying message property names in the following table, that are recognized by the Keyword Query Language (KQL) syntax. これらのプロパティ名は Microsoft Graph の message エンティティで定義したプロパティです。These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook や他の Office 365 アプリケーション (SharePoint など) では KQL 構文をサポートしており、データ ストアの共通探索ドメインの利便性が向上します。Outlook and other Office 365 applications such as SharePoint support KQL syntax, providing the convenience of a common discovery domain for their data stores.

検索可能な電子メール プロパティSearchable email property 説明Description Example
attachmentattachment 電子メール メッセージに添付されているファイルの名前。The names of files attached to an email message. me/messages?$search="attachment:api-catalog.md"
bccbcc SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの bcc フィールド。The bcc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
bodybody 電子メール メッセージの本文。The body of an email message. me/messages?$search="body:excitement"
cccc SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの cc フィールド。The cc field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="cc:danas"&$select=subject,ccRecipients
fromfrom SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの送信者。The sender of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="from:randiw"&$select=subject,from
hasAttachmenthasAttachment 電子メール メッセージに添付ファイルがあり、そのファイルがインラインの添付ファイルでない場合は true、そうでない場合は false。True if an email message contains an attachment that is not an inline attachment, false otherwise. me/messages?$search="hasAttachments=true"
importanceimportance 送信者がメッセージを送信するときに指定できる電子メール メッセージの重要度。The importance of an email message, which a sender can specify when sending a message. 使用可能な値: lowmediumhighThe possible values are low, medium, or high. me/messages?$search="importance:high"&$select=subject,importance
kindkind メッセージの種類。The type of message. 使用可能な値: contactsdocsemailfaxesimjournalsmeetingsnotespostsrssfeedstasksvoicemailThe possible values are contacts, docs, email, faxes, im, journals, meetings, notes, posts, rssfeeds, tasks, or voicemail. me/messages?$search="kind:voicemail"
participantsparticipants SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの fromtoccbcc フィールド。The from, to, cc, and bcc fields of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="participants:danas"
receivedreceived 電子メール メッセージが受信者によって受信された日付。The date that an email message was received by a recipient. me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipientsrecipients SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの toccbcc フィールド。The to, cc, and bcc fields of an email meesage, specified as an SMTP address, display name, or alias. me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sentsent 送信者によって電子メール メッセージが送信された日付。The date that an email message was sent by the sender. me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
sizesize アイテムのサイズ (バイト数)。The size of an item in bytes. me/messages?$search="size:1..500000"
subjectsubject 電子メール メッセージの件名行に含まれるテキスト。The text in the subject line of an email message. .. me/messages?$search="subject:has"&$select=subject
toto SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの to フィールド。The to field of an email message, specified as an SMTP address, display name, or alias. me/messages?$search="to:randiw"&$select=subject,toRecipients

検索可能な電子メール プロパティ、KQL 構文、サポートされている演算子、検索のヒントなどの詳細については、次の記事を参照してください。For more information about searchable email properties, KQL syntax, supported operators, and tips on searching, see the following articles:

人物コレクションで $search を使用するUsing $search on person collections

Microsoft Graph People API を使用してユーザーに最も関連のある人物を取得できます。関連性は、ユーザーのコミュニケーションとコラボレーション パターン、およびビジネスのリレーションシップによって決定されます。People API では、$search クエリ パラメーターがサポートされています。You can use the Microsoft Graph People API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. The People API supports the $search query parameter.

person リソースの displayName プロパティと emailAddress プロパティの両方で人物の検索を行います。Searches on people occur on both the displayName and emailAddress properties of the person resource.

次の要求は、サインイン ユーザーの people コレクションに含まれる各ユーザーの displayName プロパティと emailAddress プロパティで、「Irene McGowen」という名前の人物を検索します。The following request does a search for a person named "Irene McGowen" in the displayName and emailAddress properties in each person in the people collection of the signed-in user. 「Irene McGowan」という名前の人物がサインインしているユーザーに関連するため、「Irene McGowan」の情報が返されます。Because a person named "Irene McGowan" is relevant to the signed-in user, the information for "Irene McGowan" is returned.

GET https://graph.microsoft.com/v1.0/me/people/?$search="Irene McGowen"

次の例は応答を示しています。The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.onmicrosoft.com",
           "imAddress": "sip:irenem@contoso.onmicrosoft.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.onmicrosoft.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

People API の詳細については、「関係する人の情報を取得する」を参照してください。To learn more about the People API, see Get information about relevant people.

select パラメーターselect parameter

$select クエリ パラメーターを使用して、個別リソースまたはリソースのコレクションの既定値とは異なるプロパティのセットを返します。Use the $select query parameter to return a set of properties that are different than the default set for an individual resource or a collection of resources. $Select で、既定のプロパティのサブセットまたはスーパーセットを指定できます。With $select, you can specify a subset or a superset of the default properties.

たとえば、サインイン ユーザーのメッセージを取得するとき、from プロパティと subject プロパティだけを返すよう指定できます。For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

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

Graph エクスプローラーで試すTry in Graph Explorer

重要: 通常は、$select を使用して、クエリから返されるプロパティをお使いのアプリで必要なものだけに制限することをお勧めします。Important: In general, we recommend that you use $select to limit the properties returned by a query to those needed by your app. これは特に、クエリが大きな結果セットを返す可能性がある場合に該当します。This is especially true of queries that might potentially return a large result set. 行ごとに返されるプロパティを制限すれば、ネットワークの負荷を軽減し、アプリのパフォーマンスを向上させることができます。Limiting the properties returned in each row will reduce network load and help improve your app's performance.

v1.0では、ユーザーグループのような、directoryObject から派生した一部の Azure AD リソースは、読み取り時に制限された既定値のプロパティ サブセットを返します。既定のセット以外のプロパティを返すには、これらのリソースに対して $select を使用する必要があります。In v1.0, some Azure AD resources that derive from directoryObject, like user and group, return a limited, default subset of properties on reads. For these resources, you must use $select to return properties outside of the default set.

skip パラメーターskip parameter

コレクションを開始するときにスキップする項目数を設定するには、$skip クエリ パラメーターを使用します。たとえば、次の要求はユーザーのイベントを、コレクション内の 21 番目以降のイベントから作成日順で返します。Use the $skip query parameter to set the number of items to skip at the start of a collection. For example, the following request returns events for the user sorted by date created, starting with the 21st event in the collection:

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

Graph エクスプローラーで試すTry in Graph Explorer

注: Outlook のメールやカレンダーなど、いくつかの Microsoft Graph API (messageeventcalendar) は、$skip を使用してページングを実装します。Note: Some Microsoft Graph APIs, like Outlook Mail and Calendars (message, event, and calendar), use $skip to implement paging. クエリの結果が複数ページにまたがる場合、これらの API は @odata:nextLink プロパティと共に $skip パラメーターが含まれる URL を返します。When results of a query span multiple pages, these APIs will return an @odata:nextLink property with a URL that contains a $skip parameter. この URL を使用して、結果の次のページに戻れます。You can use this URL to return the next page of results. 詳細については、「ページング」を参照してください。To learn more, see Paging.

skipToken パラメーターskipToken parameter

要求の中には、サーバー側のページングを使用したり、応答におけるページ サイズを限定するために $top パラメーターを使用したりすることによって、複数のデータ ページを返すものがあります。Microsoft Graph API の多くは、skipToken クエリ パラメーターを使用して、結果の後続のページを参照します。$skiptoken パラメーターは、結果の次のページを参照する不透明トークンを含んでおり、応答の @odata.nextLink プロパティで指定される URL で返されます。詳細については、「ページング」を参照してください。Some requests return multiple pages of data either due to server-side paging or due to the use of the $top parameter to limit the page size of the response. Many Microsoft Graph APIs use the skipToken query parameter to reference subsequent pages of the result. The $skiptoken parameter contains an opaque token that references the next page of results and is returned in the URL provided in the @odata.nextLink property in the response. To learn more, see Paging.

top パラメーターtop parameter

$top クエリ パラメーターを使用して、結果セットのページ サイズを指定します。Use the $top query parameter to specify the page size of the result set.

結果セットにさらに項目が残っている場合、応答本文に @odata.nextLink パラメーターが含まれます。If more items remain in the result set, the response body will contain an @odata.nextLink parameter. このパラメーターには、結果の次のページを取得するために使用できる URL が含まれています。This parameter contains a URL that you can use to get the next page of results. 詳細については、「ページング」を参照してください。To learn more, see Paging.

たとえば、次の要求はユーザーのメールボックスの最初の 5 つのメッセージを返します。For example, the following request returns the first five messages in the user's mailbox:

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

Graph エクスプローラーで試すTry in Graph Explorer

クエリ パラメーターのエラー処理Error handling for query parameters

指定されたクエリ パラメーターがサポートされていない場合、一部の要求はエラー メッセージを返します。たとえば、$expanduser/photo のリレーションシップで使用することはできません。Some requests will return an error message if a specified query parameter is not supported. For example, you cannot use $expand on the user/photo relationship.

https://graph.microsoft.com/beta/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"
        }
    }
}

ただし、要求で指定されたクエリ パラメーターが警告なしで失敗する可能性があるため、注意が必要です。However, it is important to note that query parameters specified in a request might fail silently. これは、クエリ パラメーターがサポートされていない場合や、クエリ パラメーターの組み合わせがサポートされていない場合に起こり得ます。This can be true for unsupported query parameters as well as for unsupported combinations of query parameters. その場合、要求によって返されたデータを調べ、指定したクエリ パラメーターに期待どおりの効果があったかどうかを確認する必要があります。In these cases, you should examine the data returned by the request to determine whether the query parameters you specified had the desired effect.