Conheça o serviço REST do SharePointGet to know the SharePoint REST service

O SharePoint introduz um serviço REST (Representational State Transfer) comparável aos modelos de objeto de clientedo SharePoint existentes.SharePoint introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. Agora, os desenvolvedores podem interagir remotamente com dados do SharePoint usando qualquer tecnologia que ofereça suporte a solicitações Web do REST.Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. Isso significa que os desenvolvedores podem executar operações CRUD ( criar, ler, Atualizare excluir ) de seus suplementos, soluções e aplicativos cliente do SharePoint, usando tecnologias da Web REST e protocolo de dados abertos padrão ( Sintaxe OData). This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.\

Pré-requisitosPrerequisites

Este tópico pressupõe que você tenha familiaridade básica com o REST e como construir solicitações REST.This topic assumes you have a basic familiarity with REST and how to construct REST requests.

Como funciona o serviço REST do SharePointHow the SharePoint REST service works

O SharePoint adiciona a capacidade de interagir remotamente com sites do SharePoint usando o REST.SharePoint adds the ability for you to remotely interact with SharePoint sites by using REST. Agora você pode interagir diretamente com objetos do SharePoint usando qualquer tecnologia que ofereça suporte a recursos REST padrão.Now you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.

Para acessar os recursos do SharePoint usando o REST, crie uma solicitação HTTP RESTful usando o padrão OData, que corresponde à API do modelo de objeto do cliente desejado.To access SharePoint resources using REST, construct a RESTful HTTP request by using the OData standard, which corresponds to the desired client object model API. Por exemplo:For example:

Método de modelo de objeto cliente:Client object model method:

List.GetByTitle(listname)

Ponto de extremidade REST:REST endpoint:

http://server/site/_api/lists/getbytitle('listname')

O serviço Web Client. svc no SharePoint manipula a solicitação HTTP e serve a resposta apropriada no formato Atom ou JSON (JavaScript Object Notation).The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. Seu aplicativo cliente, em seguida, deverá analisar essa resposta.Your client application must then parse that response. A figura a seguir mostra uma visão de alto nível da arquitetura REST do SharePoint.The following figure shows a high-level view of the SharePoint REST architecture.

Arquitetura do serviço REST do SharePointSharePoint REST service architecture

Arquitetura do serviço REST do SharePoint

Com a funcionalidade e a facilidade de uso dos modelos de objeto cliente, eles continuam como a principal opção de desenvolvimento para comunicação com os sites do SharePoint usando código gerenciado por .NET Framework, Silverlight ou JavaScript.Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using .NET Framework managed code, Silverlight, or JavaScript.

Usar comandos HTTP com o serviço REST do SharePointUse HTTP commands with the SharePoint REST service

Para usar os recursos REST internos do SharePoint, crie uma solicitação HTTP RESTful usando o padrão OData, que corresponde à API do modelo de objeto do cliente que você deseja usar.To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. O serviço Web Client. svc trata a solicitação HTTP e serve a resposta apropriada no formato Atom ou JSON.The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. O aplicativo cliente, em seguida, deverá analisar essa resposta.The client application must then parse that response.

Os pontos de extremidade no serviço REST do SharePoint correspondem aos tipos e membros nos modelos de objeto do cliente do SharePoint. Usando solicitações HTTP, você pode usar esses pontos de extremidade REST para executar operações CRUD típicas com entidades do SharePoint, como listas e sites.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD operations against SharePoint entities, such as lists and sites.

Se você quiser fazer isso com um ponto de extremidadeIf you want to do this to an endpoint Use esta solicitação HTTPUse this HTTP request Tenha em menteKeep in mind
Ler um recursoRead a resource GETGET
Criar ou atualizar um recursoCreate or update a resource POSTPOST
  • Use post para criar entidades como listas e sites.Use POST to create entities such as lists and 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.The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections.
  • Para operações POST, todas as propriedades que não forem necessárias serão definidas com os valores padrão.For POST operations, any properties that are not required are set to their default values.
  • Se você tentar definir uma propriedade como somente leitura como parte de uma operação POST, o serviço retornará uma exceção.If you attempt to set a read-only property as part of a POST operation, the service returns an exception.
