次の方法で共有

SharePoint REST 要求で OData クエリ操作を使用する

  • [アーティクル]

ヒント

始める前に、次のリソースを確認してください。

SharePoint REST サービスでは、さまざまな OData クエリ文字列演算子がサポートされており、それらの演算子を使用してリクエスト データの選択、フィルタリング、並べ替えが可能です。

ヒント

SharePoint Online (およびオンプレミス SharePoint 2016 以降) REST サービスでは、OData $batch クエリ オプションを使って、サービスに対する複数の要求を 1 つの呼び出しに統合できます。 詳細とコード サンプルへのリンクについては、「REST API によりバッチ要求を発行する」を参照してください。

返されるフィールドを選択する

$select クエリ オプションを使用して、指定のリスト、リスト項目、またはエンティティ セットで表される他の SharePoint オブジェクトに対して返すフィールドを指定します。 利用可能なすべてのフィールドは、$select=* を使用して返すことができます。

注:

通常、$select クエリ オプションを使用しない場合、既定で、REST サービスは使用可能なすべてのフィールドを返します。 ただし、まれなケースとして、一部の SharePoint オブジェクトには、取得に多くのリソースを費やすプロパティが含まれていることがあります。REST サービス パフォーマンスを最適化するため、これらのプロパティは既定のクエリからは除外されており、明示的に要求する必要があります。たとえば、SPWeb.EffectiveBasePermissions プロパティは既定で返されず、$select クエリ オプションを使って明示的に要求する必要があります。

さらに、要求が他のリストとルックアップの値から予想されるフィールドを返すよう指定できます。 そのためには、$select と $expand の両方のクエリ オプションでフィールド名を指定します。 次に、例を示します。

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

一括拡張と関連アイテムの選択はサポートされません。

返されるアイテムを選択する

$filter クエリ オプションを使用して、返すアイテムを選択します。 SharePoint REST サービスでサポートされる OData クエリ演算子は、SharePoint REST サービスで使用できるフィルター クエリ比較のオプションと関数を一覧表示します。

単一値ルックアップ フィールドのクエリ

単一値参照フィールドは、SharePoint REST サービスの 2 つの個別のフィールド (実際のフィールド値を表すフィールドと、フィールド名を表すフィールド) で表されます。 そのデータ型の他のフィールドと同様に、ルックアップ フィールドの値に対してクエリを実行できます。 たとえば、ルックアップ フィールドの値が文字列の場合は、クエリで文字列比較オプションを使用できます。

ユーザーのクエリ

SharePoint REST サービスでは、ユーザーはフレンドリーなユーザー名 (表示名) で表され、エイリアスや domain\alias の組み合わせは使用されません。 したがって、フレンドリーなユーザー名でユーザー クエリを作成する必要があります。

注:

メンバーシップに基づくユーザー クエリはサポートされません。 現在のユーザーの ID を使ってクエリを実行するための、Current 演算子の使用はサポートされていません。

複数値のルックアップ フィールドとユーザーのクエリ

複数値のルックアップ フィールドは、複数の値の文字列で返されるため、それらをクエリする方法がありません (たとえば、 Includes 要素や NotIncludes 要素に相当するものはサポートされません)。

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

$orderby クエリ オプションを使って、クエリ リターン セット内のアイテムを並べ替える方法を指定します。 複数のフィールドによって並べ替える場合は、フィールドのコンマ区切りのリストを指定します。 asc または desc キーワードをクエリに追加することによって、アイテムを昇順または降順に並べ替えることもできます。

返されたアイテムのページング

$top および $skiptoken のクエリ オプションを使って、アイテムのサブセット (使用しないとクエリによって返される) を選択します。

注:

SharePoint リスト アイテムのクエリの場合、$skip クエリ オプションは機能しません。

$top オプションを使用すると、返すために、リターン セットの最初の n 個のアイテムを選択できます。 たとえば、次の URI は、予期されるリターン セットにある最初の 10 個のアイテムのみが実際に返されるよう要求します。

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

$skiptoken クエリ オプションを使うと、指定したアイテムに達するまでアイテムをスキップし、残りのアイテムを返すことができます。

GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

注:

これらのクエリ オプションを使用する場合は、OData でのページングが序数であることを考慮に入れてください。 たとえば、SharePoint リストのアイテムを表示するために [次のページ] ボタンを実装するとします。 REST サービスを使ってボタンを有効にし、クリック時に 1 から 20 のアイテム、次に 21 から 40 というように返します。 ただし、次ボタンをクリックする間に別のユーザーがアイテム 4 と 18 を削除するとします。 このような場合、残りのアイテムの序数位置がリセットされ、アイテム 21 から 40 の表示は 2 つのアイテムをスキップして行われます。

SharePoint REST サービスでサポートされる OData クエリ演算子

サポートされている サポートされていない
数値比較 (lt le gt ge eq ne) 算術演算子 (add、sub、mul、div、mod)
基本数学関数 (round、floor、ceiling)
文字列比較
startswith( {Col to query},'{string to check}' )
substringof( '{string to check}', {Col to query} )
eq
ne		 endswith、replace、substring、tolower、toupper、trim、concat
日付と時刻関数 day()、month()、year()、hour()、minute()、second() DateTimeRangesOverlap 演算子
日時が頻出する日時パターンに属するかどうか評価する

下の図は、サポートされる OData のクエリ オプションを示しています。

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

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

関連項目