SharePoint REST エンドポイントを使用して基本的な操作を完了する

[アーティクル]
04/08/2023

SharePoint で提供される Representational State Transfer (REST) インターフェイスを使用すると、基本的な作成、読み取り、更新、削除 (CRUD) の操作を実行できます。 REST インターフェイスは、他の SharePoint クライアント API で利用可能なすべての SharePoint エンティティおよび操作を公開します。 REST を使用する 1 つのメリットは、SharePoint ライブラリまたはクライアントアセンブリへの参照を追加する必要がないことです。その代わりに、適当なエンドポイントに HTTP 要求を実行して、Web、リスト、リストアイテムなどの SharePoint エンティティを取得したり更新したりします。

SharePoint REST インターフェイスとそのアーキテクチャの紹介については、「SharePoint REST サービスの概要」を参照してください。

SharePoint コアエンティティとの連携方法については、「REST を使用してリストとリストアイテムを操作する」と「REST を使用してフォルダーとファイルを操作する」を参照してください。

C# で記述された ASP.NET Web アプリケーションのコンテキストでこれらの操作の多くを実行する方法を示しているサンプルについては、「SharePoint-Add-in-REST-OData-BasicDataOperations」を参照してください。

SharePoint プラットフォームで利用できる API セットの詳細については、「SharePoint 2013 での適切な API セットの選択」を参照してください。

その他のクライアント API の使用方法については、次を参照してください。

SharePoint REST サービスにおける HTTP の動作

SharePoint REST サービスのエンドポイントは、SharePoint クライアントオブジェクトモデルの型とメンバーに対応しています。 HTTP 要求を使用することで、これらの REST エンドポイントを使用して、SharePoint エンティティ (リストやサイトなど) に対して通常の CRUD (作成、読み取り、更新、削除) 操作を実行できます。

通常、Read 操作を表すエンドポイントは HTTP の GET コマンドに相当し、作成操作を表すエンドポイントは HTTP の POST コマンドに相当し、更新または挿入操作を表すエンドポイントは HTTP の PUT コマンドに相当します。

SharePointでは、 POST を使用してリストやサイトなどのエンティティを作成します。 SharePoint REST サービスでは、オブジェクトの定義を含んだ POST コマンドの、コレクションを表すエンドポイントへの送信がサポートされます。たとえば、新しいリストオブジェクトの定義を ATOM 形式で含んだ POST コマンドを次の URL に送信して SharePoint リストを作成することができます。

http://<site url>/_api/web/lists

POST 操作では、必須ではないプロパティはすべて既定値に設定されます。 POST 操作の一部として読み取り専用プロパティを設定すると、サービスによって例外が返されます。

既存の SharePoint オブジェクトを更新する場合は、PUT 操作と MERGE 操作を使用します。オブジェクトプロパティの set 操作を表すサービスエンドポイントは、 PUT 要求と MERGE 要求の両方をサポートします。プロパティを明示的に設定しなくても、現在のプロパティが保持されます。しかし、PUT コマンドの場合、明示的に設定しないプロパティについては既定のプロパティが設定されます。さらに、HTTP PUT コマンドを使用したオブジェクトの更新では、必須のプロパティの指定が全部揃っていないと REST サービスから例外が返されます。

特定のエンドポイント URL に対して HTTP の DELETE コマンドを実行すると、そのエンドポイントが表していた SharePoint オブジェクトが削除されます。リスト、ファイル、リストアイテムなど、再利用可能なオブジェクトの場合は、結果的に Recycle 操作になります。

SharePoint REST インターフェイスを使用してデータを読み取る

SharePoint に組み込まれている REST 機能を使用するには、使用するクライアントオブジェクトモデル API に対応する OData 標準を使用して RESTful HTTP 要求を作成します。各 SharePoint エンティティはターゲットとする SharePoint サイトのエンドポイントで公開され、そのメタデータは XML または JSON 形式で表されます。 HTTP 要求は JavaScript や C# に限らず任意の言語で実行できます。

