Realizar operações básicas usando os pontos de extremidade REST do SharePointComplete basic operations using SharePoint REST endpoints

Você pode executar operações básicas de criar, ler, atualizar e excluir (CRUD) na interface REST (Transferência de Estado Representacional) fornecida pelo SharePoint.You can perform basic create, read, update, and delete (CRUD) operations by using the Representational State Transfer (REST) interface provided by SharePoint. A interface REST expõe todas as operações e entidades do SharePoint que estão disponíveis nas outras APIs cliente do SharePoint.The REST interface exposes all the SharePoint entities and operations that are available in the other SharePoint client APIs. Uma vantagem de usar REST é que você não precisa adicionar referências às bibliotecas do SharePoint ou assemblies de cliente.One advantage of using REST is that you don't have to add references to any SharePoint libraries or client assemblies. Em vez disso, você faz solicitações HTTP aos pontos de extremidade apropriados para recuperar ou atualizar entidades do SharePoint, como webs, listas e itens de lista.Instead, you make HTTP requests to the appropriate endpoints to retrieve or update SharePoint entities, such as webs, lists, and list items.

Para obter uma introdução à interface do REST do SharePoint e sua arquitetura, confira Conheça o serviço REST do SharePoint.For an introduction to the SharePoint REST interface and its architecture, see Get to know the SharePoint REST service.

Para obter informações sobre como trabalhar com as principais entidades do SharePoint, confira Trabalhar com listas e itens de lista com o REST e Trabalhar com pastas e arquivos com o 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.

Para ver um exemplo que mostra como fazer muitas dessas operações no contexto de um aplicativo Web ASP.NET escrito em C#, confira 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.

Para obter informações sobre os conjuntos de APIs disponíveis para a plataforma do SharePoint, confira Escolher o conjunto de API correto no SharePoint.For information about the sets of APIs available on the SharePoint platform, see Choose the right API set in SharePoint.

Para obter informações sobre como usar APIs de outro cliente, confira:For information about how to use the other client APIs, see:

Operações HTTP nos serviços REST do SharePointHTTP operations in SharePoint REST services

Os pontos de extremidade no serviço REST do SharePoint correspondem aos tipos e membros nos modelos de objeto do cliente do SharePoint.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. Usando solicitações HTTP, você pode usar esses pontos de extremidade REST para executar operações CRUD típicas (Create, Read, Update e Delete) com entidades do SharePoint, como listas e sites.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.

Em geral, os pontos de extremidade que representam operações Read são mapeados para comandos GET HTTP, os pontos de extremidade que representam as operações de criação são mapeados para comandos POST HTTP e os pontos de extremidade que representam operações de atualização ou de inserção são mapeados para os comandos PUT HTTP.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.

No SharePoint, use POST para criar entidades como listas e sites. O serviço REST do SharePoint dá suporte ao envio de comandos POST que incluem definições de objeto para pontos de extremidade que representam coleções. Por exemplo, você poderia enviar um comando POST com uma nova lista de definições de objeto em ATOM para a URL a seguir e criar uma lista do 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

Para operações POST, todas as propriedades que não forem necessárias serão definidas com os valores padrão. Se você tentar definir uma propriedade como somente leitura como parte de uma operação POST, o serviço retornará uma exceção.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.

Use as operações PUT e MERGE para atualizar objetos do SharePoint existentes. Qualquer ponto de extremidade de serviço que represente uma operação set da propriedade do objeto dá suporte a solicitações PUT e a solicitações MERGE. Para as solicitações MERGE, a definição de propriedades é opcional; qualquer propriedade que você não definir explicitamente, conservará a propriedade atual. Para comandos PUT, no entanto, qualquer propriedade que você não definir explicitamente será definida de acordo com as propriedades padrão. Além disso, se você não especificar todas as propriedades exigidas nas atualizações de objetos, ao usar os comandos PUT HTTP, o serviço REST retornará uma exceção.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.

