Determinar os URIs de ponto de extremidade do serviço REST do SharePoint

Dica

Antes de começar, confira os seguintes recursos:

Conheça o serviço REST do SharePoint Navegue na estrutura de dados do SharePoint representada no serviço REST

• Usar operações de consulta OData em solicitações REST do SharePoint

Estrutura da URI do ponto de extremidade REST do SharePoint

Antes de poder acessar um recurso do SharePoint usando o serviço REST, primeiro você precisa descobrir o ponto de extremidade URI que aponta para esse recurso. 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. Por exemplo:

CSOM

var items = List.GetByTitle(listname).GetItems();

http

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Em alguns casos, no entanto, a URI de ponto de extremidade difere da assinatura do modelo de objeto cliente correspondente para cumprir convenções OData ou REST.

A figura a seguir mostra a estrutura de sintaxe geral de URIs REST do SharePoint.

Estrutura da sintaxe de URIs do REST do SharePoint

Alguns pontos de extremidade de recursos do SharePoint desviam dessa estrutura de sintaxe:

• Métodos que exigem tipos complexos como parâmetros. Se o método de modelo de objeto correspondente do cliente exigir que os tipos complexos sejam passados como parâmetros, o ponto de extremidade REST poderá desviar dessa construção de sintaxe para abranger as limitações de REST.
• Propriedades e métodos estáticos. Pontos de extremidade REST desviam desta estrutura de sintaxe para URIs que representam métodos e propriedades estáticas.

Determine os pontos de extremidade do serviço REST do SharePoint

Para construir um ponto de extremidade REST para um recurso do SharePoint, siga estas etapas:

1. Comece com a referência de serviço REST:

   https://{site_url}/_api

2. Especifique o ponto de entrada apropriado. Por exemplo:

   https://{site_url}/_api/web

3. Navegue do ponto de entrada para os recursos específicos que você deseja acessar. Isso inclui especificar parâmetros de pontos de extremidade que correspondam aos métodos no modelo de objeto cliente. Por exemplo:

   https://{site_url}/_api/web/lists/getbytitle('{list_name}')

Fazer referência ao serviço REST do SharePoint em sua URI de ponto de extremidade

Use _api para expressar o serviço REST do SharePoint nos URIs de ponto de extremidade. O serviço REST faz parte do serviço da Web client.svc. No entanto, para facilitar a construção da URI REST e diminuir o caminho URI REST básico, o serviço REST usa _api para retirar a necessidade de referenciar de forma explícita o serviço da Web client.svc.

O serviço REST ainda reconhece e aceita URIs que fazem referência ao serviço Web client.svc. Por exemplo, você pode usar https://{site_url}/_vti_bin/client.svc/web/lists em vez de https://{site_url}/_api/web/lists. No entanto, usar _api é a convenção preferencial. URLs têm um limite de 256 caracteres então, usar _api encurta a URI básica, deixando mais caracteres para serem usados na criação do restante da URL.

Especifique pontos de entrada para o serviço REST do SharePoint

Os pontos de entrada principais do serviço REST representam o conjunto de sites e o site do contexto especificado. Dessa forma, esses pontos de entrada correspondem à propriedade ClientContext.Site e à propriedade ClientContext.Web nos modelos de objeto cliente.

Para acessar um conjunto de sites específico, use a seguinte construção:

https://{site_url}/_api/site

Para acessar um site específico, use a seguinte construção:

https://{site_url}/_api/web

Além disso, para /site e /web, o serviço REST inclui diversos outros pontos de acesso que permitem aos desenvolvedores navegar para funcionalidades específicas. A tabela a seguir lista alguns desses pontos de acesso.

Área de recursos	Ponto de acesso
Site	https://{site_url}/_api/site
Web	https://{site_url}/_api/web
Perfil de Usuário	https://{site_url}/_api/SP.UserProfiles.PeopleManager
Pesquisar	https://{site_url}/_api/search

Navegue até os recursos específicos que você deseja acessar

A partir daqui, construa pontos de extremidade REST mais específicos “percorrendo” o modelo de objeto usando os nomes das APIs do modelo de objeto do cliente separadas por uma barra (/). A tabela a seguir mostra exemplos de chamadas de modelo de objeto do cliente e o ponto de extremidade REST equivalente.

API de modelo de objeto cliente	Ponto de extremidade REST
ClientContext.Web.Lists	https://{site_url}/_api/web/lists
ClientContext.Web.Lists[guid]	https://{site_url}/_api/web/lists('<guid>')
ClientContext.Web.Lists.GetByTitle("Title")	https://{site_url}/_api/web/lists/getbytitle('<Title>')

URIs de ponto de extremidade não diferenciam maiúsculas de minúsculas. Na tabela anterior, por exemplo, use /getbytitle para especificar o REST equivalente ao método GetByTitle().

Especifique os parâmetros nos URIs do ponto de extremidade REST

O SharePoint estende a especificação OData para permitir que você use parênteses para especificar parâmetros de método e valores de índice. Isso evita possíveis problemas de diferenciação em URIs que contêm vários parâmetros com o mesmo nome. Por exemplo, as duas URIs a seguir contêm parâmetros que têm o mesmo nome:

https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')

https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')

Para especificar vários parâmetros, inclua o parâmetro como um par de valor e nome e separe os parâmetros com vírgulas. Por exemplo:

https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)

