次の方法で共有

SharePoint REST サービスの概要

  • [アーティクル]

SharePoint には、既存の SharePoint クライアント オブジェクト モデルと比較できる REST (Representational State Transfer) サービスが含まれます。 開発者は、REST Web 要求をサポートするテクノロジを使用して SharePoint データとリモートで対話できるようになりました。 つまり、開発者は自身の SharePoint アドイン、ソリューション、クライアント アプリケーションから REST Web テクノロジと標準の OData (Open Data Protocol) 構文を使用して、CRUD (作成、読み取り、更新、削除) 操作を実行できるようになりました。

前提条件

このトピックでは、REST と REST 要求の作成方法に基本的に精通しているものとします。

SharePoint REST サービスのしくみ

SharePoint では、REST を使用して、SharePoint サイトをリモートから操作できるようにする機能が追加されました。 これにより、ユーザーのコードは、標準の REST 機能をサポートする技術を使用することで SharePoint オブジェクトと直接やり取りできます。

REST を使用して SharePoint リソースにアクセスするには、目的のクライアント オブジェクト モデル API に対応する OData 標準を使用して、REST 対応の HTTP 要求を作成します。 例:

var items = List.GetByTitle(listname).GetItems();

SharePoint の client.svc という Web サービスは HTTP 要求を処理し、Atom または JSON (JavaScript Object Notation) 形式で該当する応答をします。 その後、クライアント アプリケーションは、その応答を解析する必要があります。 次の図は、SharePoint REST アーキテクチャの概要を示しています。

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

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

クライアント オブジェクト モデルは、その機能と使いやすさのため、.NET Framework、Silverlight (現在は廃止)、または JavaScript (JSOM) を使用した SharePoint との通信の開発において、依然として主要な選択肢となっています。

SharePoint REST サービスでの HTTP コマンドの使用

SharePoint に組み込まれている REST 機能を使用するには、使用するクライアント オブジェクト モデル API に対応する OData 標準を使用して RESTful HTTP 要求を作成します。 client.svc Web サービスは HTTP 要求を処理し、Atom または JSON 形式で該当する応答をします。 その後、クライアント アプリケーションは、その応答を解析する必要があります。

SharePoint REST サービスのエンドポイントは、SharePoint クライアント オブジェクト モデルの型とメンバーに対応しています。 HTTP 要求を使用して、これらの REST エンドポイントを使って、リストやサイトなどの SharePoint エンティティに対して典型的な CRUD 操作を行うことができます。

エンドポイントで実行する操作 この HTTP 要求を使用する 注意点
リソースを読み取る GET
リソースを作成または更新する POST
  • POST を使用してリストやサイトなどのエンティティを作成します。
  • SharePoint REST サービスでは、コレクションを表すエンドポイントに向けて、オブジェクト定義を含んだ POST コマンドを送信することがサポートされています。
  • POST 操作では、必須ではないプロパティはすべて既定値に設定されます。
  • POST 操作の一部として読み取り専用プロパティを設定しようとすると、サービスによって例外が返されます。
リソースを更新または挿入する PUT
  • 既存の SharePoint オブジェクトを更新する場合は、PUT 操作と MERGE 操作を使用します。
  • オブジェクト プロパティの set 操作を表すサービス エンドポイントは、すべて PUT 要求と MERGE 要求の両方をサポートします。
  • MERGE 要求の場合、プロパティの設定は省略可能です。プロパティを明示的に設定しなくても、現在のプロパティが保持されます。
  • PUT 要求の場合、オブジェクトの更新で必要なプロパティをすべて設定しなかった場合には、REST サービスから例外が返されます。
  • さらに、省略可能なプロパティを明示的に指定しなかった場合には、既定のプロパティが設定されます。
リソースを削除する DELETE
  • 特定のエンドポイント URL に対して HTTP の DELETE コマンドを実行すると、そのエンドポイントが表していた SharePoint オブジェクトが削除されます。
  • リスト、ファイル、リスト アイテムなど、再利用可能なオブジェクトは、Recycle 操作になります。

SharePoint リソースにアクセスするための REST URL の作成

これらの REST エンドポイントの URI は、できる限り API シグネチャの構造に近いものとします。 REST サービスの主なエントリ ポイントは、指定されたコンテキストのサイト コレクションとサイトを表します。

特定のサイト コレクションにアクセスするには、次の構造を使用します。

https://{site_url}/_api/site

特定のサイトにアクセスするには、次の構造を使用します。

https://{site_url}/_api/web

どちらの場合も、server はサーバーの名前、site は特定のサイトの名前 (パス名) を表します。

これを基本形として、ダッシュで区切ったクライアント オブジェクト モデルの API 名を使用して、オブジェクト モデルを「階層化」することで、さらに具体的な REST URI を作成することができます。

