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

SharePoint で提供される Representational State Transfer (REST) インターフェイスを使用すると、基本的な作成、読み取り、更新、削除 (CRUD) の操作を実行できます。You can perform basic create, read, update, and delete (CRUD) operations by using the Representational State Transfer (REST) interface provided by SharePoint. REST インターフェイスは、他の SharePoint クライアント API で利用可能なすべての SharePoint エンティティおよび操作を公開します。The REST interface exposes all the SharePoint entities and operations that are available in the other SharePoint client APIs. REST を使用する 1 つのメリットは、SharePoint ライブラリまたはクライアント アセンブリへの参照を追加する必要がないことです。One advantage of using REST is that you don't have to add references to any SharePoint libraries or client assemblies. その代わりに、適当なエンドポイントに HTTP 要求を実行して、Web、リスト、リスト アイテムなどの SharePoint エンティティを取得したり更新したりします。Instead, you make HTTP requests to the appropriate endpoints to retrieve or update SharePoint entities, such as webs, lists, and list items.

SharePoint REST インターフェイスとそのアーキテクチャの紹介については、「SharePoint REST サービスの概要」を参照してください。For an introduction to the SharePoint REST interface and its architecture, see Get to know the SharePoint REST service.

SharePoint コア エンティティとの連携方法については、「REST を使用してリストとリスト アイテムを操作する」と「REST を使用してフォルダーとファイルを操作する」を参照してください。For information about how to work with core SharePoint entities, see Working with lists and list items with REST and Working with folders and files with REST.

C# で記述された ASP.NET Web アプリケーションのコンテキストでこれらの操作の多くを実行する方法を示しているサンプルについては、「SharePoint-Add-in-REST-OData-BasicDataOperations」を参照してください。For a sample that shows you how to do many of these operations in the context of an ASP.NET web application written in C#, see SharePoint-Add-in-REST-OData-BasicDataOperations.

SharePoint プラットフォームで利用できる API セットの詳細については、「SharePoint 2013 での適切な API セットの選択」を参照してください。For information about the sets of APIs available on the SharePoint platform, see Choose the right API set in SharePoint.

その他のクライアント API の使用方法については、次を参照してください。For information about how to use the other client APIs, see:

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

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

通常、Read 操作を表すエンドポイントは HTTP の GET コマンドに相当し、作成操作を表すエンドポイントは HTTP の POST コマンドに相当し、更新または挿入操作を表すエンドポイントは HTTP の PUT コマンドに相当します。Typically, endpoints that represent Read operations map to HTTP GET commands, endpoints that represent create operations map to HTTP POST commands, and endpoints that represent update or insert operations map to HTTP PUT commands.

SharePointでは、 POST を使用してリストやサイトなどのエンティティを作成します。SharePoint REST サービスでは、オブジェクトの定義を含んだ POST コマンドの、コレクションを表すエンドポイントへの送信がサポートされます。たとえば、新しいリスト オブジェクトの定義を ATOM 形式で含んだ POST コマンドを次の URL に送信して SharePoint リストを作成することができます。In SharePoint, use POST to create entities such as lists and sites. The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections. For example, you could send a POST command that included a new list object definition in ATOM to the following URL, to create a SharePoint list:

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

\*\*POST\*\* 操作では、必須ではないプロパティはすべて既定値に設定されます。 \*\*POST\*\* 操作の一部として読み取り専用プロパティを設定すると、サービスによって例外が返されます。For **POST** operations, any properties that are not required are set to their default values. If you attempt to set a read-only property as part of a **POST** operation, the service returns an exception.

既存の SharePoint オブジェクトを更新する場合は、 PUT および MERGE 操作を使用します。オブジェクト プロパティ set 操作を表すサービス エンドポイントは、すべて PUT リクエストと MERGE リクエストの両方をサポートします。 MERGE リクエストの場合、プロパティの設定は省略可能です。プロパティを明示的に設定しなくても、現在のプロパティが保持されます。ただし、 PUT コマンドの場合、プロパティを明示的に設定しなかった場合には、既定のプロパティが設定されます。さらに、HTTP PUT コマンドを使用したオブジェクトの更新で必要なプロパティをすべて設定しなかった場合には、REST サービスから例外が返されます。Use PUT and MERGE operations to update existing SharePoint objects. Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests. For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property. For PUT commands, however, any properties you do not explicitly set are set to their default properties. In addition, if you do not specify all required properties in object updates when using HTTP PUT commands, the REST service returns an exception.