Atualizar ou inserir um recursoUpdate or insert a resource PUTPUT
  • Use as operações PUT e MERGE para atualizar objetos do SharePoint existentes.Use PUT and MERGE operations to update existing SharePoint objects.
  • 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.Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests.
  • Nas solicitações MERGE, a configuração de propriedades é opcional; quaisquer propriedades que você não configure explicitamente retêm sua propriedade atual.For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property.
  • Se você não especificar todas as propriedades necessárias nas atualizações de objeto em solicitações PUT, o serviço REST retornará uma exceção.For PUT requests, if you do not specify all required properties in object updates, the REST service returns an exception.
  • Além disso, as propriedades opcionais não definidas explicitamente são ajustadas em suas propriedades padrão.In addition, any optional properties you do not explicitly set are set to their default properties.
Excluir um recursoDelete a resource DELETEDELETE
  • 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.Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.
  • No caso de objetos recicláveis, como listas, arquivos e listas de itens, isso resultará em uma operação Recycle.In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

Construir URLs REST para acessar recursos do SharePointConstruct REST URLs to access SharePoint resources

Sempre que possível, o URI desses pontos de extremidade REST simula de forma próxima a assinatura API do recurso no modelo de objeto cliente do SharePoint.Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. Os pontos de entrada principais do serviço REST representam o conjunto de sites e o site do contexto especificado.The main entry points for the REST service represent the site collection and site of the specified context.

Para acessar um conjunto de sites específico, use a seguinte construção:To access a specific site collection, use the following construction:

http://server/site/_api/site

Para acessar um site específico, use a seguinte construção:To access a specific site, use the following construction:

http://server/site/_api/web

Em cada caso, servidor representa o nome do servidor e site representa o nome ou o caminho para o site específico.In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

A partir desse ponto de partida, você pode construir URIs REST mais específicos, "percorrendo" o modelo de objeto, usando os nomes das APIs do modelo de objeto do cliente separado por uma barra (/).From this starting point, you can then construct more specific REST URIs by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

Essa sintaxe não se aplica às APIs REST SocialFeedManager ou SocialFollowingManager.This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. Para obter mais informações, consulte:For more information, see:

Para obter mais diretrizes para determinar URIs de ponto de extremidade REST do SharePoint na assinatura das APIs de modelo de objeto do cliente correspondentes, consulte determinar URIs de ponto de extremidade do serviço REST do SharePoint.For more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.

Exemplos de ponto de extremidade REST do SharePointSharePoint REST endpoint examples

A tabela a seguir contém exemplos de URL de ponto de extremidade REST comuns para que você comece a trabalhar com dados do SharePoint.The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. Preceda http://server/site/_api/ os fragmentos de URL mostrados na tabela para construir uma URL REST totalmente qualificada.Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. Onde necessário para comandos POST, a tabela contém dados de amostra que você precisa passar no corpo da solicitação HTTP para criar o item do SharePoint especificado.Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. Os itens nas aspas representam variáveis que você deve substituir com seus valores.Items in quotes represent variables that you must replace with your values.

DescriçãoDescription Ponto de extremidade de URLURL endpoint Método HTTPHTTP method Conteúdo do corpoBody content
Recupera o título de uma listaRetrieves the title of a list web/title GETGET Não aplicávelNot applicable
Recupera todas as listas em um siteRetrieves all lists on a site lists GETGET Não aplicávelNot applicable
Recupera os metadados de uma única listaRetrieves a single list's metadata lists/getbytitle('listname') GETGET Não aplicávelNot applicable
Recupera itens dentro de uma listaRetrieves items within a list lists/getbytitle('listname')/items GETGET Não aplicávelNot applicable
Recupera uma propriedade específica de um documentoRetrieves a specific property of a document
(neste caso, o título do documento)(in this case, the document title)
lists/getbytitle('listname')?select=Title GETGET Não aplicávelNot applicable
Cria uma listaCreates a list lists POSTPOST Consulte exemploSee sample
Adiciona um item a uma listaAdds an item to a list lists/getbytitle('listname')/items POSTARPOST Consulte exemploSee sample

Cria um exemplo de dados de lista :Creates a list sample data:

{
  '__metadata': {
    'type': 'SP.List'
  },
  'AllowContentTypes': true,
  'BaseTemplate': 104 ,
  'ContentTypesEnabled': true,
  'Description': 'My list description ',
  'Title': 'RestTest '
}

Adiciona um item a uma lista de dados de amostra:Adds an item to a list sample data:

{
  '__metadata': {
    'type': 'SP.Data.listname.ListItem'
  },
  'Title': 'MyItem'
}

No JSON acima, substitua ListName pelo nome da sua lista do SharePoint, omitindo os espaços.In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.

