Navegar pela estrutura de dados do SharePoint representada no serviço REST

Artigo
09/26/2023

Quando estiver trabalhando com o serviço REST do SharePoint, você geralmente começará sabendo a URL de um item específico do SharePoint, mas quiser acessar itens relacionados, como a estrutura de pasta ou biblioteca onde reside esse item. Por exemplo, suponha que você crie um suplemento onde o usuário insere a URL de um documento em uma biblioteca do SharePoint. O suplemento deve, em seguida, dividir essa URL para descobrir a URL real do site do SharePoint. Depois disso, o suplemento poderá então fazer mais solicitações do site em nome do usuário, como para criar, atualizar ou excluir itens ou recursos relacionados.

Para fazer isso, seu suplemento precisa consultar o SharePoint para obter as seguintes informações:

As URLs relativas do servidor do site e o conjunto de sites que contêm o recurso.
Um resumo de formulário para permitir que você faça solicitações que altere o estado do recurso, como POST, PUT, MERGE e DELETE.

O processo básico

Use o operador /contextinfo com a URL determinada para acessar o site e endereços de conjunto de sites e o resumo do formulário. Use o operador /contextinfo no formato a seguir:
```
POST https://{site_url}/_api/contextinfo
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
```
Para aumentar a segurança contra tentativas de scripts entre sites, o operador /contextinfo aceita apenas solicitações POST.
Use as propriedades de objeto SPContextWebInformation que o operador /contextinfo retorna para acessar recursos adicionais como desejado.

Experimente

Comece com uma URL para um determinado item do SharePoint. Por exemplo: https://{url_do_site}/doclib/myDocument.docx
Remova o nome do recurso específico do final da URL, para que a URL aponte para uma biblioteca de documento, pasta ou lista. Neste caso: https://{url_do_site}/doclib/

Acrescente o ponteiro do serviço REST e o operador /contextinfo à URL:

POST https://{site_url}/_api/doclib/contextinfo
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Leia o resumo do formulário e propriedades webFullUrl da resposta.
Acrescente o ponteiro do serviço REST _api à URL da Web.
Use a URL resultante e o resumo do formulário para fazer solicitações de outros recursos que você precisa.

Dica

Não é necessário passar o resumo do formulário, se você estiver fazendo solicitações GET ou fazer solicitações usando um token OAuth validado.

Navegar por sites pai e filho

Quando você navega na estrutura do seu site usando o modelo de objeto do servidor do SharePoint, usa as propriedades SPWeb.ParentWeb e SPWeb.Webs para acessar os objetos que representam sites pai e filho.

Os recursos REST correspondentes, web/parentweb e web/webs, não retornam os objetos que representam os sites. Isso ocorre porque o serviço REST está de acordo com as normas de OData e retorna representações completas de site que tornariam essas solicitações ineficientes. Em vez disso, elas retornarão um objeto WebInfo, que contém as propriedades escalar do site, mas sem entidade relacionada define como conjuntos ou conjuntos de campo.

Para navegar até um site pai ou secundário específico, crie a URL REST apropriada para esse site usando a propriedade Id ou Title. Dali é possível acessar os conjuntos de entidade relacionada do site.

Navegar na estrutura de pastas

O serviço REST do SharePoint não oferece suporte para percorrer a hierarquia de um site pela criação da URL. Em vez disso, use o equivalente REST do método Web.GetFolderByServerRelativeUrl. Por exemplo:

Navegação não suportada pelo serviço REST:

https://{site_url}/_vti_bin/client.svc/web/lists/SharedDocuments/folder1/stuff/things/Recycle

A navegação compatível com o serviço REST:

https://{site_url}/_vti_bin/client.svc/web/GetFolderByServerRelativeUrl('SharedDocuments/folder1/stuff/things')/Recycle

Propriedades do objeto SPContextWebInformation

Propriedade SPContextWebInformation	Descrição
webFullUrl	Obtém a URL relativa ao servidor do site mais próximo.
siteFullUrl	Obtém a URL relativa ao servidor da raiz do conjunto de sites em que o site está contido. Se a Web mais próxima for a raiz de um conjunto de sites, o valor da propriedade webFullUrl será igual à propriedade siteFullUrl.
formDigestValue	Obtém resumo do formulário de solicitação do servidor.
LibraryVersion	Obtém a versão atual da biblioteca REST.
SupportedSchemaVersions	Obtém as versões do esquema da biblioteca REST/CSOM que têm suporte.

Objeto WebInfo

Propriedade WebInfo	Descrição
Created	Obtém um valor que especifica quando o site foi criado.
Descrição	Obtém ou define a descrição do site.
Id	Obtém um valor que especifica o identificador de site.
Idioma	Obtém um valor que especifica o ID do local (LCID) do idioma usado no site.
LastItemModifiedDate	Obtém um valor que especifica quando um item foi modificado pela última vez no site.
Título	Obtém ou define o título do site.
WebTemplateId	Obtém o identificador do modelo de site.

Partilhar via