特定のエンドポイント URL に対して HTTP の DELETE コマンドを実行すると、そのエンドポイントが表していた SharePoint オブジェクトが削除されます。リスト、ファイル、リスト アイテムなど、再利用可能なオブジェクトの場合は、結果的に Recycle 操作になります。Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint. In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

SharePoint REST インターフェイスを使用してデータを読み取るReading data with the SharePoint REST interface

SharePoint に組み込まれている REST 機能を使用するには、使用するクライアント オブジェクト モデル API に対応する OData 標準を使用して RESTful HTTP 要求を作成します。各 SharePoint エンティティはターゲットとする SharePoint サイトのエンドポイントで公開され、そのメタデータは XML または JSON 形式で表されます。HTTP 要求は JavaScript や C# に限らず任意の言語で実行できます。To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request, using the OData standard, which corresponds to the client object model API you want to use. Each SharePoint entity is exposed at an endpoint on the SharePoint site that you are targeting, and its metadata is represented in either XML or JSON format. You can make the HTTP requests in any language, including but not limited to JavaScript and C#.

REST エンドポイントから情報を読み取るには、エンドポイントの URL と、エンドポイントで公開されている SharePoint エンティティの OData 表現の両方を知っている必要があります。To read information from a REST endpoint, you must know both the URL of the endpoint and the OData representation of the SharePoint entity that is exposed at that endpoint. たとえば、特定の SharePoint サイトのリストをすべて取得するには、http://<site url>/_api/web/listsGET 要求を実行します。For example, to retrieve all the lists in a specific SharePoint site, you would make a GET request to http://<site url>/_api/web/lists. ブラウザーでこの URL にアクセスし、返される XML を確認できます。You can navigate to this URL in your browser and see the XML that gets returned. コードで要求を実行する際には、リストの OData 表現を XML と JSON のどちらで受け取るかを指定できます。When you make the request in code, you can specify whether to receive the OData representation of the lists in XML or JSON.

次の C# コードでは、JQuery を使用してサイトのリストすべての JSON 表現を返す GET 要求を実行する方法を示しています。The following C# code demonstrates how to make this GET request that returns a JSON representation of all of a site's lists by using JQuery. ここでは、accessToken 変数に格納されている有効な OAuth アクセス トークンがあることも前提としています。It also assumes that you have a valid OAuth access token that is stored in the accessToken variable. アドイン Web 内部からこの呼び出しを実行する場合、SharePoint ホスト型アドイン内で実行する場合と異なり、アクセス トークンは不要です。You do not need the access token if you make this call from inside an add-in web, as you would in a SharePoint-hosted add-in. ブラウザー クライアントで実行しているコードからアクセス トークンを取得できないことにご注意ください。Note that you cannot obtain an access token from code that is running on a browser client. サーバーで実行しているコードからアクセス トークンを取得する必要があります。You must obtain the access token from code that is running on a server.

アクセス トークンの取得方法の詳細については、「SharePoint のアドインのコンテキスト トークン OAuth フロー」と「SharePoint アドインの認証コード OAuth フロー」を参照してください。For more information about how you can obtain an access token, see Context Token OAuth flow for SharePoint Add-ins and Authorization Code OAuth flow for SharePoint Add-ins.


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 でアドインを作成する場合には、この要求は少し違ったものになります。This request would look a little different if you are writing your add-in in JavaScript while using the SharePoint cross-domain library. この場合、アクセス トークンを提供する必要がありません。In this case, you don't need to provide an access token.

