SharePoint REST サービスの概要Get to know the SharePoint REST service

SharePoint では、既存の SharePoint クライアント オブジェクト モデルと比較できる REST (Representational State Transfer) サービスを導入しています。SharePoint introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. 開発者は、REST Web 要求をサポートするテクノロジを使用して SharePoint データとリモートで対話できるようになりました。Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. つまり、開発者は自身の SharePoint アドイン、ソリューション、クライアント アプリケーションから REST Web テクノロジと標準の OData (Open Data Protocol) 構文を使用して、CRUD (作成読み取り更新削除) 操作を実行できるようになりました。This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.

前提条件Prerequisites

このトピックでは、REST と REST 要求の作成方法に基本的に精通しているものとします。This topic assumes you have a basic familiarity with REST and how to construct REST requests.

SharePoint REST サービスのしくみHow the SharePoint REST service works

SharePoint では、REST を使用して、SharePoint サイトをリモートから操作できるようにする機能が追加されました。SharePoint adds the ability for you to remotely interact with SharePoint sites by using REST. これにより、標準の REST 機能をサポートする技術を使用することで SharePoint オブジェクトと直接やり取りできます。Now you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.

REST を使用して SharePoint リソースにアクセスするには、目的のクライアント オブジェクト モデル API に対応する OData 標準を使用して、REST 対応の HTTP 要求を作成します。To access SharePoint resources using REST, construct a RESTful HTTP request by using the OData standard, which corresponds to the desired client object model API. 次に例を示します。For example:

クライアント オブジェクト モデルのメソッド:Client object model method:

List.GetByTitle(listname)

REST エンドポイント:REST endpoint:

http://server/site/_api/lists/getbytitle('listname')

SharePoint の client.svc という Web サービスは HTTP 要求を処理し、Atom または JSON (JavaScript Object Notation) 形式で該当する応答をします。The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. その後、クライアント アプリケーションは、その応答を解析する必要があります。Your client application must then parse that response. 次の図は、SharePoint REST アーキテクチャの概要を示しています。The following figure shows a high-level view of the SharePoint REST architecture.

SharePoint REST サービスのアーキテクチャSharePoint REST service architecture

SharePoint REST サービスのアーキテクチャ

クライアント オブジェクト モデルは、その機能と使いやすさのため、.NET Framework 管理コード、Silverlight、または JavaScript を使用した SharePoint との通信の開発において、依然として主要な選択肢となっています。Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using .NET Framework managed code, Silverlight, or JavaScript.

SharePoint REST サービスでの HTTP コマンドの使用Use HTTP commands with the SharePoint REST service

SharePoint に組み込まれている REST 機能を使用するには、使用するクライアント オブジェクト モデル API に対応する OData 標準を使用して RESTful HTTP 要求を作成します。To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. client.svc Web サービスは HTTP 要求を処理し、Atom または JSON 形式で該当する応答をします。The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. その後、クライアント アプリケーションは、その応答を解析する必要があります。The client application must then parse that response.

SharePoint REST サービスのエンドポイントは、SharePoint クライアント オブジェクト モデルの型とメンバーに対応しています。HTTP 要求を使用することで、これらの REST エンドポイントを使用して、SharePoint エンティティ (リストやサイトなど) に対して通常の CRUD 操作を実行できます。The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD operations against SharePoint entities, such as lists and sites.

エンドポイントで実行する操作If you want to do this to an endpoint この HTTP 要求を使用するUse this HTTP request 注意点Keep in mind
リソースを読み取るRead a resource GETGET
リソースを作成または更新するCreate or update a resource POSTPOST
  • POST を使用してリストやサイトなどのエンティティを作成します。Use POST to create entities such as lists and sites.
  • SharePoint REST サービスでは、コレクションを表すエンドポイントに向けて、オブジェクト定義を含んだ POST コマンドを送信することがサポートされています。The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections.
  • POST 操作では、必須ではないプロパティはすべて既定値に設定されます。For POST operations, any properties that are not required are set to their default values.
  • POST 操作の一部として読み取り専用プロパティを設定しようとすると、サービスによって例外が返されます。If you attempt to set a read-only property as part of a POST operation, the service returns an exception.
