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

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

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 リクエストの両方をサポートします。 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/listsGET 要求を実行します。 ブラウザーでこの 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();

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

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

次の例は、リソース エンドポイントにプロパティ名を追加して、プロパティを取得する方法を示しています。この例では、 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 要求を使用する点です。また、エンティティを更新するときは、 PUT または MERGE の HTTP 要求メソッドも渡します。これを実行するには、これらのいずれかの語を X-HTTP-Method キーの値として要求のヘッダーに追加します。 MERGE メソッドでは指定したエンティティのプロパティのみが更新されるのに対し、 PUT メソッドでは POST の本文に指定した新しいエンティティで既存のエンティティが置き換えられます。エンティティの削除には DELETE メソッドを使用します。エンティティを作成したり更新したりするときは、作成または変更するエンティティの OData 表現を HTTP 要求の本文で指定する必要があります。

SharePoint エンティティを作成、更新、削除するときのもう 1 つの重要な考慮事項は、これらの要求の認証に OAuth を使用していない場合、これらの処理にサーバーの要求フォーム ダイジェスト値が X-RequestDigest ヘッダーの値として必要であることです。この値を取得するには、 http://<site url>/_api/contextinfo に対して本文が空の POST 要求を実行し、 contextinfo エンドポイントが返す XML の d:FormDigestValue ノードの値を抽出します。次の例は、 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 要求を実行してフォーム ダイジェストの値を取得する必要はありません。代わりに、SharePoint のページが既定のマスター ページを使用している場合、次の例に示すようにそのページから JavaScript コードで値を取得することができます。この例では、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 要求は data パラメーターと type パラメーターを使って要求の本文と種類を指定しますが、クロスドメイン ライブラリ要求は body パラメーターと method パラメーターを使ってこれらの値を指定します。

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

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

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

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

    "X-RequestDigest": $("#__REQUESTDIGEST").val()

  • OAuth を使用するクラウドでホストされるアドインの場合は、まず要求を contextinfo エンドポイントに送信してフォーム ダイジェスト値を取得し、次いで「 REST インターフェイスを使用してデータを書き込む」に示されているように、その値を要求に追加します。

  • JavaScript クロスドメイン ライブラリを使用するクラウドでホストされるアドインでは、フォーム ダイジェスト値を指定する必要はありません。既定で、SP.RequestExecutor が自動でその処理を行います。(content-length 値も処理します。)

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 または他のサイト コレクションをコンテキストとして初期化する必要があります。この処理のため、クロスドメイン ライブラリ要求は表 1 に示すように URI 内の SP.AppContextSite エンドポイントを使います。表 1 に示されているサンプル URI は、@target エイリアスを使ってクエリ文字列内のターゲット URL を送信します。これは、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 および書き込み操作用の POSTPOST 要求では、 DELETE ヘッダーで MERGEPUT、または X-HTTP-Method 動詞を指定して、更新または削除操作を行うことができます。
body (または data) 要求本文でデータを送信する POST 要求 POST 要求の本文。エンドポイント URI で送信できないデータ (複合型など) を送信します。 content-length ヘッダーで使用します。
Authentication ヘッダー OAuth を使用してユーザーを認証するリモート アドイン。JavaScript またはクロスドメイン ライブラリを使用する場合は適用されません。 (Microsoft Access Control Service (ACS) セキュア トークン サーバーから取得した) OAuth アクセス トークンを送信します。このアクセス トークンは、要求に対してユーザーを認証するのに使用します。例: "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 ヘッダー POSTDELETE、または 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 によりバッチ要求を発行する」を参照してください。

関連項目