REST エンドポイントから情報を読み取るには、エンドポイントの URL と、エンドポイントで公開されている SharePoint エンティティの OData 表現の両方を知っている必要があります。たとえば、特定の SharePoint サイトのリストをすべて取得するには、http://<site url>/_api/web/lists に GET 要求を実行します。ブラウザーでこの URL にアクセスし、返される XML を確認できます。コードで要求を実行する際には、リストの OData 表現を XML と JSON のどちらで受け取るかを指定できます。

次の C# コードでは、JQuery を使用してサイトのリストすべての JSON 表現を返す GET 要求を実行する方法を示しています。ここでは、accessToken 変数に格納されている有効な OAuth アクセストークンがあることも前提としています。アドイン Web 内部からこの呼び出しを実行する場合、SharePoint ホスト型アドイン内で実行する場合と異なり、アクセストークンは不要です。ブラウザークライアントで実行しているコードからアクセストークンを取得できないことにご注意ください。サーバーで実行しているコードからアクセストークンを取得する必要があります。

アクセストークンの取得方法の詳細については、「SharePoint のアドインのコンテキストトークン OAuth フロー」と「SharePoint アドインの認証コード OAuth フロー」を参照してください。

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

SharePoint クロスドメインライブラリを使用しながら JavaScript でアドインを作成する場合には、この要求は少し違ったものになります。この場合、アクセストークンを提供する必要がありません。

次のコードは、クロスドメインライブラリを使用し、リストの OData 表現を JSON ではなく XML で受け取る場合、この要求がどのようになるかを示しています (Atom は既定の応答形式なので、Accept ヘッダーを含める必要はありません。) クロスドメインライブラリ使用の詳細については、「クロスドメインライブラリを使用してアドインから SharePoint のデータにアクセスする」を参照してください。

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
  {
    url: appweburl +
          "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
          hostweburl + "'",
    method: "GET",
    success: successHandler,
    error: errorHandler
  }
);

次のコードは、C# を使用してサイトのすべてのリストの JSON 表現を要求する方法の例です。ここでは、accessToken 変数に格納されている OAuth アクセストークンがあることを前提としています。

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

リソースと共に返されないプロパティの取得

リソースを取得すると多くのプロパティ値が返されますが、一部のプロパティでは、 GET 要求をプロパティエンドポイントに直接送信する必要があります。これは、SharePoint エンティティを表すプロパティの場合に一般的です。

次の例は、リソースエンドポイントにプロパティ名を追加して、プロパティを取得する方法を示しています。この例では、 Author プロパティの値が File リソースから取得されます。

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/author

JSON 形式で結果を取得するには、"application/json;odata=verbose" に設定した Accept ヘッダーを含めます。

REST インターフェイスを使用してデータを書き込む

適切なエンドポイントに対する RESTful HTTP 要求を作成すると、データを読み取るときと同じように SharePoint エンティティの作成および更新を実行できます。ただし、重要な違いの 1 つは、 POST 要求を使用することです。エンティティを更新するときは、要求のヘッダーに X-HTTP メソッド キーの値としてこれらの用語のいずれかを追加して、PUT または MERGE HTTP 要求メソッドも渡します。 MERGE メソッドは、指定したエンティティのプロパティのみを更新しますが、PUT メソッドは既存のエンティティを POST の本文で指定した新しいエンティティに置き換えます。 DELETE メソッドを使用してエンティティを削除します。エンティティを作成または更新するときには、作成または変更するエンティティの OData 表現を HTTP 要求の本文で指定する必要があります。

SharePoint エンティティを作成、更新、削除するときのもう 1 つの重要な考慮事項は、これらの要求の認証に OAuth を使用していない場合、これらの処理にサーバーの要求フォームダイジェスト値が X-RequestDigest ヘッダーの値として必要であることです。この値を取得するには、に対して本文が空の http://<site url>/_api/contextinfo 要求を実行し、 d:FormDigestValue エンドポイントが返す XML のノードの値を抽出します。次の例は、 contextinfo エンドポイントに対する HTTP 要求を C# で示しています。

