Выполнение базовых операций с использованием конечных точек REST SharePointComplete basic operations using SharePoint REST endpoints

Вы можете выполнять базовые операции CRUD (создание, чтение, обновление, удаление) с помощью интерфейса REST, предоставляемого средой SharePoint.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 состоит в том, что вам не требуется добавлять ссылки на библиотеки и клиентские сборки SharePoint.One advantage of using REST is that you don't have to add references to any SharePoint libraries or client assemblies. Вместо этого соответствующим конечным точкам отправляются HTTP-запросы на получение или обновление сущностей 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 и его архитектуре см. в статье Знакомство со службой REST в SharePoint.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.

В примере SharePoint-Add-in-REST-OData-BasicDataOperations показано, как выполнять многие из этих операций в контексте веб-приложения ASP.NET, написанного на языке C#.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.

Дополнительные сведения о наборах API, доступных на платформе SharePoint, см. в статье Выбор правильного набора API в SharePoint.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:

Операции HTTP в службах REST SharePointHTTP operations in SharePoint REST services

Конечные точки в службе REST SharePoint соответствуют типам и элементам клиентских объектных моделей SharePoint.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. С помощью HTTP-запросов вы можете использовать эти конечные точки REST для выполнения типичных операций CRUD (Create, Read, Update и Delete) с сущностями SharePoint, такими как списки и сайты.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. Служба REST SharePoint поддерживает отправку команд POST, включающих описания объектов для конечных точек, представляющих коллекции. Например, можно отправить команду POST, включающую новое описание объекта списка в ATOM, на следующий 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.

Используйте HTTP-команду DELETE для определенного URL-адреса конечной точки, чтобы удалить объект 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.

Считывание данных с помощью интерфейса REST SharePointReading data with the SharePoint REST interface

Для использования возможностей REST, которые встроены в SharePoint, вы создаете HTTP-запрос с поддержкой REST, используя стандарт OData, что соответствует клиентской объектной модели API, которую вы хотите использовать. Каждый объект 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-адрес конечной точки и представление OData соответствующей сущности SharePoint.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, необходимо отправить запрос GET по адресу http://<site url>/_api/web/lists.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# показано, как совершить запрос GET, который возвращает представление всех списков на сайте в формате JSON с помощью JQuery.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. Кроме того, предполагается, что у вас есть допустимый маркер доступа OAuth, хранящийся в переменной accessToken.It also assumes that you have a valid OAuth access token that is stored in the accessToken variable. Этот маркер доступа не требуется, если вы совершаете вызов с сайта надстройки, как в надстройках с размещением в 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.

Дополнительные сведения о том, как получить маркер доступа, см. в статьях Поток маркеров контекста OAuth для надстроек SharePoint и Поток кода авторизации OAuth для надстроек SharePoint.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();

Если вы создаете надстройку на JavaScript, но используете междоменную библиотеку SharePoint, этот запрос будет выглядеть немного по-другому.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 списков в формате XML, а не JSON.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
  }
);

В приведенном ниже примере кода показано, как запросить представление в формате JSON для всех списков на сайте с помощью C#.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#. Предполагается, что у вас есть маркер доступа OAuth, хранящийся в переменной accessToken.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

Многие значения свойств возвращаются, когда вы получаете ресурс, но для некоторых свойств необходимо отправить запрос GET непосредственно в конечную точку свойства. Это типично для свойств, представляющих объекты SharePoint.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, включите набор заголовков Accept в "application/json;odata=verbose".To get the results in JSON format, include an Accept header set to "application/json;odata=verbose".

Запись данных с помощью интерфейса RESTWriting data by using the REST interface

Вы можете создавать и обновлять объекты SharePoint, создавая HTTP-запросы с поддержкой REST для соответствующих конечных точек, так же, как это происходит при чтении данных. Одно из ключевых отличий заключается в том, что вы используете запрос POST. При обновлении объектов вы также передаете HTTP-запрос PUT или MERGE, добавляя один из этих операторов в заголовки запроса в качестве значения ключа 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 является то, что если вы не используете OAuth для авторизации своих запросов, для выполнения этих операций потребуется передавать значение дайджеста формы запроса сервера в качестве значения заголовка X-RequestDigest. Чтобы получить это значение, выполните запрос POST с пустым телом для http://<site url>/_api/contextinfo и извлеките значение сайта d:FormDigestValue в XML-коде, возвращаемом конечной точкой contextinfo. В следующем примере показан HTTP-запрос к конечной точке contextinfo, написанный на 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, вам не понадобится отправлять отдельный 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. В противном случае необходимо получить значение etag списка или его элемента, выполнив запрос GET на получение сущности.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.

