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

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 の JavaScript ライブラリ コードを使用して基本的な操作を完了する」- 「SharePoint のクライアント ライブラリ コードを使用して基本的な操作を完了する」
• SharePoint にアクセスする Windows Phone アプリを構築する

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
});

環境によって異なる 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 インターフェイスを使用してデータを読み取る」を参照してください。

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 を送信します。

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

次のコード例に示すように、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("&");
  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 要求プロパティを使う場合

バッチ ジョブのサポート

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

関連項目

• SharePoint REST サービスの概要
• SharePoint アドインのセキュリティで保護されたデータ アクセスとクライアント オブジェクト モデル
• SharePoint の外部データの操作
• OData の技術情報
• REST インターフェイスを使用してリストにカスタム アクセス許可を設定する
• SharePoint アドインの開発