A figura a seguir mostra a sintaxe de parâmetro REST do SharePoint.

Sintaxe de parâmetro REST do SharePoint

Tipos complexos como parâmetros para o serviço REST

Alguns métodos no modelo de objeto cliente exigem uma grande carga como parâmetro. Para que os pontos de extremidade REST mantenham a paridade de funcionalidade com APIs de modelo de objeto cliente correspondente, os pontos de extremidade precisam aceitar um tipo complexo como parâmetro. Nesses casos, o serviço REST estende o protocolo OData existente para habilitar esses pontos de extremidade REST a aceitar um único tipo complexo como um parâmetro. Isso se aplica apenas a operações POST e você precisa passar o tipo complexo para o formato Atom ou JSON, de acordo com os padrões OData.

Por exemplo, o método ListCollection.Add usa um objeto Microsoft.SharePoint.Client.ListCreationInformation como um parâmetro. Para adicionar uma lista a um site especificado, construa o ponto de extremidade REST apropriado da seguinte maneira:

POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}

{ "d" : {
    "results": {
      "__metadata": {
        "type": "SP.ListCreationInformation"
      },
      "CustomSchemaXml": "…large payload…/",
      "Description": "desc",
      "DocumentTemplateType": "1",
      "TemplateType": "101",
      "Title": "Announcements"
    }
  }
}

Usando aliases de parâmetro nas chamadas de serviço REST

É possível usar a semântica de "alias de parâmetro" no OData para passar parâmetros para um ponto de extremidade REST do SharePoint. No alias de parâmetro, o valor do parâmetro é identificado com um alias na chamada de parâmetro e o valor real é especificado na sequência de consulta da URI. Isso permite que você ofereça suporte a mais tipos de caracteres e formatação consistente usando a cadeia de caracteres de consulta.

Por exemplo, as seguintes URIs REST são equivalentes:

Especifique o valor do parâmetro diretamente:

https://{site_url}/_api/web/applyWebTemplate("STS#0")

Use um alias de parâmetro e especifique o valor real do parâmetro na cadeia de caracteres de consulta do URI:

https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"

No entanto, o serviço REST do SharePoint não oferece suporte a tipos de passagem complexos por alias de parâmetro. Por exemplo, a URI a seguir que contém um tipo complexo no alias do parâmetro, não tem suporte:

https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}

Sintaxe de alias do parâmetro de serviço REST do SharePoint

Especificar dicionários como valores de parâmetro

Nos pontos de extremidade REST que correspondem aos métodos que usam Dictionary<String, String> dicionários como parâmetros, passe o dicionário como uma série de pares de nome-valor separados por vírgula na cadeia de caracteres de consulta.

Sintaxe do serviço REST para parâmetros de dicionário

Um Dictionary<String, object> é representado como um objeto de vários valores, chamado KeyedPropertyValue, com as seguintes propriedades de cadeia de caracteres:

• Key A chave do objeto de vários valores.
• Value O valor do objeto.
• ValueType O tipo de valor do objeto. Para tipos de valor simples que mapeiam para tipos EDM (Modelo de Dados de Entidade) existentes, o serviço REST retorna a cadeia de caracteres de tipo EDM apropriada; por exemplo, "Edm.String". Caso contrário, o serviço REST retornará o tipo de valor retornado pela função Type.ToString .

Especificar valores de parâmetro na cadeia de caracteres de consulta

Se a URI REST terminar em uma chamada de método, você poderá usar uma sintaxe de cadeia de caracteres de consulta para especificar os valores de parâmetro do método. Por exemplo:

https://{site_url}/_api/web/applyWebTemplate?template="STS#0"

A figura a seguir mostra a sintaxe do serviço REST para os parâmetros na cadeia de caracteres de consulta.

Sintaxe de serviço REST para parâmetros na cadeia de caracteres de consulta

Especificar métodos e propriedades estáticos como URIs de serviço REST

Para construir URIs que correspondam às propriedades ou aos métodos estáticos, use o nome da API correspondente do modelo de objeto ECMAScript, começando com a declaração de namespace e usando notação de ponto. Por exemplo, SP. Utilities.Utility.getImageUrl(imageName) no modelo de objeto cliente ECMAScript teria o seguinte equivalente REST:

https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')

Entretanto, propriedades estáticas podem ser acessadas apenas diretamente e não são permitidas como parte de uma composição de URI maior. Por exemplo, acessar diretamente o método SP.Utility.AssetsLibrary no REST é permitido, conforme a seguir:

https://{site_url}/_api/SP.Utility.assetsLibrary/id

No entanto, usando esse local de recursos como um parâmetro para um URI mais complexo, como mostrado no exemplo a seguir, não é permitido:

https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)

A figura a seguir mostra a sintaxe de membro estático do serviço REST do SharePoint.

Sintaxe de membro estático do serviço REST do SharePoint

Se você quiser selecionar, filtrar ou organizar os dados solicitados de um ponto de extremidade, o serviço REST do SharePoint oferece suporte a uma ampla variedade de operadores de cadeias de caracteres de consulta do OData. Para obter mais informações, confira Use operações de consulta OData em solicitações REST do SharePoint.

Confira também

• Conheça o serviço REST do SharePoint
• Usar valores ETag por meio do serviço REST para obter o controle de versão do item de lista de documento
• Recursos de OData
• Desenvolver suplementos do SharePoint