Use o comando DELETE HTTP na URL específica do ponto de extremidade para excluir o objeto do SharePoint representado por esse ponto de extremidade. No caso de objetos recicláveis, como listas, arquivos e listas de itens, isso resultará em uma operação 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.

Ler dados com a interface REST do SharePointReading data with the SharePoint REST interface

Para usar os recursos REST internos ao SharePoint, crie uma solicitação HTTP RESTful, usando o OData padrão, que corresponde à API do modelo de objeto cliente que você deseja usar. Cada entidade do SharePoint é exposta a um ponto de extremidade no site do SharePoint para o qual você está direcionando, e seus metadados são representados no formato XML ou JSON. Você pode fazer as solicitações HTTP em qualquer linguagem, incluindo, sem limitação, JavaScript e 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#.

Para ler as informações de um ponto de extremidade REST, você deve saber tanto a URL do ponto de extremidade e a representação OData da entidade do SharePoint que é exposta naquele ponto de extremidade.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. Por exemplo, para recuperar todas as listas em um site específico do SharePoint, faça uma solicitação GET para 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. Navegue até essa URL no seu navegador e veja o XML que é retornado.You can navigate to this URL in your browser and see the XML that gets returned. Quando faz a solicitação no código, você pode especificar se deseja receber a representação OData das listas em XML ou JSON.When you make the request in code, you can specify whether to receive the OData representation of the lists in XML or JSON.

O código C# a seguir demonstra como fazer essa solicitação GET que retorna uma representação JSON de todas as listas do site usando 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. Também pressupõe que você tenha um token de acesso OAuth válido que está armazenado na variável accessToken.It also assumes that you have a valid OAuth access token that is stored in the accessToken variable. Não é necessário o token de acesso se você fizer essa chamada de dentro de um suplemento Web, como faria em um suplemento hospedado no 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. Observe que você não pode obter um token de acesso de código que está sendo executado em um cliente do navegador.Note that you cannot obtain an access token from code that is running on a browser client. Obtenha o token de acesso do código que está sendo executado em um servidor.You must obtain the access token from code that is running on a server.

Para saber mais sobre como obter um token de acesso, confira Fluxo OAuth de token de contexto para Suplementos do SharePoint e Fluxo OAuth de código de autorização para suplementos do 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();

Essa solicitação terá uma aparência um pouco diferente se você estiver gravando seu suplemento no JavaScript enquanto usa a biblioteca entre domínios do SharePoint.This request would look a little different if you are writing your add-in in JavaScript while using the SharePoint cross-domain library. Nesse caso, você não precisa fornecer um token de acesso.In this case, you don't need to provide an access token.

O código a seguir demonstra qual seria a aparência desse token se você estiver usando a biblioteca entre domínios e deseja receber a representação OData das listas como XML em vez de 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. Como Atom é o formato de resposta padrão, não é necessário incluir um cabeçalho Accept. Para saber mais sobre como usar a biblioteca entre domínios, confira Acessar dados do SharePoint de suplementos usando a biblioteca entre domínios.(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
  }
);

O código no exemplo a seguir mostra como solicitar uma representação JSON de todas as listas em um site usando 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#. Ele pressupõe que você tem um token de acesso OAuth que está armazenando na variável 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();

Obtendo propriedades não retornadas com o recursoGetting properties that aren't returned with the resource

Muitos valores de propriedades são retornados quando você recupera um recurso mas, para algumas propriedades, é preciso enviar uma solicitação GET diretamente ao ponto de extremidade da propriedade. Isso é típico de propriedades que representam entidades do 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.

O exemplo a seguir mostra como obter uma propriedade anexando o nome da propriedade ao ponto de extremidade do recurso. O exemplo obtém o valor da propriedade Author de um recurso 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

Para receber os resultados no formato JSON, inclua um cabeçalho Accept definido como "application/json;odata=verbose".To get the results in JSON format, include an Accept header set to "application/json;odata=verbose".

Escrevendo dados usando a interface RESTWriting data by using the REST interface

