Trabalhar com sites do SharePoint no Microsoft Graph

Artigo
07/04/2024

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 leitura/escrita para SharePointSettings ao nível do inquilino
Lidar com recursos por ID do SharePoint, URL ou caminho relativo

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

Site(objeto de nível superior)
List
ListItem

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	Aceda às definições de nível de administração da organização.

Os sites também podem ser abordados por caminho através do nome de anfitrião do SharePoint, seguido de dois pontos e do caminho relativo para o site. Opcionalmente, pode fazer a transição de volta para abordar o modelo de recursos ao colocar 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}/

Um URL construído apenas com o nome do anfitrião aponta para o site raiz (SPWeb) na coleção de sites predefinida.

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

Um URL construído apenas com o nome do anfitrião e o ID siteCollection (SPSite) aponta para o site raiz (SPWeb) na coleção de sites especificada.

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

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

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

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

Os exemplos seguintes ajudam os programadores familiarizados com os padrões de URL da API REST v1 do SharePoint a adaptarem os seus casos de utilização a padrões de URL da API do Microsoft Graph semelhantes.

Padrão 1

Aceda ao site associado ao URL especificado SPWeb .

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

Exemplo 1

O exemplo seguinte devolve informações sobre o site associado ao SPWeb URL https://contoso.sharepoint.com/teams/hr/benefits. Tenha em atenção que benefits se trata de uma SPWeb 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

Aceda ao item de lista associado aos seguintes componentes.

Componente	Descrição
{hostname}	O nome do anfitrião do site.
{site-server-relative-url}	O URL relativo ao servidor do site (`SPWeb`).
{list-id}	O ID do GUID da lista (`SPList`) no site.
{item-id}	O GUID ou ID de número inteiro do item de lista (`SPListItem`) na lista.

O exemplo seguinte mostra um pedido 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 seguinte devolve informações sobre o com o SPListItem ID 42 de número inteiro que pertence à lista com o ID do GUID 5771e865-4e91-48b8-a0de-35a25d4e52fe. Esta lista pertence ao site associado ao 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

Partilhar via