この構文は、SocialFeedManager または SocialFollowingManager の REST API には適用されません。 詳細については、以下を参照してください。

対応するクライアント オブジェクト モデル API のシグネチャから SharePoint REST エンドポイント URI を決定する詳細なガイドラインについては、「SharePoint REST サービス エンドポイント URI を決定する」を参照してください。

SharePoint REST エンドポイントの例

以下の表に、SharePoint データでの作業を開始するための典型的な REST エンドポイント URL の例を示します。 完全修飾の REST URL を作成するには、表に示される URL フラグメントの先頭に http://server/site/_api/ を付けます。 POST コマンドの場合に必要な個所では、指定された SharePoint アイテムを作成するために HTTP 要求の本文で渡す必要のあるサンプル データが表に示されています。 引用符内のアイテムは実際の値に置き換える必要のある変数を表します。

説明 URL エンドポイント HTTP メソッド 本文のコンテンツ
サイトのタイトルを取得する web/title GET 該当しない
サイト上のすべてのリストを取得する lists GET 該当なし
単一の 'リスト' メタデータを取得する lists/getbytitle('listname') GET 該当しない
リスト内のアイテムを取得する lists/getbytitle('listname')/items GET 該当なし
リストの特定のプロパティを取得する
(この場合はリスト タイトル)		 lists/getbytitle('listname')?select=Title GET 該当しない
リストを作成する lists POST サンプルを参照
リストにアイテムを追加する lists/getbytitle('listname')/items POST サンプルを参照

リストを作成するサンプル データ

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

リストにアイテムを追加するサンプル データ

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

上記の JSON では、スペースを省略して listname を SharePoint リストの名前に置き換えます。

バッチ ジョブのサポート

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

OData の技術情報

SharePoint REST サービスのトピック

SharePoint REST サービスの使用の詳細については、下記の参照資料を使用してください。

タイトル 説明
SharePoint REST エンドポイントを使用して基本的な操作を完了する SharePoint REST インターフェイスで基本的な作成、読み取り、更新、削除 (CRUD) の操作を実行します。
REST を使用したリストとリスト アイテムの操作 SharePoint REST インターフェイスでリストとリスト アイテムに対する基本的な CRUD 操作を実行します。
REST を使用してフォルダーとファイルを操作する SharePoint REST インターフェイスでフォルダーとファイルに対する基本的な CRUD 操作を実行します。
REST サービスで表される SharePoint データ構造内を移動する 特定の SharePoint アイテムに対する REST エンドポイントから、親サイトやそのアイテムが存在するライブラリ構造などの関連するアイテムに移動およびアクセスします。
SharePoint REST サービス エンドポイント URI を決定する 対応するクライアント オブジェクト モデル API のシグネチャから、SharePoint REST エンドポイント URI を決定するための一般的なガイドラインです。
SharePoint REST 要求で OData クエリ操作を使用する さまざまな OData クエリ文字列演算子を使用して、SharePoint REST サービスからリクエスト データの選択、フィルタリング、並べ替えを行います。
REST API によりバッチ要求を発行する 複数の要求を、REST サービスへの 1 つの呼び出しに結合します。
REST サービスを使用して SharePoint アイテムを同期させる SharePoint REST サービスの一部である GetListItemChangesSinceToken リソースを使用して、SharePoint とアドインまたはサービス間でアイテムを同期させます。
REST API および jQuery を使用してファイルをアップロードする この記事のコード例では、REST インターフェイスと jQuery AJAX 要求を使用して、ローカル ファイルをドキュメント ライブラリに追加してから、アップロードしたファイルを表すリスト アイテムのプロパティを変更します。
REST インターフェイスを使用してリストにカスタム アクセス許可を設定する SharePoint サイト、リスト、およびリスト アイテムは、その親のアクセス許可を継承する SecurableObject の種類です。 オブジェクトのカスタム アクセス許可を設定するには、継承を解除して、親からのアクセス許可の継承を停止した後、ロールの割り当てを追加または削除して、新しいアクセス許可を定義する必要があります。
SharePoint ワークフローの基礎 SharePoint Server 2013 の検索 REST サービスと、REST Web 要求をサポートするテクノロジを使用してクライアント アプリケーションとモバイル アプリケーションに検索機能を追加します。
SharePoint ソーシャル フィード REST API リファレンス フィード関連タスクの SharePoint REST エンドポイント。
SharePoint でのユーザーやコンテンツのフォローに関する REST API リファレンス 次の人物とコンテンツの SharePoint REST エンドポイント。
SharePoint アドインの開発 SharePoint アドインに高度な機能を組み込むのに役立つ詳細な記事とリソースについて説明します。