Trabajar con sitios de SharePoint en Microsoft Graph

  • Artículo

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:

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 Microsoft Graph API

Los ejemplos siguientes ayudan a los desarrolladores a familiarizarse con los patrones de dirección URL de la API rest v1 de SharePoint adaptan sus casos de uso a patrones de direcciones URL de Microsoft Graph API similares.

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