Realizar operações básicas usando os pontos de extremidade REST do SharePoint

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. A interface REST expõe todas as operações e entidades do SharePoint que estão disponíveis nas outras APIs cliente do SharePoint. Uma vantagem de usar REST é que você não precisa adicionar referências às bibliotecas do SharePoint ou assemblies de cliente. 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.

Para obter uma introdução à interface do REST do SharePoint e sua arquitetura, confira Conheça o serviço REST do SharePoint.

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.

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.

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.

Para obter informações sobre como usar APIs de outro cliente, confira:

• Concluir operações básicas usando um código da biblioteca do JavaScript no SharePoint- Concluir operações básicas usando um código da biblioteca de cliente do SharePoint
• Criar aplicativos do Windows Phone que acessam o SharePoint

Operações HTTP nos serviços REST do SharePoint

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 (Create, Read, Update e Delete) com entidades do SharePoint, como listas e 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.

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:

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.

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 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.

Ler dados com a interface REST do SharePoint

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#.

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. 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. Navegue até essa URL no seu navegador e veja o XML que é retornado. Quando faz a solicitação no código, você pode especificar se deseja receber a representação OData das listas em XML ou 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. Também pressupõe que você tenha um token de acesso OAuth válido que está armazenado na variável accessToken. 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. Observe que você não pode obter um token de acesso de código que está sendo executado em um cliente do navegador. Obtenha o token de acesso do código que está sendo executado em um servidor.

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.

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. Nesse caso, você não precisa fornecer um token de acesso.

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. 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.

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#. Ele pressupõe que você tem um token de acesso OAuth que está armazenando na variável accessToken.

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 recurso

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.

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.

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".

Escrevendo dados usando a interface REST

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.

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#.

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.

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ê.

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. 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.

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.

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. 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. 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. 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. Os cabeçalhos de resposta HTTP resultante passam o etag como o valor da chave ETag. Esse valor também está incluído nos metadados da entidade.

O exemplo a seguir mostra a tag de abertura <entry> para o nó XML que contém as informações da lista. A propriedade m:etag contém o valor etag.

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

Criar um site com REST

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

Como as solicitações REST diferem por ambiente

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.

As seções a seguir descrevem outras diferenças comuns entre ambientes.

A maneira de receber e enviar o valor do resumo do formulário depende do suplemento

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:

• Nos suplementos hospedados no SharePoint, você pode passar apenas o cabeçalho a seguir:

  "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.

• Em suplementos hospedados em nuvem que usam a biblioteca entre domínios do JavaScript, não é necessário especificar o valor de resumo do formulário. Por padrão, SP.RequestExecutor lida com isso automaticamente para você. (Também lida com o comprimento do conteúdo).

Os suplementos que usam o OAuth devem passar os tokens de acesso nas solicitações

Suplementos hospedados na nuvem usam o OAuth ou a biblioteca entre domínios para autorizar o acesso aos dados do SharePoint. 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. Nesse caso, você precisa incluir um cabeçalho Authorization para enviar o token de acesso. 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.

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.

Os URIs de pontos de extremidade em solicitações entre domínios usam o SP.AppContextSite para alterar o contexto

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:

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

As solicitações de bibliotecas entre domínios usam esse formato ao acessar dados no 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 (':').

Tabela 1. Usando o ponto de extremidade SP.AppContextSite para alterar o contexto da solicitação

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. O exemplo também mostra como fazer referência à biblioteca entre domínios, que é definida no arquivo SP.RequestExecutor.js no host da Web. O exemplo presume que o suplemento inicia pelo 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.

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

Propriedades usadas em solicitações REST

A Tabela 2 mostra as propriedades que são comumente usadas em solicitações HTTP para o serviço REST do SharePoint.

Tabela 2. Quando usar as propriedades de solicitação REST em solicitações HTTP

Suporte ao trabalho em lotes

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. Para obter detalhes e links de amostras de código, confira Fazer solicitações em lote com APIs REST.

Confira também

• Conheça o serviço REST do SharePoint
• Proteger acesso a dados e modelos de objeto cliente para suplementos do SharePoint
• Utilizar dados externos no SharePoint
• Recursos de OData
• Definir permissões personalizadas em uma lista usando a interface REST
• Desenvolver suplementos do SharePoint