Suporte ao trabalho em lotesBatch job support

O serviço REST do SharePoint Online (e do SharePoint 2016 ou posterior) oferece suporte à combinação de várias solicitações em uma única chamada para o serviço usando a $batch opção de consulta OData.The SharePoint Online (and on-premises SharePoint 2016 or 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.

Recursos de ODataOData resources

Tópicos do serviço REST do SharePointSharePoint REST service topics

Para saber mais sobre como usar o serviço REST do SharePoint, use os recursos a seguir.To learn more about using the SharePoint REST service, use the following resources.

TítuloTitle DescriçãoDescription
Realizar operações básicas usando os pontos de extremidade REST do SharePointComplete basic operations using SharePoint REST endpoints Realizar operações básicas de criação, leitura, atualização e exclusão (CRUD) com a interface REST do SharePoint.Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface.
Trabalhar com listas e itens de listas com RESTWorking with lists and list items with REST Executar operações CRUD básicas em listas e itens de lista com a interface REST do SharePoint.Perform basic CRUD operations on lists and list items with the SharePoint REST interface.
Trabalhando com pastas e arquivos com RESTWorking with folders and files with REST Executar operações CRUD básicas em pastas e arquivos com a interface REST do SharePoint.Perform basic CRUD operations on folders and files with the SharePoint REST interface.
Navegue pela estrutura de dados do SharePoint representada no serviço RESTNavigate the SharePoint data structure represented in the REST service Inicie a partir de um ponto de extremidade REST para um determinado item do SharePoint e navegue até e acesse itens relacionados, como sites pai ou a estrutura de bibliotecas onde esse item reside.Start from a REST endpoint for a given SharePoint item, and navigate to and access related items, such as parent sites or the library structure where that item resides.
Determinar as URIs de ponto de extremidade do serviço REST do SharePointDetermine SharePoint REST service endpoint URIs Diretrizes gerais para determinar URIs de ponto de extremidade REST do SharePoint da assinatura das APIs de modelo de objeto do cliente correspondentes.General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs.
Usar operações de consulta OData em solicitações REST do SharePointUse OData query operations in SharePoint REST requests Use uma ampla variedade de operadores de cadeia de caracteres de consulta OData para selecionar, filtrar e ordenar os dados que você solicita no serviço REST do SharePoint.Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service.
Fazer solicitações em lote com as APIs RESTMake batch requests with the REST APIs Combinar várias solicitações em uma única chamada para o serviço REST.Combine multiple requests into a single call to the REST service.
Sincronizar os itens do SharePoint usando o serviço RESTSynchronize SharePoint items using the REST service Sincronizar itens entre o SharePoint e seus suplementos ou serviços usando o recurso GetListItemChangesSinceToken , parte do serviço REST do SharePoint.Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service.
Carregar um arquivo, usando a API REST e jQueryUpload a file by using the REST API and jQuery Os exemplos de código neste artigo usam as solicitações jQuery AJAX e a interface REST para adicionar um arquivo local à biblioteca de Documentos e, em seguida, alterar as propriedades do item da lista que representa o arquivo carregado.The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.
Definir permissões personalizadas em uma lista usando a interface RESTSet custom permissions on a list by using the REST interface Os sites, listas e itens de lista do SharePoint são tipos de Protegívelobject, que herda as permissões de seu pai.SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. Para definir permissões personalizadas de um objeto, você precisará interromper a herança para que ele pare de herdar permissões do site pai e depois definir novas permissões adicionando ou removendo atribuições de função.To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.
Conceitos básicos de fluxos de trabalho no SharePointSharePoint workflow fundamentals Adicione a funcionalidade de pesquisa e aplicativos móveis para os clientes usando o serviço de Pesquisa REST no SharePoint Server 2013 e em qualquer tecnologia compatível com os requisitos da Web para REST.Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests.
Referência de API REST de feed social para o SharePointSocial feed REST API reference for SharePoint Pontos de extremidade REST do SharePoint para tarefas relacionadas a feeds.SharePoint REST endpoints for feed-related tasks.
Seguintes pessoas e conteúdo referência de API REST para o SharePointFollowing people and content REST API reference for SharePoint Pontos de extremidade REST do SharePoint para as pessoas e o conteúdo a seguir.SharePoint REST endpoints for following people and content.
Desenvolver Suplementos do SharePointDevelop SharePoint Add-ins Encontre artigos e recursos detalhados para ajudá-lo a criar recursos avançados em seus suplementos do SharePoint.Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins.