Trabalhar com sites do SharePoint no Microsoft Graph

  • Artigo

A API do SharePoint no Microsoft Graph oferece suporte aos seguintes cenários principais:

  • Acesso aos sites, lists e drives do SharePoint (bibliotecas de documentos)
  • Suporte somente leitura para recursos de site (nenhuma capacidade de criar novos sites)
  • Suporte a leitura e gravação para lists, listItems e driveItems
  • Suporte de gravação de leitura para SharePointSettings no nível do locatário
  • Lidar com recursos por ID do SharePoint, URL ou caminho relativo

A API do SharePoint expõe três tipos de recursos principais:

A seguir está um exemplo de um recurso listItem.

{
  "fields": {
    "Title": "Access card",
    "Employee": "Ryan Gregg",
    "EmployeeId": "10",
    "CardSerial": "01235492",
    "Alias": "RGregg",
    "ID": 1,
    "ContentType": "Item",
    "Modified": "2016-09-19T23:15:25-07:00",
    "Created": "2016-09-19T23:15:25-07:00"
  },
  "createdBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "createdDateTime": "2016-09-20T06:15:25Z",
  "eTag": "48e941c3-9515-4c48-9760-c07c90c79d48,1",
  "id": "4",
  "lastModifiedBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "lastModifiedDateTime": "2016-09-20T06:15:25Z",
}

Recursos expõem dados de três maneiras diferentes:

  • Propriedades (como id e name) expõem valores simples.
  • Facetas (como campos e createdBy) expõem valores complexos.
  • Referências (como itens) apontam para conjuntos de outros recursos.

Você pode expandir referências na URL com o parâmetro de consulta expand; por exemplo, ?expand=fields. Você pode solicitar propriedades e facetas específicas com o parâmetro de consulta select; por exemplo, ?select=id,name. Por padrão, a maioria das propriedades e facetas retorna enquanto todas as referências ficam ocultas. Por questões de eficiência, recomendamos que você especifique selecionar e expandir para só retornar os dados mais importantes para você.

Recursos de raiz da API do SharePoint

Os exemplos a seguir são relativos a https://graph.microsoft.com/v1.0.

Caminho Descrição
/sites/root Site padrão da organização.
/sites/{site-id} Acessar um site específico por sua identificação.
/sites/{site-id}/drive Acessar a unidade padrão (biblioteca de documentos) desse site.
/sites/{site-id}/drives Enumerar as unidades (bibliotecas de documentos) no site.
/sites/{site-id}/sites Enumerar os subsites no site.
/sites/{site-id}/lists Enumerar as listas sob o site.
/sites/{site-id}/lists/{list-id}/items Enumerar listItems sob a lista.
/groups/{group-id}/sites/root Acesse um site de equipe do grupo.
/admin/sharepoint/settings Acesse as configurações de nível de administrador da organização.

Os sites também podem ser abordados por caminho usando o nome de host do SharePoint, seguidos por um ponto e o caminho relativo para o site. Opcionalmente, você pode fazer a transição para resolver o modelo de recurso colocando outro ponto no final.

Caminho Descrição
/sites/contoso.sharepoint.com:/teams/hr O site associado comhttps://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive Acessar a unidade padrão desse.

Observação para desenvolvedores do SharePoint existentes

A API do Microsoft Graph do SharePoint tem algumas diferenças essenciais das APIs CSOM. Os recurso do site mapeia para SPWeb. O site (SPWeb) raiz em um conjunto de sites tem uma faceta siteCollection, que contém informações sobre SPSite. Como as IDs de sites são exclusivas penas em sua coleção de site, abordar um site por ID requer o fornecimento do identificador de coleção de site e identificador de site.

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id},{spweb-id}/

Uma URL construída com apenas o nome do host aponta para o site raiz (SPWeb) na coleção de sites padrão.

GET https://graph.microsoft.com/v1.0/sites/{hostname}

Uma URL construída apenas com o nome do host e a ID do siteCollection (SPSite) aponta para o site raiz (SPWeb) no conjunto de sites fornecido.

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id}

Uma URL construída com apenas a ID do siteCollection (SPSite) aponta para o site raiz (SPWeb) na coleção de sites fornecida.

GET https://graph.microsoft.com/v1.0/sites/{spsite-id}

Mapeamento das URLs de API REST v1 do SharePoint para URLs do Microsoft API do Graph

Os exemplos a seguir ajudam os desenvolvedores familiarizados com os padrões de URL da API REST v1 do SharePoint a adaptar seus casos de uso a padrões de URL semelhantes do Microsoft API do Graph.

Padrão 1

Acesse o site associado à URL especificada SPWeb .

GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-server-relative-url}

Exemplo 1

O exemplo a seguir retorna informações sobre o site associado à SPWeb URL https://contoso.sharepoint.com/teams/hr/benefits. Observe que benefits é um SPWeb dentro da coleção de sites (SPSite) em https://contoso.sharepoint.com/teams/hr.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/teams/hr/benefits

Padrão 2

Acesse o item de lista associado aos seguintes componentes.

Componente Descrição
{hostname} O nome do host do site.
{site-server-relative-url} A URL relativa ao servidor do site (SPWeb).
{list-id} A ID guid da lista (SPList) no site.
{item-id} A ID GUID ou inteiro do item de lista (SPListItem) na lista.

O exemplo a seguir mostra uma solicitação que contém os componentes anteriores.

GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-server-relative-url}:/lists/{list-id}/items/{item-id}

Exemplo 2

O exemplo a seguir retorna informações sobre a SPListItem ID 42 com inteiro que pertence à lista com a ID 5771e865-4e91-48b8-a0de-35a25d4e52feguid . Essa lista pertence ao site associado SPWeb à URL https://contoso.sharepoint.com/teams/hr/benefits.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/teams/hr/benefits:/lists/5771e865-4e91-48b8-a0de-35a25d4e52fe/items/42