リソースを更新または挿入するUpdate or insert a resource PUTPUT
  • 既存の SharePoint オブジェクトを更新する場合は、PUT 操作と MERGE 操作を使用します。Use PUT and MERGE operations to update existing SharePoint objects.
  • オブジェクト プロパティの set 操作を表すサービス エンドポイントは、すべて PUT 要求と MERGE 要求の両方をサポートします。Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests.
  • MERGE 要求の場合、プロパティの設定は省略可能です。プロパティを明示的に設定しなくても、現在のプロパティが保持されます。For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property.
  • PUT 要求の場合、オブジェクトの更新で必要なプロパティをすべて設定しなかった場合には、REST サービスから例外が返されます。For PUT requests, if you do not specify all required properties in object updates, the REST service returns an exception.
  • さらに、省略可能なプロパティを明示的に設定しなかった場合には、既定のプロパティが設定されます。In addition, any optional properties you do not explicitly set are set to their default properties.
リソースを削除するDelete a resource DELETEDELETE
  • 特定のエンドポイント URL に対して HTTP の DELETE コマンドを実行すると、そのエンドポイントが表していた SharePoint オブジェクトが削除されます。Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.
  • リスト、ファイル、リスト アイテムなど、再利用可能なオブジェクトの場合は、Recycle 操作になります。In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

SharePoint リソースにアクセスするための REST URL の作成Construct REST URLs to access SharePoint resources

これらの REST エンドポイントの URI は、できる限り API シグネチャの構造に近いものとします。REST サービスの主なエントリ ポイントは、指定されたコンテキストのサイト コレクションとサイトを表します。Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. The main entry points for the REST service represent the site collection and site of the specified context.

特定のサイト コレクションにアクセスするには、次の構造を使用します。To access a specific site collection, use the following construction:

http://server/site/_api/site

特定のサイトにアクセスするには、次の構造を使用します。To access a specific site, use the following construction:

http://server/site/_api/web

どちらの場合も、server はサーバーの名前、site は特定のサイトの名前 (パス名) を表します。In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

これを基本形として、ダッシュで区切ったクライアント オブジェクト モデルの API 名を使用して、オブジェクト モデルを「階層化」することで、さらに具体的な REST URI を作成することができます。From this starting point, you can then construct more specific REST URIs by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

この構文は、SocialFeedManager または SocialFollowingManager の REST API には適用されません。This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. 詳細については、以下を参照してください。For more information, see:

対応するクライアント オブジェクト モデル API のシグネチャから SharePoint REST エンドポイント URI を決定する詳細なガイドラインについては、「SharePoint REST サービス エンドポイント URI を決定する」を参照してください。For more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.

SharePoint REST エンドポイントの例SharePoint REST endpoint examples

以下の表に、SharePoint データでの作業を開始するための典型的な REST エンドポイント URL の例を示します。The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. 完全修飾の REST URL を作成するには、表に示される URL フラグメントの先頭に http://server/site/_api/ を付けます。Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. POST コマンドの場合に必要な個所では、指定された SharePoint アイテムを作成するために HTTP 要求の本文で渡す必要のあるサンプル データが表に示されています。Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. 引用符内のアイテムは実際の値に置き換える必要のある変数を表します。Items in quotes represent variables that you must replace with your values.

説明Description URL エンドポイントURL endpoint HTTP メソッドHTTP method 本文のコンテンツBody content
リストのタイトルを取得するRetrieves the title of a list web/title GETGET 該当しないNot applicable
サイト上のすべてのリストを取得するRetrieves all lists on a site lists GETGET 該当なしNot applicable
単一の 'リスト' メタデータを取得するRetrieves a single list's metadata lists/getbytitle('listname') GETGET 該当しないNot applicable
リスト内のアイテムを取得するRetrieves items within a list lists/getbytitle('listname')/items GETGET 該当なしNot applicable
ドキュメントの特定のプロパティを取得するRetrieves a specific property of a document
(この場合はドキュメント タイトル)(in this case, the document title)
lists/getbytitle('listname')?select=Title 取得GET 該当しないNot applicable
リストを作成するCreates a list lists POSTPOST サンプルを参照See sample
リストにアイテムを追加するAdds an item to a list lists/getbytitle('listname')/items POSTPOST サンプルを参照See sample

リストを作成するサンプル データ Creates a list sample data

{
  '__metadata': {
    'type': 'SP.List'
  },
  'AllowContentTypes': true,
  'BaseTemplate': 104 ,
  'ContentTypesEnabled': true,
  'Description': 'My list description ',
  'Title': 'RestTest '
}

リストにアイテムを追加するサンプル データ Adds an item to a list sample data

{
  '__metadata': {
    'type': 'SP.Data.listname.ListItem'
  },
  'Title': 'MyItem'
}

上記の JSON では、スペースを省略して listname を SharePoint リストの名前に置き換えます。In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.

バッチ ジョブのサポートBatch job support