HttpWebRequest endpointRequest =(HttpWebRequest)HttpWebRequest.Create(
                                    "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

「SharePoint アドインの承認と認証」で説明している認証と承認のフローを使用している場合は、要求に要求のダイジェストを含める必要はありません。

JavaScript クロスドメインライブラリを使用している場合は、SP.RequestExecutor がフォームダイジェスト値の取得と送信を処理します。

SharePoint ホスト型 SharePoint アドインを作成する場合、別途 HTTP 要求を実行してフォームダイジェストの値を取得する必要はありません。代わりに、JavaScript コードで SharePoint ページから値を取得できます (ページが既定のマスターページを使用している場合)。次の例でこれを示します。ここでは、JQuery を使用し、リストを作成します。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: {
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

次の例は、前の例で作成されたリストを更新する方法を示しています。この例ではリストのタイトルを変更し、JQuery を使用しますが、SharePoint ホスト型アドインでこの操作を実行することを前提としています。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: {
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

要求ヘッダーの IF-MATCH キーの値では、リストまたはリストアイテムの etag 値を指定します。この特定の値はリストおよびリストアイテムのみに適用され、それらのエンティティを更新するときに同時実行の問題を回避することが目的です。前の例ではこの値にアスタリスク (*) を使用しています。この値は同時実行の問題を心配する理由がない場合に使用できます。それ以外の場合は、エンティティを取得する GET 要求を実行してリストまたはリストアイテムの etag 値を取得する必要があります。結果の HTTP 応答の応答ヘッダーは、この etag を ETag キーの値として渡します。この値はまた、エンティティメタデータにも含まれます。

次の例は、リスト情報を含む XML ノードの開始の <entry> タグを示しています。 m:etag プロパティに etag 値が含まれます。

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

REST によるサイトの作成

次の例は、JavaScript でサイトを作成する方法を示しています。

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: {
        "accept": "application/json; odata=verbose",
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    success: doSuccess,
    error: doError
});

注:

WebTemplate を 'sts' に設定すると、最新のホームページが作成されます。従来のホームページを作成するには、WebTemplate を 'sts #0' に設定します。

環境によって異なる REST 要求の方法

HTTP 要求の構築と送信は言語、ライブラリ、アドインタイプなどによって異なるため、1 つの環境から別の環境に要求を変換するときに 1 つ以上の要求コンポーネントを変更する必要が生じることは珍しくありません。たとえば、jQuery AJAX 要求では データ パラメーターと型パラメーターを使用して要求本文と型を指定しますが、クロスドメインライブラリ要求では body パラメーターと method パラメーターを使用してこれらの値を指定します。

以下のセクションでは、環境による他の一般的な相違について説明します。

フォームダイジェスト値を取得および送信する方法はアドインに依存する

POST 要求を送信するときは、 X-RequestDigest ヘッダーにフォームダイジェスト値が含まれている必要があります。ただし、その値を取得して送信する方法はアドインごとに異なります。

SharePoint ホスト型アドインの場合は、次のヘッダーを渡すだけです。

"X-RequestDigest": $("#__REQUESTDIGEST").val()
OAuth を使用するクラウドでホストされるアドインの場合は、まず要求を contextinfo エンドポイントに送信してフォームダイジェスト値を取得し、次いで「 REST インターフェイスを使用してデータを書き込む」に示されているように、その値を要求に追加します。
JavaScript クロスドメインライブラリを使用するクラウドホスト型アドインでは、フォームダイジェスト値を指定する必要はありません。既定では、SP。RequestExecutor によって自動的に処理されます。 (コンテンツ長の値も処理します)。

OAuth を使うアドインは、要求でアクセストークンを渡す必要がある

クラウドでホストされるアドインは、OAuth またはクロスドメインライブラリを使って SharePoint データへのアクセスを承認します。リモート Web サーバー上で実行されるコードを持つアドインコンポーネントは、OAuth を使って SharePoint データへのアクセスを承認する必要があります。この場合、アクセストークンを送信するために Authorization ヘッダーを含める必要があります。 HTTPWebRequest オブジェクトに承認ヘッダーを追加する例については、「SharePoint REST インターフェイスを使用してデータを読み取る」を参照してください。

注:

JavaScript で記述され、クラウドでホストされるアドインコンポーネントは、クロスドメインライブラリ内の SP.RequestExecutor オブジェクトを使って SharePoint データにアクセスする必要があります。クロスドメインライブラリ要求はアクセストークンを含める必要はありません。

OAuth アクセストークンとそれらを取得する方法の詳細は、「SharePoint のアドインのコンテキストトークン OAuth フロー」および「SharePoint アドインの認証コード OAuth フロー」を参照してください。

SP.AppContextSite を使ってコンテキストを変更するには、クロスドメイン要求のエンドポイントの URI を使用する

要求は、要求の url プロパティで指定されているリソースエンドポイントに送信されます。エンドポイント URI は次の形式で指定します。

<site url>/_api/<context>/<resource> (例: https://contoso.com/_api/web/lists)

クロスドメインライブラリ要求は、アドイン Web 上のデータにアクセスするときにこの形式を使用します。これは、クロスドメインライブラリ要求の既定のコンテキストです。ただし、ホスト Web または別のサイトコレクション上のデータにアクセスするには、要求をコンテキストとしてホスト Web またはその他のサイトコレクションを初期化する必要があります。これを行うには、SP を使用 します。 表 1 に示すように、URI の AppContextSite エンドポイント。表 1 の URI の例では、URL に特殊文字 (':') が含まれているため、 @target エイリアスを使用してクエリ文字列内のターゲット URL を送信します。

注:

クロスドメインライブラリを使うときには、クラウドでホストされるアドインが SharePoint データにアクセスできるようにするためにアドイン Web インスタンスが必要となります。

表 1. SP.AppContextSite エンドポイントを使って要求のコンテキストを変更する

アドインの種類	クロスドメインでのデータアクセスのシナリオ	エンドポイント URI の例
クラウドホスト型	クロスドメインライブラリを使ってホスト Web データにアクセスする JavaScript アドインコンポーネント	`<app web url>/_api/SP.AppContextSite(@target)/web/lists?@target='<host web url>'`
クラウドホスト型	クロスドメインライブラリを使ってホスト Web 以外のサイトコレクション内のデータにアクセスする JavaScript アドインコンポーネント (テナントスコープアドインのみ)	`<app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'`
SharePoint ホスト型	別のサイトコレクション内のデータにアクセスするアドイン Web コンポーネント (テナントスコープアドインのみ)	`<app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'`

注:

クロスドメインデータアクセスでは、適切なアドインのアクセス許可も必要です。詳しくは、「ホスト Web からのデータアクセス」および「サイトコレクション間でのデータアクセス」を参照してください。

次のコード例に示すように、SharePoint アドインはアドインページのクエリ文字列からアドイン Web URL とホスト Web URL を取得できます。この例には、クロスドメインライブラリ (ホスト Web 上の SP.RequestExecutor.js ファイルで定義される) を参照する方法も示されています。この例は、アドインが SharePoint から起動することを想定しています。アドインが SharePoint から起動しない場合に SharePoint コンテキストを正しく設定するためのガイダンスは、「SharePoint アドインの認証コード OAuth フロー」をご覧ください。

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&amp;");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

REST 要求で使うプロパティ

表 2 に、SharePoint REST サービスの HTTP 要求で一般に使われるプロパティを示します。

表 2. HTTP 要求で REST 要求プロパティを使う場合

プロパティ	必要な場合	説明
url	すべての要求	REST リソースエンドポイントの URL。例: `http://<site url>/_api/web/lists`
method (または type)	すべての要求	HTTP 要求メソッド: 読み取り操作用の GET および書き込み操作用の POST。 POST 要求では、 DELETE ヘッダーで MERGE、 PUT、または X-HTTP-Method 動詞を指定して、更新または削除操作を行うことができます。
body (または data)	要求本文でデータを送信する POST 要求	POST 要求の本文。エンドポイント URI で送信できないデータ (複合型など) を送信します。 content-length ヘッダーで使用します。
Authentication ヘッダー	OAuth を使用してユーザーを認証するリモートアドイン。JavaScript またはクロスドメインライブラリを使用する場合は適用されません。	要求のユーザーの認証に使用される OAuth アクセストークン (Microsoft Access Control Service (ACS) のセキュリティで保護されたトークンサーバーから取得) を送信します。例: `"Authorization": "Bearer " + accessToken`、は `accessToken` トークンを格納する変数を表します。トークンは、サーバー側コードを使用して取得する必要があります。
X-RequestDigest ヘッダー	POST 要求 (SP.RequestExecutor 要求を除く)	OAuth を使用するリモートアドインは、エンドポイントからフォームダイジェスト値を `http://<site url>/_api/contextinfo` 取得できます。 SharePoint ホスト型アドインは、 #__REQUESTDIGEST ページコントロールから値を取得できます (SharePoint ページで使用できる場合)。「 REST インターフェイスを使用してデータを書き込む」を参照してください。
accept ヘッダー	SharePoint メタデータを返す要求	サーバーからの応答データの形式を指定します。既定の形式はです `application/atom+xml`。例: `"accept":"application/json;odata=verbose"`
content-type ヘッダー	要求本文でデータを送信する POST 要求	クライアントがサーバーに送信するデータの形式を指定します。既定の形式はです `application/atom+xml`。例: `"content-type":"application/json;odata=verbose"`
content-length ヘッダー	要求本文でデータを送信する POST 要求 (SP.RequestExecutor 要求を除く)	コンテンツの長さを指定します。例: `"content-length":requestBody.length`
IF-MATCH ヘッダー	DELETE 操作、MERGE 操作、または PUT 操作に対する POST 要求。主にリストとライブラリの変更に使用します。	変更されたオブジェクトが最後に取得されてから変更されていないことを確認する方法を提供します。または、次の例に示すように、変更を上書きするように指定できます。 `"IF-MATCH":"*"`
X-HTTP-Method ヘッダー	POST、 DELETE、または MERGE 操作に対する PUT 要求	要求で更新または削除操作を実行するように指定する場合に使用します。例: `"X-HTTP-Method":"PUT"`
binaryStringRequestBody	本文でバイナリデータを送信する SP.RequestExecutor POST 要求	要求本文がバイナリ文字列であるかどうかを指定します。 Boolean。
binaryStringResponseBody	バイナリデータを返す SP.RequestExecutor 要求	応答がバイナリ文字列であるかどうかを指定します。 Boolean。

バッチジョブのサポート

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

次の方法で共有

SharePoint REST エンドポイントを使用して基本的な操作を完了する

SharePoint REST サービスにおける HTTP の動作

SharePoint REST インターフェイスを使用してデータを読み取る

リソースと共に返されないプロパティの取得

REST インターフェイスを使用してデータを書き込む

REST によるサイトの作成

環境によって異なる REST 要求の方法

フォームダイジェスト値を取得および送信する方法はアドインに依存する

OAuth を使うアドインは、要求でアクセストークンを渡す必要がある

SP.AppContextSite を使ってコンテキストを変更するには、クロスドメイン要求のエンドポイントの URI を使用する

REST 要求で使うプロパティ

バッチジョブのサポート

関連項目

その他のリソース

次の方法で共有

SharePoint REST エンドポイントを使用して基本的な操作を完了する

SharePoint REST サービスにおける HTTP の動作

SharePoint REST インターフェイスを使用してデータを読み取る

リソースと共に返されないプロパティの取得

REST インターフェイスを使用してデータを書き込む

REST によるサイトの作成

環境によって異なる REST 要求の方法

フォーム ダイジェスト値を取得および送信する方法はアドインに依存する

OAuth を使うアドインは、要求でアクセス トークンを渡す必要がある

SP.AppContextSite を使ってコンテキストを変更するには、クロスドメイン要求のエンドポイントの URI を使用する

REST 要求で使うプロパティ

バッチ ジョブのサポート

関連項目

その他のリソース

フォームダイジェスト値を取得および送信する方法はアドインに依存する

OAuth を使うアドインは、要求でアクセストークンを渡す必要がある

バッチジョブのサポート