次のコードは、クロスドメイン ライブラリを使用し、リストの OData 表現を JSON ではなく XML で受け取る場合、この要求がどのようになるかを示しています The following code demonstrates how this request would look if you are using the cross-domain library and want to receive the OData representation of the lists as XML instead of JSON. (Atom は既定の応答形式なので、Accept ヘッダーを含める必要はありません。) クロスドメイン ライブラリ使用の詳細については、「クロスドメイン ライブラリを使用してアドインから SharePoint のデータにアクセスする」を参照してください。(Because Atom is the default response format, you don't have to include an Accept header.) For more information about using the cross-domain library, see Access SharePoint data from add-ins using the cross-domain library.

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 表現を要求する方法の例です。The code in the following example shows you how to request a JSON representation of all of the lists in a site by using C#. ここでは、accessToken 変数に格納されている OAuth アクセス トークンがあることを前提としています。It assumes that you have an OAuth access token that you are storing in the accessToken variable.

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


リソースと共に返されないプロパティの取得Getting properties that aren't returned with the resource

リソースを取得する際には多くのプロパティ値が返されますが、プロパティが SharePoint エンティティを表す場合は、通常、プロパティ エンドポイントに GET 要求を直接送信する必要があります。Many property values are returned when you retrieve a resource, but for some properties, you have to send a GET request directly to the property endpoint. This is typical of properties that represent SharePoint entities.

次の例は、リソース エンドポイントにプロパティ名を追加して、プロパティを取得する方法を示しています。この例では、 Author プロパティの値が File リソースから取得されます。The following example shows how to get a property by appending the property name to the resource endpoint. The example gets the value of the Author property from a File resource.

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

JSON 形式で結果を取得するには、"application/json;odata=verbose" に設定した Accept ヘッダーを含めます。To get the results in JSON format, include an Accept header set to "application/json;odata=verbose".

REST インターフェイスを使用してデータを書き込むWriting data by using the REST interface

適切なエンドポイントに RESTful HTTP 要求を作成すると、データを読み取るときと同じように SharePoint エンティティの作成および更新を実行できます。1 つの大きな違いは、 POST 要求を使用する点です。また、エンティティを更新するときは、 PUT または MERGE の HTTP 要求メソッドも渡します。これを実行するには、これらのいずれかの語を X-HTTP-Method キーの値として要求のヘッダーに追加します。 MERGE メソッドでは指定したエンティティのプロパティのみが更新されるのに対し、 PUT メソッドでは POST の本文に指定した新しいエンティティで既存のエンティティが置き換えられます。エンティティの削除には DELETE メソッドを使用します。エンティティを作成したり更新したりするときは、作成または変更するエンティティの OData 表現を HTTP 要求の本文で指定する必要があります。You can create and update SharePoint entities by constructing RESTful HTTP requests to the appropriate endpoints, just as you do when you're reading data. One key difference, however, is that you use a POST request. When you're updating entities, you also pass a PUT or MERGE HTTP request method by adding one of those terms to the headers of your request as the value of the X-HTTP-Method key. The MERGE method updates only the properties of the entity that you specify, while the PUT method replaces the existing entity with a new one that you supply in the body of the POST. Use the DELETE method to delete the entity. When you create or update an entity, you must provide an OData representation of the entity that you want to create or change in the body of your HTTP request.

SharePoint エンティティを作成、更新、削除するときのもう 1 つの重要な考慮事項は、これらの要求の認証に OAuth を使用していない場合、これらの処理にサーバーの要求フォーム ダイジェスト値が X-RequestDigest ヘッダーの値として必要であることです。この値を取得するには、 http://<site url>/_api/contextinfo に対して本文が空の POST 要求を実行し、 contextinfo エンドポイントが返す XML の d:FormDigestValue ノードの値を抽出します。次の例は、 contextinfo エンドポイントに対する HTTP 要求を C# で示しています。Another important consideration when creating, updating, and deleting SharePoint entities is that if you aren't using OAuth to authorize your requests, these operations require the server's request form digest value as the value of the X-RequestDigest header. You can retrieve this value by making a POST request with an empty body to http://<site url>/_api/contextinfo and extracting the value of the d:FormDigestValue node in the XML that the contextinfo endpoint returns. The following example shows an HTTP request to the contextinfo endpoint in 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 アドインの承認と認証」で説明している認証と承認のフローを使用している場合は、要求に要求のダイジェストを含める必要はありません。If you're using the authentication and authorization flow described in Authorization and authentication of SharePoint Add-ins, you don't need to include the request digest in your requests.

JavaScript クロスドメイン ライブラリを使用している場合は、SP.RequestExecutor がフォーム ダイジェスト値の取得と送信を処理します。If you're using the JavaScript cross-domain library, SP.RequestExecutor handles getting and sending the form digest value for you.

SharePoint ホスト型 SharePoint アドインを作成する場合、別途 HTTP 要求を実行してフォーム ダイジェストの値を取得する必要はありません。If you're creating a SharePoint-hosted SharePoint Add-in, you don't have to make a separate HTTP request to retrieve the form digest value. 代わりに、JavaScript コードで SharePoint ページから値を取得できます (ページが既定のマスター ページを使用している場合)。次の例でこれを示します。ここでは、JQuery を使用し、リストを作成します。Instead, you can retrieve the value in JavaScript code from the SharePoint page (if the page uses the default master page), as shown in the following example, which uses JQuery and creates a list.

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 ホスト型アドインでこの操作を実行することを前提としています。The following example shows how to update the list that is created in the previous example. The example changes the title of the list, uses JQuery, and assumes that you are doing this operation in a SharePoint-hosted add-in.

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 値を指定します。The value of the IF-MATCH key in the request headers is where you specify the etag value of a list or list item. この特定の値はリストおよびリスト アイテムのみに適用され、それらのエンティティを更新するときに同時実行の問題を回避することが目的です。This particular value applies only to lists and list items, and is intended to help you avoid concurrency problems when you update those entities. 前の例ではこの値にアスタリスク (*) を使用しています。この値は同時実行の問題を心配する理由がない場合に使用できます。The previous example uses an asterisk (*) for this value, and you can use that value whenever you don't have any reason to worry about concurrency issues. それ以外の場合は、エンティティを取得する GET 要求を実行してリストまたはリスト アイテムの etag 値を取得する必要があります。Otherwise, you should obtain the etag value or a list or list item by performing a GET request that retrieves the entity. 結果の HTTP 応答の応答ヘッダーは、この etag を ETag キーの値として渡します。The response headers of the resulting HTTP response pass the etag as the value of the ETag key. この値はまた、エンティティ メタデータにも含まれます。This value is also included in the entity metadata.

次の例は、リスト情報を含む XML ノードの開始の <entry> タグを示しています。The following example shows the opening <entry> tag for the XML node that contains the list information. m:etag プロパティに etag 値が含まれます。The m:etag property contains the etag value.

<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 によるサイトの作成Creating a site with REST

次の例は、JavaScript でサイトを作成する方法を示しています。The following example shows how to create a site in 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' に設定すると、最新のホーム ページが作成されます。Setting WebTemplate to 'sts' will create a modern homepage. 従来のホーム ページを作成するには、WebTemplate を 'sts #0' に設定します。To create a classic homepage, set WebTemplate to 'sts#0'.

環境によって異なる REST 要求の方法How REST requests differ by environment

HTTP 要求の構築と送信は、言語、ライブラリ、アドイン タイプなどによって異なります。このため、1 つの環境から別の環境に要求を変換する場合に 1 つ以上の要求コンポーネントを変更する必要が生じることがよくあります。例えば、jQuery AJAX 要求は data パラメーターと type パラメーターを使って要求の本文と種類を指定しますが、クロスドメイン ライブラリ要求は body パラメーターと method パラメーターを使ってこれらの値を指定します。Building and sending an HTTP request may vary according to language, library, and add-in type, so you often need to change one or more request components when you're translating a request from one environment to another. For example, jQuery AJAX requests use data and type parameters to specify the request body and type, but cross-domain library requests use body and method parameters to specify those values.

以下のセクションでは、環境による他の一般的な相違について説明します。The following sections describe other common differences across environments.

フォーム ダイジェスト値を取得および送信する方法はアドインに依存するThe way you get and send the form digest value depends on the add-in

POST 要求を送信するときは、 X-RequestDigest ヘッダーにフォーム ダイジェスト値が含まれている必要があります。ただし、その値を取得して送信する方法はアドインごとに異なります。When you send a POST request, the request must include the form digest value in the X-RequestDigest header. However, the way you get and send the value differs by add-in:

  • SharePoint ホスト型アドインの場合は、次のヘッダーを渡すだけです。In SharePoint-hosted add-ins, you can just pass the following header:

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

  • OAuth を使用するクラウドでホストされるアドインの場合は、まず要求を contextinfo エンドポイントに送信してフォーム ダイジェスト値を取得し、次いで「 REST インターフェイスを使用してデータを書き込む」に示されているように、その値を要求に追加します。In cloud-hosted add-ins that use OAuth, first retrieve the form digest value by sending a request to the contextinfo endpoint, and then add it to requests, as shown in Writing data by using the REST interface.

  • JavaScript クロスドメイン ライブラリを使用するクラウドでホストされるアドインでは、フォーム ダイジェスト値を指定する必要はありません。既定で、SP.RequestExecutor が自動でその処理を行います。(content-length 値も処理します。)In cloud-hosted add-ins that use the JavaScript cross-domain library, you don't need to specify the form digest value. By default, SP.RequestExecutor automatically handles this for you. (It also handles the content-length value.)

OAuth を使うアドインは、要求でアクセス トークンを渡す必要があるAdd-ins that use OAuth must pass access tokens in requests

クラウドでホストされるアドインは、OAuth またはクロスドメイン ライブラリを使って SharePoint データへのアクセスを承認します。Cloud-hosted add-ins use either OAuth or the cross-domain library to authorize access to SharePoint data. リモート Web サーバー上で実行されるコードを持つアドイン コンポーネントは、OAuth を使って SharePoint データへのアクセスを承認する必要があります。Add-in components with code that runs on a remote web server must use OAuth to authorize access to SharePoint data. この場合、アクセス トークンを送信するために Authorization ヘッダーを含める必要があります。In this case, you need to include an Authorization header to send the access token. HTTPWebRequest オブジェクトに承認ヘッダーを追加する例については、「SharePoint REST インターフェイスを使用してデータを読み取る」を参照してください。For an example that adds an authorization header to an HTTPWebRequest object, see Reading data with the SharePoint REST interface.

注意

JavaScript で記述され、クラウドでホストされるアドイン コンポーネントは、クロスドメイン ライブラリ内の SP.RequestExecutor オブジェクトを使って SharePoint データにアクセスする必要があります。Cloud-hosted add-in components that are written in JavaScript must use the SP.RequestExecutor object in the cross-domain library to access to SharePoint data. クロスドメイン ライブラリ要求はアクセス トークンを含める必要はありません。Cross-domain library requests don't need to include an access token.

OAuth アクセス トークンとそれらを取得する方法の詳細は、「SharePoint のアドインのコンテキスト トークン OAuth フロー」および「SharePoint アドインの認証コード OAuth フロー」を参照してください。To learn more about OAuth access tokens and how to get them, see Context Token OAuth flow for SharePoint Add-ins and Authorization Code OAuth flow for SharePoint Add-ins.

SP.AppContextSite を使ってコンテキストを変更するには、クロスドメイン要求のエンドポイントの URI を使用するEndpoint URIs in cross-domain requests use SP.AppContextSite to change the context

要求は、要求の url プロパティで指定されているリソース エンドポイントに送信されます。エンドポイント URI は次の形式で指定します。Requests are sent to the resource endpoint that's specified in the url property of the request. Endpoint URIs use the following format:

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

クロスドメイン ライブラリ要求は、アドイン Web 上のデータにアクセスするときにはこの形式を使います。これは、クロスドメイン ライブラリ要求のデフォルトのコンテキストです。しかし、ホスト Web または他のサイト コレクション上のデータにアクセスするときには、ホスト Web または他のサイト コレクションをコンテキストとして初期化する必要があります。この処理のため、クロスドメイン ライブラリ要求は表 1 に示すように URI 内の SP.AppContextSite エンドポイントを使います。表 1 に示されているサンプル URI は、 **@target** エイリアスを使ってクエリ文字列内のターゲット URL を送信します。これは、URL に特殊文字 (':') が含まれているためです。Cross-domain library requests use this format when they access data on the add-in web, which is the default context for cross-domain library requests. But to access data on the host web or on another site collection, the requests need to initialize the host web or other site collection as the context. To do this, they use the SP.AppContextSite endpoint in the URI, as shown in Table 1. The example URIs in Table 1 use the **@target** alias to send the target URL in the query string because the URL contains a special character (':').

注意

クロスドメイン ライブラリを使うときには、クラウドでホストされるアドインが SharePoint データにアクセスできるようにするためにアドイン Web インスタンスが必要となります。An add-in web instance is required for a cloud-hosted add-in to access SharePoint data when using the cross-domain library.

表 1. SP.AppContextSite エンドポイントを使って要求のコンテキストを変更するTable 1. Using the SP.AppContextSite endpoint to change the context of the request

アドインの種類Add-in type クロスドメインでのデータ アクセスのシナリオCross-domain data access scenario エンドポイント URI の例Example endpoint URI
クラウド ホスト型Cloud-hosted クロスドメイン ライブラリを使ってホスト Web データにアクセスする JavaScript アドイン コンポーネントJavaScript add-in component accessing host web data by using the cross-domain library <app web url>/_api/SP.AppContextSite(@target)/web/lists?@target='<host web url>'
クラウド ホスト型Cloud-hosted クロスドメイン ライブラリを使ってホスト Web 以外のサイト コレクション内のデータにアクセスする JavaScript アドイン コンポーネント (テナント スコープ アドインのみ)JavaScript add-in component accessing data in a site collection other than the host web by using the cross-domain library (tenant-scoped add-ins only) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'
SharePoint ホスト型SharePoint-hosted 別のサイト コレクション内のデータにアクセスするアドイン Web コンポーネント (テナント スコープ アドインのみ)Add-in web component accessing data in another site collection (tenant-scoped add-ins only) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'

注意

クロスドメイン データ アクセスでは、適切なアドインのアクセス許可も必要です。詳しくは、「ホスト Web からのデータ アクセス」と「サイト コレクション間でのデータ アクセス」をご覧ください。Cross-domain data access scenarios also require appropriate add-in permissions. For more information, see Access data from the host web and Access data across site collections.

次のコード例に示すように、SharePoint アドインはアドイン ページのクエリ文字列からアドイン Web URL とホスト Web URL を取得できます。SharePoint Add-ins can get the add-in web URL and host web URL from the query string of the add-in page, as shown in the following code example. この例には、クロスドメイン ライブラリ (ホスト Web 上の SP.RequestExecutor.js ファイルで定義される) を参照する方法も示されています。The example also shows how to reference the cross-domain library, which is defined in the SP.RequestExecutor.js file on the host web. この例は、アドインが SharePoint から起動することを想定しています。The example assumes that your add-in launches from SharePoint. アドインが SharePoint から起動しない場合に SharePoint コンテキストを正しく設定するためのガイダンスは、「SharePoint アドインの認証コード OAuth フロー」をご覧ください。For guidance about setting your SharePoint context correctly when your add-in does not launch from SharePoint, see Authorization Code OAuth flow for SharePoint Add-ins.

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 要求で使うプロパティProperties used in REST requests

表 2 に、SharePoint REST サービスの HTTP 要求で一般に使われるプロパティを示します。Table 2 shows properties that are commonly used in HTTP requests for the SharePoint REST service.

表 2. HTTP 要求で REST 要求プロパティを使う場合Table 2. When to use REST request properties in HTTP requests

プロパティProperties 必要な場合When required 説明Description
urlurl すべての要求All requests REST リソース エンドポイントの URL。例: http://<site url>/_api/web/listsThe URL of the REST resource endpoint. Example: http://<site url>/_api/web/lists
method (または type)method (or type) すべての要求All requests HTTP 要求メソッド: 読み取り操作用の GET および書き込み操作用の POSTPOST 要求では、 DELETE ヘッダーで MERGEPUT、または X-HTTP-Method 動詞を指定して、更新または削除操作を行うことができます。The HTTP request method: GET for read operations and POST for write operations. POST requests can perform update or delete operations by specifying a DELETE, MERGE, or PUT verb in the X-HTTP-Method header.
body (または data)body (or data) 要求本文でデータを送信する POST 要求POST requests that send data in the request body POST 要求の本文。エンドポイント URI で送信できないデータ (複合型など) を送信します。 content-length ヘッダーで使用します。The body of the POST request. Sends data (such as complex types) that can't be sent in the endpoint URI. Used with the content-length header.
Authentication ヘッダーAuthentication header OAuth を使用してユーザーを認証するリモート アドイン。JavaScript またはクロスドメイン ライブラリを使用する場合は適用されません。Remote add-ins that are using OAuth to authenticate users; does not apply when using JavaScript or the cross domain library (Microsoft Access Control Service (ACS) セキュア トークン サーバーから取得した) OAuth アクセス トークンを送信します。このアクセス トークンは、要求に対してユーザーを認証するのに使用します。例: "Authorization": "Bearer " + accessToken。ここで、 accessToken はトークンを格納する変数を表します。トークンはサーバー側のコードを使用して取得する必要があります。Sends the OAuth access token (obtained from a Microsoft Access Control Service (ACS) secure token server) that's used to authenticate the user for the request. Example: "Authorization": "Bearer " + accessToken, where accessToken represents the variable that stores the token. Tokens must be retrieved by using server-side code.
X-RequestDigest ヘッダーX-RequestDigest header POST 要求 (SP.RequestExecutor 要求を除く)POST requests (except SP.RequestExecutor requests) OAuth を使用するリモート アドインは、 http://<site url>/_api/contextinfo エンドポイントからフォーム ダイジェスト値を取得できます。SharePoint ホスト型アドインは、 #__REQUESTDIGEST ページ コントロールから値を取得できます (SharePoint ページで使用できる場合)。「 REST インターフェイスを使用してデータを書き込む」を参照してください。Remote add-ins that use OAuth can get the form digest value from the http://<site url>/_api/contextinfo endpoint. SharePoint-hosted add-ins can get the value from the #__REQUESTDIGEST page control if it's available on the SharePoint page. See Writing data by using the REST interface.
accept ヘッダーaccept header SharePoint メタデータを返す要求Requests that return SharePoint metadata サーバーからの応答データの形式を指定します。既定の形式は application/atom+xml です。例: "accept":"application/json;odata=verbose"Specifies the format for response data from the server. The default format is application/atom+xml. Example: "accept":"application/json;odata=verbose"
content-type ヘッダーcontent-type header 要求本文でデータを送信する POST 要求POST requests that send data in the request body クライアントがサーバーに送信するデータの形式を指定します。既定の形式は application/atom+xml です。例: "content-type":"application/json;odata=verbose"Specifies the format of the data that the client is sending to the server. The default format is application/atom+xml. Example: "content-type":"application/json;odata=verbose"
content-length ヘッダーcontent-length header 要求本文でデータを送信する POST 要求 (SP.RequestExecutor 要求を除く)POST requests that send data in the request body (except SP.RequestExecutor requests) コンテンツの長さを指定します。例: "content-length":requestBody.lengthSpecifies the length of the content. Example: "content-length":requestBody.length
IF-MATCH ヘッダーIF-MATCH header DELETE 操作、MERGE 操作、または PUT 操作に対する POST 要求。主にリストとライブラリの変更に使用します。POST requests for DELETE, MERGE, or PUT operations, primarily for changing lists and libraries 変更対象のオブジェクトが最後に取得されてから変更されていないことを確認する方法を提供します。または、すべての変更を上書きするように指定することもできます。例: "IF-MATCH":"*"Provides a way to verify that the object being changed has not been changed since it was last retrieved. Or, lets you specify to overwrite any changes, as shown in the following example: "IF-MATCH":"*"
X-HTTP-Method ヘッダーX-HTTP-Method header POSTDELETE、または MERGE 操作に対する PUT 要求POST requests for DELETE, MERGE, or PUT operations 要求で更新または削除操作を実行するように指定する場合に使用します。例: "X-HTTP-Method":"PUT"Used to specify that the request performs an update or delete operation. Example: "X-HTTP-Method":"PUT"
binaryStringRequestBodybinaryStringRequestBody 本文でバイナリ データを送信する SP.RequestExecutor POST 要求SP.RequestExecutor POST requests that send binary data in the body 要求本文がバイナリ文字列であるかどうかを指定します。 BooleanSpecifies whether the request body is a binary string. Boolean.
binaryStringResponseBodybinaryStringResponseBody バイナリ データを返す SP.RequestExecutor 要求SP.RequestExecutor requests that return binary data 応答がバイナリ文字列であるかどうかを指定します。BooleanSpecifies whether the response is a binary string. Boolean.

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

SharePoint Online (およびオンプレミス SharePoint 2016 以降) REST サービスでは、OData $batch クエリ オプションを使って、サービスに対する複数の要求を 1 つの呼び出しに統合できます。The SharePoint Online (and on-premises SharePoint 2016 and 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.

関連項目See also