Você pode criar e atualizar entidades do SharePoint criando solicitações HTTP RESTful para os pontos de extremidade apropriados, do mesmo modo que faz ao ler dados. Uma importante diferença, entretanto, é que você deve usar uma solicitação POST. Ao atualizar entidades, você também transfere um método de solicitação HTTP PUT ou MERGE adicionando um desses termos ao cabeçalho da sua solicitação, como o valor da chave X-HTTP-Method. O método MERGE atualiza apenas as propriedades da entidade que você especificar, enquanto o método PUT substitui a entidade existente por uma nova, fornecida no corpo de POST. Use o método DELETE para excluir a entidade. Ao criar ou atualizar uma entidade, você deverá fornecer uma representação do OData da entidade que deseja criar ou alterar no corpo da sua solicitação 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.

Outro ponto importante a ser considerado ao criar, atualizar e excluir entidades do SharePoint é que se você não estiver usando o OAuth para autorizar suas solicitações, essas operações exigirão o valor de resumo de formulário de solicitação como o valor do cabeçalho X-RequestDigest. Você pode recuperar esse valor fazendo uma solicitação POST com um corpo vazio para http://<site url>/_api/contextinfo e extraindo o valor do nó d:FormDigestValue no XML retornado pelo ponto de extremidade contextinfo. O exemplo a seguir mostra uma solicitação HTTP para o ponto de extremidade contextinfo no 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();

Se você estiver usando o fluxo de autenticação e autorização descritos em Autorização e autenticação dos suplementos do SharePoint, você não precisará incluir o resumo da solicitação em suas solicitações.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.

Se você estiver usando a biblioteca entre domínios do JavaScript, SP.RequestExecutor gerenciará o recebimento e o envio do valor do resumo do formulário para você.If you're using the JavaScript cross-domain library, SP.RequestExecutor handles getting and sending the form digest value for you.

Se você estiver criando um suplemento do SharePoint hospedado no SharePoint, não será necessário fazer uma solicitação HTTP separada para recuperar o valor de resumo do formulário.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. Em vez disso, você pode recuperar o valor em código JavaScript da página do SharePoint (se a página usa a página mestre padrão), conforme mostrado no seguinte exemplo, que usa JQuery e cria uma lista.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
});

O exemplo a seguir mostra como atualizar a lista criada no exemplo anterior. O exemplo altera o título da lista, usa JQuery e pressupõe que você esteja realizando essa operação em um suplemento hospedado no 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
});

O valor da chave IF-MATCH nos cabeçalhos da solicitação é onde você especifica o valor etag de uma lista ou de um item de lista.The value of the IF-MATCH key in the request headers is where you specify the etag value of a list or list item. Esse valor específico se aplica somente às listas e aos itens de lista e destina-se a ajudá-lo a evitar problemas de simultaneidade quando você atualiza essas entidades.This particular value applies only to lists and list items, and is intended to help you avoid concurrency problems when you update those entities. O exemplo anterior usa um asterisco (*) para esse valor, que você pode usar sempre que não tiver motivos para se preocupar com problemas de simultaneidade.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. Caso contrário, você deve obter o valor etag ou uma lista ou um item de lista executando uma solicitação GET que recupera a entidade.Otherwise, you should obtain the etag value or a list or list item by performing a GET request that retrieves the entity. Os cabeçalhos de resposta HTTP resultante passam o etag como o valor da chave ETag.The response headers of the resulting HTTP response pass the etag as the value of the ETag key. Esse valor também está incluído nos metadados da entidade.This value is also included in the entity metadata.

O exemplo a seguir mostra a tag de abertura <entry> para o nó XML que contém as informações da lista.The following example shows the opening <entry> tag for the XML node that contains the list information. A propriedade m:etag contém o valor 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"">

Criar um site com RESTCreating a site with REST

Os exemplos a seguir mostram como criar um site no 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
});

Observação