В приведенном ниже примере показан открывающий тег <entry> узла XML, содержащий данные списка.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"">

Создание сайта с помощью RESTCreating 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-запросов могут различаться в зависимости от языка, библиотеки и типа надстройки, поэтому при переводе запроса из одной среды в другую часто требуется изменять один или несколько компонентов запросов. Например, запросы 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. Компоненты надстроек с кодом, выполняющимся на удаленном веб-сервере, должны использовать 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 см. в разделе Считывание данных с помощью интерфейса REST SharePoint.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 и их получении см. в статьях Поток маркеров контекста OAuth для надстроек в SharePoint и Поток кода авторизации OAuth для надстроек в SharePoint.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.

URI конечных точек в междоменных запросах используют объект SP.AppContextSite для изменения контекста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)

Запросы к междоменным библиотекам имеют такой формат при доступе к данным на сайте надстройки, стандартном контексте запросов к междоменным библиотекам. Тем не менее, для доступа к данным на сайте надстройки или в другом семействе веб-сайтов запросам необходимо инициализировать хост-сайт или другое семейство веб-сайтов в качестве контекста. Для этого они используют конечную точку SP.AppContextSite из URI, как показано в таблице 1. В примерах URI из таблицы 1 используется псевдоним @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 при использовании междоменной библиотеки надстройке с размещением в облаке необходим экземпляр сайта надстройки.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.AppContextSiteTable 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 Компонент надстройки 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 Компонент надстройки 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>'
Размещение в SharePointSharePoint-hosted Компонент сайта надстройки получает доступ к данным в другом семействе веб-сайтов (только для надстроек с разрешениями на уровне клиента)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>'

Примечание

Сценарии междоменного доступа к данным также требуют соответствующих разрешений для надстроек. Подробнее см. в разделах Доступ к данным на хост-сайте и Доступ к данным на нескольких семействах веб-сайтов.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 могут получать 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. В этом примере также показано, как ссылаться на междоменную библиотеку, определенную в файле 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, см. в статье Поток кода авторизации OAuth для надстроек SharePoint.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

Свойства, используемые в запросах RESTProperties used in REST requests

В таблице 2 показаны свойства, которые часто используются в HTTP-запросах для службы REST SharePoint.Table 2 shows properties that are commonly used in HTTP requests for the SharePoint REST service.

Таблица 2. Использование свойств запроса REST в HTTP-запросахTable 2. When to use REST request properties in HTTP requests

СвойстваProperties Когда требуетсяWhen required ОписаниеDescription
urlurl Все запросыAll requests URL-адрес конечной точки ресурса REST. Например: 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 для операций чтения и POST для операций записи. Запросы POST могут выполнять операции обновления или удаления, используя команду DELETE, MERGE или PUT в заголовке 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.
Заголовок AuthenticationAuthentication 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 Azure), который используется для проверки подлинности пользователя для запроса. Например: "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-RequestDigestX-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.
Заголовок acceptaccept header Запросы, которые возвращают метаданные SharePointRequests 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-typecontent-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-lengthcontent-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-MATCHIF-MATCH header Запросы POST для операций DELETE, MERGE и PUT (в первую очередь для изменения списков и библиотек).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-MethodX-HTTP-Method header POST запрашивает операции DELETE, MERGE или PUTPOST 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 Запросы POST, которые отправляют двоичные данные в теле запросаSP.RequestExecutor POST requests that send binary data in the body Указывает, является ли текст запроса двоичной строкой. Boolean.Specifies whether the request body is a binary string. Boolean.
binaryStringResponseBodybinaryStringResponseBody Запросы SP.RequestExecutor, возвращающие двоичные данныеSP.RequestExecutor requests that return binary data Указывает, является ли ответ двоичной строкой. Boolean.Specifies whether the response is a binary string. Boolean.

Поддержка пакетных заданийBatch job support

Служба REST в SharePoint Online (а также локальной среде SharePoint 2016 или более поздней версии) поддерживает объединение нескольких запросов в один вызов службы с помощью параметра запроса OData $batch.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