SharePoint REST 要求で OData クエリ操作を使用するUse OData query operations in SharePoint REST requests

はじめにBefore you start

SharePoint REST サービスでは、さまざまな OData クエリ文字列演算子がサポートされており、それらの演算子を使用してリクエスト データの選択、フィルタリング、並べ替えが可能です。The SharePoint REST service supports a wide range of OData query string operators that enable you to select, filter, and order the data you request.

ヒント

SharePoint Online (およびオンプレミス SharePoint 2016 以降) REST サービスでは、OData $batch クエリ オプションを使って、サービスに対する複数の要求を 1 つの呼び出しに統合できます。The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. 詳細とコード サンプルへのリンクについては、「REST API によりバッチ要求を発行する」を参照してください。For details and links to code samples, see Make batch requests with the REST APIs.

返されるフィールドを選択するSelect fields to return

$select クエリ オプションを使用して、指定のリスト、リスト項目、またはエンティティ セットで表される他の SharePoint オブジェクトに対して返すフィールドを指定します。Use the $select query option to specify which fields to return for a given list, list item, or other SharePoint object represented by an entity set. 利用可能なすべてのフィールドは、$select=* を使用して返すことができます。You can use $select=* to return all available fields.

注意

通常、$select クエリ オプションを使用しない場合、既定で、REST サービスは使用可能なすべてのフィールドを返します。In general, if you do not specify the $select query option, the REST service returns all available fields by default. ただし、まれなケースとして、一部の SharePoint オブジェクトには、取得に多くのリソースを費やすプロパティが含まれていることがあります。REST サービス パフォーマンスを最適化するため、これらのプロパティは既定のクエリからは除外されており、明示的に要求する必要があります。たとえば、SPWeb.EffectiveBasePermissions プロパティは既定で返されず、$select クエリ オプションを使って明示的に要求する必要があります。However, in a few cases, some SharePoint objects include properties that are very resource intensive to retrieve; to optimize REST service performance, these properties are not included in the default query, and must be explicitly requested.For example, the SPWeb.EffectiveBasePermissions property is not returned by default, and must be explicitly requested by using the $select query option.

さらに、要求が他のリストとルックアップの値から予想されるフィールドを返すよう指定できます。In addition, you can specify that the request returns projected fields from other lists and the values of lookups. そのためには、$select$expand の両方のクエリ オプションでフィールド名を指定します。To do this, specify the field name in both the $select and $expand query options. 次に例を示します。For example:

http://server/site/_api/web/lists('guid')/items?$select=Title,Products/Name&$expand=Products/Name

一括拡張と関連アイテムの選択はサポートされません。Bulk expansion and selection of related items is not supported.

返されるアイテムを選択するSelect items to return

$filter クエリ オプションを使用して、返すアイテムを選択します。Use the $filter query option to select which items to return. SharePoint REST サービスでサポートされる OData クエリ演算子は、SharePoint REST サービスで使用できるフィルター クエリ比較のオプションと関数を一覧表示します。OData query operators supported in the SharePoint REST service lists the filter query comparison options and functions you can use with the SharePoint REST service.

単一値ルックアップ フィールドのクエリQuery for single value lookup fields

単一値ルックアップ フィールドのクエリは、SharePoint REST サービスでは、2 つの異なるフィールドで表されます。一方のフィールドで実際のフィールド値を表し、もう一方のフィールドはフィールド名を表します。ルックアップ フィールドの値をクエリする場合、そのデータ型の別のフィールドを指定することもできます。たとえば、ルックアップ フィールドの値が文字列の場合、クエリに文字列比較オプションを使用することができます。Single value lookup fields are represented by two separate fields in the SharePoint REST service: one field representing the actual field value, and another representing the field name. You can perform queries against the lookup field value as you would any other field of that data type. For example, if the lookup field value is a string, you can use string comparison options in your query.

ユーザーのクエリQuery for users

SharePoint REST サービスでは、ユーザーはフレンドリーなユーザー名 (表示名) で表され、エイリアスや domain\alias の組み合わせは使用されません。したがって、フレンドリーなユーザー名でユーザー クエリを作成する必要があります。In the SharePoint REST service, users are represented by the user's friendly (display) name, and not their alias or domain\alias combination. Therefore, you must construct user queries against users' friendly names.

注意