Configurar WebTemplate como "sts" criará uma home page moderna.Setting WebTemplate to 'sts' will create a modern homepage. Para criar uma home page clássica, configure WebTemplate como "sts#0".To create a classic homepage, set WebTemplate to 'sts#0'.

Como as solicitações REST diferem por ambienteHow REST requests differ by environment

A criação e o envio de uma solicitação HTTP podem variar de acordo com a linguagem, a biblioteca e o tipo de suplemento e, portanto, você não precisa alterar um ou mais componentes de solicitação ao traduzir uma solicitação de um ambiente para outro. Por exemplo, as solicitações jQuery AJAX usam os parâmetros data e type para especificar o corpo e tipo de solicitação, mas as solicitações de biblioteca entre domínios usam os parâmetros body e method para especificar esses valores.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.

As seções a seguir descrevem outras diferenças comuns entre ambientes.The following sections describe other common differences across environments.

A maneira de receber e enviar o valor do resumo do formulário depende do suplementoThe way you get and send the form digest value depends on the add-in

Quando você envia uma solicitação POST, a solicitação deve incluir o valor do resumo do formulário no cabeçalho do X-RequestDigest. Entretanto, a maneira como você recebe e envia o valor difere de acordo com o suplemento: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:

  • Nos suplementos hospedados no SharePoint, você pode passar apenas o cabeçalho a seguir:In SharePoint-hosted add-ins, you can just pass the following header:

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

  • Em suplementos hospedados na nuvem que usam o OAuth, primeiro recupere o valor do resumo do formulário enviando uma solicitação para o ponto de extremidade contextinfo e depois adicionando-o às solicitações, como mostrado em Escrevendo dados usando a interface 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.

  • Em suplementos hospedados na nuvem que usam a biblioteca entre domínios do JavaScript, não é preciso especificar o valor do resumo do formulário. Por padrão, o SP.RequestExecutor gerenciará isso automaticamente para você (ele também gerenciará o valor de 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.)

Os suplementos que usam o OAuth devem passar os tokens de acesso nas solicitaçõesAdd-ins that use OAuth must pass access tokens in requests

Suplementos hospedados na nuvem usam o OAuth ou a biblioteca entre domínios para autorizar o acesso aos dados do SharePoint.Cloud-hosted add-ins use either OAuth or the cross-domain library to authorize access to SharePoint data. Os componentes de suplemento com código executados em um servidor Web remoto deve usar o OAuth para autorizar o acesso aos dados do SharePoint.Add-in components with code that runs on a remote web server must use OAuth to authorize access to SharePoint data. Nesse caso, você precisa incluir um cabeçalho Authorization para enviar o token de acesso.In this case, you need to include an Authorization header to send the access token. Para obter um exemplo que adiciona o cabeçalho de autorização a um objeto HTTPWebRequest, confira Ler dados com a interface REST do SharePoint.For an example that adds an authorization header to an HTTPWebRequest object, see Reading data with the SharePoint REST interface.

Observação

Componentes de suplementos hospedados em nuvem que são gravados em JavaScript devem usar o objeto SP.RequestExecutor na biblioteca entre domínios para acessar os dados do 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. Solicitações de biblioteca entre domínios não precisam incluir um token de acesso.Cross-domain library requests don't need to include an access token.

Para saber mais sobre os tokens de acesso OAuth e como obtê-los, confira Fluxo OAuth de token de contexto para suplementos do SharePoint e Fluxo OAuth de código de autorização de suplementos do 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.

Os URIs de pontos de extremidade em solicitações entre domínios usam o SP.AppContextSite para alterar o contextoEndpoint URIs in cross-domain requests use SP.AppContextSite to change the context

