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

  • Artigo

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

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

  2. Use as propriedades de objeto SPContextWebInformation que o operador /contextinfo retorna para acessar recursos adicionais como desejado.

Experimente

  1. Comece com uma URL para um determinado item do SharePoint. Por exemplo: https://{url_do_site}/doclib/myDocument.docx

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

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

  4. Leia o resumo do formulário e propriedades webFullUrl da resposta.

  5. Acrescente o ponteiro do serviço REST _api à URL da Web.

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

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.

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.

Confira também