メンバーシップに基づくユーザー クエリはサポートされません。Membership-based user queries are not supported. 現在のユーザーの ID を使ってクエリを実行するための、Current 演算子の使用はサポートされていません。Usage of the Current operator to do queries using the ID of the current user is not supported.

複数値のルックアップ フィールドとユーザーのクエリQuery for multi-value lookup fields and users

複数値のルックアップ フィールドは、複数の値の文字列で返されるため、それらをクエリする方法がありません (たとえば、 Includes 要素や NotIncludes 要素に相当するものはサポートされません)。Because multi-value lookup fields are returned as a string of multiple values, there is no way to query for them (for example, the equivalent of an Includes element or NotIncludes element is not supported).

返されたアイテムの並べ替えSort returned items

$orderby クエリ オプションを使って、クエリ リターン セット内のアイテムを並べ替える方法を指定します。Use the $orderby query option to specify how to sort the items in your query return set. 複数のフィールドによって並べ替える場合は、フィールドのコンマ区切りのリストを指定します。To sort by multiple fields, specify a comma-separated list of fields. asc または desc キーワードをクエリに追加することによって、アイテムを昇順または降順に並べ替えることもできます。You can also specify whether to sort the items in ascending or descending order by appending the asc or desc keyword to your query.

返されたアイテムのページングPage through returned items

$top および $skiptoken のクエリ オプションを使って、アイテムのサブセット (使用しないとクエリによって返される) を選択します。Use the $top and $skiptoken query options to select a subset of the items that would otherwise be returned by your query.

注意

SharePoint リスト アイテムのクエリの場合、$skip クエリ オプションは機能しません。The $skip query option does not work with queries for SharePoint list items.

$top オプションを使用すると、返すために、リターン セットの最初の n 個のアイテムを選択できます。The $top option enables you to select the first n items of the return set for return. たとえば、次の URI は、予期されるリターン セットにある最初の 10 個のアイテムのみが実際に返されるよう要求します。For example, the following URI requests that only the first ten items in the prospective return set actually be returned:

http://server/site/_api/web/lists('<guid>')/items$top=10

$skiptoken オプションを使うと、指定したアイテムに達するまでアイテムをスキップし、残りのアイテムを返すことができます。The $skiptoken option enables you to skip over items until the specified item is reached and return the rest.

$skiptoken=Paged=TRUE%26p_ID=5

注意

これらのクエリ オプションを使用する場合は、OData でのページングが序数であることを考慮に入れてください。When using these query options, take into account that paging in OData is ordinal. たとえば、SharePoint リストのアイテムを表示するために [次のページ] ボタンを実装するとします。For example, suppose you are implementing a next page button to display SharePoint list items. REST サービスを使ってボタンを有効にし、クリック時に 1 から 20 のアイテム、次に 21 から 40 というように返します。You use the REST service to enable the button to return items 1 through 20 when clicked, and then items 21 through 40, and so on. ただし、次ボタンをクリックする間に別のユーザーがアイテム 4 と 18 を削除するとします。However, suppose another user deletes items 4 and 18 between clicks of the next button. このような場合、残りのアイテムの序数位置がリセットされ、アイテム 21 から 40 の表示は 2 つのアイテムをスキップして行われます。In such a case, the ordinal positioning of the remaining items is reset, and displaying items 21 through 40 actually skips over two items.

SharePoint REST サービスでサポートされる OData クエリ演算子OData query operators supported in the SharePoint REST service

サポートされているSupported サポートされていないNot supported
数値比較 Lt Le Gt Ge Eq NeNumeric comparisons Lt Le Gt Ge Eq Ne 算術演算子 (Add、Sub、Mul、Div、Mod)Arithmetic operators (Add, Sub, Mul, Div, Mod)
基本数学関数 (round、floor、ceiling)Basic math functions (round, floor, ceiling)
文字列比較 startsWith substringof Eq NeString comparisons startsWith substringof Eq Ne endsWith replace substring tolower toupper trim concatendsWith replace substring tolower toupper trim concat
日付と時刻関数 day() month() year() hour() minute() second()Date and time functions day() month() year() hour() minute() second() DateTimeRangesOverlap 演算子DateTimeRangesOverlap operator
日時が頻出する日時パターンに属するかどうか評価するQuerying as to whether a date time falls inside a recurrent date time pattern

下の図は、サポートされる OData のクエリ オプションを示しています。The following figure shows the supported OData query options.

サポートされる OData のクエリ オプションSupported OData query options

SharePoint REST サービス クエリ オプションの構文


関連項目See also