As solicitações são enviadas para o ponto de extremidade do recurso que é especificado na propriedade url da solicitação. As URIs do ponto de extremidade usam o seguinte formato: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> (exemplo, https://contoso.com/_api/web/lists)<site url>/_api/<context>/<resource> (example, https://contoso.com/_api/web/lists)

As solicitações de bibliotecas entre domínios usam esse formato ao acessar dados na Web de suplementos, que é o contexto padrão para solicitações de bibliotecas entre domínios. Mas para acessar os dados na Web do host ou em outro conjunto de sites, as solicitações precisam inicializar a Web do host ou outro conjunto de sites como o contexto. Para isso, elas usam o ponto de extremidade do SP.AppContextSite na URI, conforme mostrado na Tabela 1. As URIs de exemplo na Tabela 1 usam o alias @target para enviar a URL de destino na cadeia de caracteres de consulta porque a URL contém um caractere especial (':').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 (':').

Observação

Uma instância da Web do suplemento é necessária para que um suplemento hospedado na nuvem possa acessar dados do SharePoint usando a biblioteca de domínio cruzado.An add-in web instance is required for a cloud-hosted add-in to access SharePoint data when using the cross-domain library.

Tabela 1. Usar o ponto de extremidade SP.AppContextSite para alterar o contexto da solicitaçãoTable 1. Using the SP.AppContextSite endpoint to change the context of the request

Tipo de suplementoAdd-in type Cenário de acesso de dados entre domíniosCross-domain data access scenario Exemplo de URI de ponto de extremidadeExample endpoint URI
Hospedado na nuvemCloud-hosted Componente do suplemento JavaScript acessando os dados do host da Web usando a biblioteca entre domíniosJavaScript 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>'
Hospedado na nuvemCloud-hosted Componente de suplemento do JavaScript acessando os dados em um conjunto de sites diferente do host da Web usando a biblioteca entre domínios (somente suplementos no escopo do locatário)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>'
Hospedado pelo SharePointSharePoint-hosted Componente de site do suplemento acessando os dados em outros conjuntos de sites (somente suplementos no escopo do locatário)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>'

Observação

Os cenários de acesso de dados entre domínios também exigem permissões de suplemento apropriadas. Para saber mais, confira Acessar dados da Web do host e Acessar dados entre conjuntos de sites.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.

Suplementos do SharePoint podem obter a URL da Web do suplemento e o host da Web da cadeia de caracteres de consulta, como mostrado no seguinte exemplo de código.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. O exemplo também mostra como fazer referência à biblioteca entre domínios, que é definida no arquivo SP.RequestExecutor.js no host da Web.The example also shows how to reference the cross-domain library, which is defined in the SP.RequestExecutor.js file on the host web. O exemplo presume que o suplemento inicia pelo SharePoint.The example assumes that your add-in launches from SharePoint. Para obter orientação sobre como configurar seu contexto do SharePoint corretamente quando seu suplemento não é iniciado pelo SharePoint, confira Fluxo OAuth de código de autorização para os suplementos do 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

Propriedades usadas em solicitações RESTProperties used in REST requests

A Tabela 2 mostra as propriedades que são comumente usadas em solicitações HTTP para o serviço REST do SharePoint.Table 2 shows properties that are commonly used in HTTP requests for the SharePoint REST service.

Tabela 2. Quando usar as propriedades de solicitação REST em solicitações HTTPTable 2. When to use REST request properties in HTTP requests

PropriedadesProperties Quando é necessárioWhen required DescriçãoDescription
urlurl Todas as solicitaçõesAll requests A URL do ponto de extremidade de recursos REST. Exemplo: http://<site url>/_api/web/listsThe URL of the REST resource endpoint. Example: http://<site url>/_api/web/lists
method (ou type)method (or type) Todas as solicitaçõesAll requests O método de solicitação HTTP: GET para operações de leitura e POST para operações de escrita. As solicitações POST podem realizar operações de atualização ou exclusão especificando um verbo DELETE, MERGE ou PUT no cabeçalho do 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 (ou data)body (or data) As solicitações POST que enviam dados no corpo da solicitaçãoPOST requests that send data in the request body O corpo da solicitação POST. Envia dados (como tipos complexos) que podem ser enviados na URI do ponto de extremidade. Usado com o cabeçalho 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.
Cabeçalho AuthenticationAuthentication header Os suplementos remotos que estão usando o OAuth para autenticar usuários; não se aplica ao uso do JavaScript ou da biblioteca entre domíniosRemote add-ins that are using OAuth to authenticate users; does not apply when using JavaScript or the cross domain library Envia o token de acesso do OAuth (obtido a partir de um servidor de token seguro do Serviço de Controle de Acesso (ACS) da Microsoft) usado para autenticar o usuário para a solicitação. Exemplo: "Authorization": "Bearer " + accessToken, em que accessToken representa a variável que armazena o token. Os tokens devem ser recuperados usando o código do lado do servidor. 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.
Cabeçalho X-RequestDigestX-RequestDigest header Solicitações POST (exceto solicitações SP.RequestExecutor)POST requests (except SP.RequestExecutor requests) Os suplementos remotos que usam o OAuth podem obter um valor do resumo do formulário a partir do ponto de extremidade http://<site url>/_api/contextinfo. Os suplementos hospedados no SharePoint podem obter o valor a partir do controle da página #__REQUESTDIGEST se ele estiver disponível na página do SharePoint. Confira Escrevendo dados usando a interface 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.
Cabeçalho acceptaccept header Solicitações que retornam metadados do SharePointRequests that return SharePoint metadata Especifica o formato para dados de resposta do servidor. O formato padrão é application/atom+xml. Exemplo: "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"
Cabeçalho content-typecontent-type header As solicitações POST que enviam dados no corpo da solicitaçãoPOST requests that send data in the request body Especifica o formato dos dados que o cliente está enviando para o servidor. O formato padrão é application/atom+xml. Exemplo: "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"
cabeçalho content-lengthcontent-length header As solicitações POST que enviam dados no corpo da solicitação (exceto solicitações SP.RequestExecutor)POST requests that send data in the request body (except SP.RequestExecutor requests) Especifica o comprimento do conteúdo. Exemplo: "content-length":requestBody.lengthSpecifies the length of the content. Example: "content-length":requestBody.length
Cabeçalho IF-MATCHIF-MATCH header Solicitações POST para operações DELETE, MERGE ou PUT, primariamente para alterar listas e bibliotecasPOST requests for DELETE, MERGE, or PUT operations, primarily for changing lists and libraries Oferece uma maneira para verificar se o objeto que está sendo alterado não foi alterado desde a última recuperação. Ou permite especificar para substituir qualquer alteração, como mostrado no exemplo a seguir: "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":"*"
Cabeçalho X-HTTP-MethodX-HTTP-Method header Solicitações POST para operações DELETE, MERGE ou PUTPOST requests for DELETE, MERGE, or PUT operations Usadas para especificar que a solicitação realizará uma operação de atualização ou exclusão. Exemplo: "X-HTTP-Method":"PUT"Used to specify that the request performs an update or delete operation. Example: "X-HTTP-Method":"PUT"
binaryStringRequestBodybinaryStringRequestBody As solicitações POST do SP.RequestExecutor que enviam dados binários no corpoSP.RequestExecutor POST requests that send binary data in the body Especifica se o corpo é uma cadeia de caracteres binária. Boolean.Specifies whether the request body is a binary string. Boolean.
binaryStringResponseBodybinaryStringResponseBody As solicitações SP.RequestExecutor que retornam dados bináriosSP.RequestExecutor requests that return binary data Especifica se a resposta é uma cadeia de caracteres binária. Boolean.Specifies whether the response is a binary string. Boolean.

Suporte ao trabalho em lotesBatch job support

O serviço REST do SharePoint Online (e o SharePoint 2016 e posterior no local) dá suporte à combinação de várias solicitações em uma única chamada para o serviço usando a opção de consulta $batch do OData.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. Para obter detalhes e links de amostras de código, confira Fazer solicitações em lote com APIs REST.For details and links to code samples, see Make batch requests with the REST APIs.

Confira tambémSee also