SharePoint Online (およびオンプレミスの SharePoint 2016 以降の) REST サービスは、OData $batch クエリ オプションを使用して、複数の要求を組み合わせて 1 つのサービスへの呼び出しにすることをサポートしています。The SharePoint Online (and on-premises SharePoint 2016 or 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.

OData の技術情報OData resources

SharePoint REST サービスのトピックSharePoint REST service topics

SharePoint REST サービスの使用の詳細については、下記の参照資料を使用してください。To learn more about using the SharePoint REST service, use the following resources.

タイトルTitle 説明Description
SharePoint REST エンドポイントを使用して基本的な操作を完了するComplete basic operations using SharePoint REST endpoints SharePoint REST インターフェイスで基本的な作成、読み取り、更新、削除 (CRUD) の操作を実行します。Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface.
REST を使用したリストとリスト アイテムの操作Working with lists and list items with REST SharePoint REST インターフェイスでリストとリスト アイテムに対する基本的な CRUD 操作を実行します。Perform basic CRUD operations on lists and list items with the SharePoint REST interface.
REST を使用してフォルダーとファイルを操作するWorking with folders and files with REST SharePoint REST インターフェイスでフォルダーとファイルに対する基本的な CRUD 操作を実行します。Perform basic CRUD operations on folders and files with the SharePoint REST interface.
REST サービスで表される SharePoint データ構造内を移動するNavigate the SharePoint data structure represented in the REST service 特定の SharePoint アイテムに対する REST エンドポイントから、親サイトやそのアイテムが存在するライブラリ構造などの関連するアイテムに移動およびアクセスします。Start from a REST endpoint for a given SharePoint item, and navigate to and access related items, such as parent sites or the library structure where that item resides.
SharePoint REST サービス エンドポイント URI を決定するDetermine SharePoint REST service endpoint URIs 対応するクライアント オブジェクト モデル API のシグネチャから、SharePoint REST エンドポイント URI を決定するための一般的なガイドラインです。General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs.
SharePoint REST 要求で OData クエリ操作を使用するUse OData query operations in SharePoint REST requests さまざまな OData クエリ文字列演算子を使用して、SharePoint REST サービスからリクエスト データの選択、フィルタリング、並べ替えを行います。Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service.
REST API によりバッチ要求を発行するMake batch requests with the REST APIs 複数の要求を、REST サービスへの 1 つの呼び出しに結合します。Combine multiple requests into a single call to the REST service.
REST サービスを使用して SharePoint アイテムを同期させるSynchronize SharePoint items using the REST service SharePoint REST サービスの一部である GetListItemChangesSinceToken リソースを使用して、SharePoint とアドインまたはサービス間でアイテムを同期させます。Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service.
REST API および jQuery を使用してファイルをアップロードするUpload a file by using the REST API and jQuery この記事のコード例では、REST インターフェイスと jQuery AJAX 要求を使用して、ローカル ファイルをドキュメント ライブラリに追加してから、アップロードしたファイルを表すリスト アイテムのプロパティを変更します。The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.
REST インターフェイスを使用してリストにカスタム アクセス許可を設定するSet custom permissions on a list by using the REST interface SharePoint サイト、リスト、およびリスト アイテムは、その親のアクセス許可を継承する SecurableObject の種類です。SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. オブジェクトのカスタム アクセス許可を設定するには、継承を解除して、親からのアクセス許可の継承を停止した後、ロールの割り当てを追加または削除して、新しいアクセス許可を定義する必要があります。To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.
SharePoint ワークフローの基礎SharePoint workflow fundamentals SharePoint Server 2013 の検索 REST サービスと、REST Web 要求をサポートするテクノロジを使用してクライアント アプリケーションとモバイル アプリケーションに検索機能を追加します。Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests.
SharePoint ソーシャル フィード REST API リファレンスSocial feed REST API reference for SharePoint フィード関連タスクの SharePoint REST エンドポイント。SharePoint REST endpoints for feed-related tasks.
SharePoint でのユーザーやコンテンツのフォローに関する REST API リファレンスFollowing people and content REST API reference for SharePoint 次の人物とコンテンツの SharePoint REST エンドポイント。SharePoint REST endpoints for following people and content.
SharePoint アドインの開発Develop SharePoint Add-ins SharePoint アドインに高度な機能を組み込むのに役立つ詳細な記事とリソースについて説明します。Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins.
REST API リファレンスおよびサンプルREST API reference and samples Microsoft のツール、サービス、テクノロジを使用するための包括的な API リファレンス。Comprehensive API reference for working with Microsoft tools, services, and technologies. アプリの作成、Web サイトの開発、またはクラウドでの作業を問わず、詳細な構文、コード スニペット、ベスト プラクティスを参照することができます。Whether you're building apps, developing websites, or working with the cloud, you'll find detailed syntax, code snippets, and best practices.