Trabajar con sitios de SharePoint en Microsoft Graph

Artículo
07/04/2024

La API de SharePoint en Microsoft Graph admite los siguientes escenarios principales:

Acceso a los sitios, las listas y las unidades (bibliotecas de documentos) de SharePoint
Soporte de solo lectura de los recursos del sitio (sin capacidad para crear nuevos sitios)
Compatibilidad de lectura y escritura para recursos list, listItem y driveItem
Compatibilidad con lectura y escritura para SharePointSettings de nivel de inquilino
Recursos de dirección por la ruta de acceso relativa, URL o id. de SharePoint

La API de SharePoint expone tres tipos principales de recursos:

Site(objeto de nivel superior)
Lista
ListItem

A continuación se muestra un ejemplo de un 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",
}

Los recursos exponen los datos de tres maneras diferentes:

Propiedades (como id y name) exponen valores simples.
Facetas (como fields y createdBy) exponen valores complejos.
Referencias (como items) indican colecciones de otros recursos.

Puede ampliar las referencias en la dirección URL con el parámetro de consulta expand, por ejemplo, ?expand=fields. Puede solicitar propiedades y facetas específicas con el parámetro de consulta select, por ejemplo, ?select=id,name. De manera predeterminada, la mayoría de las propiedades y las facetas se devuelve mientras que todas las referencias se ocultan. Por motivos de eficacia, recomendamos que especifique select y expand para que solo devuelvan los datos que le interesen.

Recursos raíz de las API de SharePoint

Los ejemplos siguientes son relativos al https://graph.microsoft.com/v1.0.

Ruta de acceso	Descripción
/sites/root	Sitio predeterminado de la organización.
/sites/{site-id}	Acceso a un sitio específico por su id.
/sites/{site-id}/drive	Acceso a la unidad predeterminada (biblioteca de documentos) para este sitio.
/sites/{site-id}/drives	Enumerar las unidades (bibliotecas de documentos) en el sitio.
/sites/{site-id}/sites	Enumerar los sitios secundarios en sitio.
/sites/{site-id}/lists	Enumerar las listas en el sitio.
/sites/{site-id}/lists/{list-id}/items	Enumerar los listItems en la lista.
/groups/{group-id}/sites/root	Acceso a un sitio de equipo de grupo.
/admin/sharepoint/settings	Acceda a la configuración de nivel de administrador de la organización.

Los sitios también se pueden abordar por ruta de acceso mediante el nombre de host de SharePoint, seguido de dos puntos y la ruta de acceso relativa al sitio. Opcionalmente, puede volver a abordar el modelo de recursos si coloca otro dos puntos al final.

Ruta de acceso	Descripción
/sites/contoso.sharepoint.com:/teams/hr	El sitio asociado con https://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive	Acceso a la unidad predeterminada para este sitio.

Nota para los desarrolladores de SharePoint existentes

La API de SharePoint de Microsoft Graph tiene algunas diferencias clave con las API de CSOM. El recurso del site se asigna a SPWeb. El recurso site raíz (SPWeb) en una colección de sitios tiene una faceta siteCollection, que contiene información sobre SPSite. Debido a que los identificadores para los sitios solo son únicos dentro de su colección de sitios, el direccionamiento a un sitio a través del id. requiere proporcionar el identificador de la colección de sitios y el identificador del sitio.

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

Una dirección URL construida con solo el nombre de host apunta al sitio raíz (SPWeb) en la colección de sitios predeterminada.

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

Una dirección URL construida con solo el nombre de host y el identificador de siteCollection (SPSite) apuntan al sitio raíz (SPWeb) de la colección de sitios especificada.

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

Una dirección URL construida con solo el identificador siteCollection (SPSite) apunta al sitio raíz (SPWeb) de la colección de sitios especificada.

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

Asignación de direcciones URL de API rest v1 de SharePoint a direcciones URL de Api de Microsoft Graph

En los ejemplos siguientes se ayuda a los desarrolladores a familiarizarse con los patrones de dirección URL de la API rest v1 de SharePoint para adaptar sus casos de uso a patrones similares de direcciones URL de la API de Microsoft Graph.

Patrón 1

Acceda al sitio asociado a la dirección URL especificada SPWeb .

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

Ejemplo 1

En el ejemplo siguiente se devuelve información sobre el sitio asociado a la SPWeb dirección URL https://contoso.sharepoint.com/teams/hr/benefits. Tenga en cuenta que benefits se encuentra SPWeb dentro de la colección de sitios (SPSite) en https://contoso.sharepoint.com/teams/hr.

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

Patrón 2

Acceda al elemento de lista asociado a los siguientes componentes.

Componente	Descripción
{hostname}	Nombre de host del sitio.
{site-server-relative-url}	Dirección URL relativa al servidor del sitio (`SPWeb`).
{list-id}	Identificador GUID de la lista (`SPList`) del sitio.
{item-id}	GUID o identificador entero del elemento de lista (`SPListItem`) de la lista.

En el ejemplo siguiente se muestra una solicitud que contiene los componentes anteriores.

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

Ejemplo 2

En el ejemplo siguiente se devuelve información sobre con el SPListItem identificador 42 entero que pertenece a la lista con el identificador 5771e865-4e91-48b8-a0de-35a25d4e52feGUID . Esta lista pertenece al sitio asociado a la SPWeb dirección 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

Compartir a través de