Utilisation des sites SharePoint dans Microsoft Graph

Article
05/09/2023

L’API SharePoint dans Microsoft Graph prend en charge les scénarios de base suivants :

Accès aux ressources site, list et drive SharePoint (bibliothèques de documents)
Prise en charge en lecture seule des ressources site (aucune possibilité de créer des sites)
Prise en charge en lecture-écriture des ressources list, listItem et driveItem
Prise en charge en lecture-écriture de SharePointSettings au niveau du locataire
Accès aux ressources par ID SharePoint, URL ou chemin d’accès relatif

L’API SharePoint présente trois types de ressources principaux :

Site(objet de niveau supérieur)
List
ListItem

Voici un exemple de ressource 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",
}

Les ressources affichent les données de trois manières différentes :

Les propriétés (comme id et name) exposent des valeurs simples.
Les facettes (comme fields et createdBy) exposent des valeurs complexes.
Les références (comme items) renvoient vers des collections d’autres ressources.

Vous pouvez développer les références dans votre URL à l’aide du paramètre de requête expand. Par exemple : ?expand=fields. Vous pouvez demander des facettes et des propriétés spécifiques à l’aide du paramètre de requête select. Par exemple : ?select=id,name. Par défaut, la plupart des propriétés et des facettes sont renvoyées alors que toutes les références sont masquées. Pour gagner en efficacité, nous vous recommandons de spécifier select et expand afin de renvoyer uniquement les données qui vous intéressent.

Ressources racine de l’API SharePoint

Les exemples suivants sont relatifs à https://graph.microsoft.com/beta.

Chemin	Description
/sites/root	Site par défaut de l’organisation.
/sites/{site-id}	Accédez à un site spécifique à l’aide de son ID.
/sites/{site-id}/drive	Accédez au lecteur par défaut (bibliothèque de documents) pour le site donné.
/sites/{site-id}/drives	Énumérez les lecteurs (bibliothèques de documents) sous le site.
/sites/{site-id}/sites	Énumérez les sous-sites sous le site.
/sites/{site-id}/lists	Énumérez les ressources list sous la ressource site.
/sites/{site-id}/lists/{list-id}/items	Énumérez les ressources listItem sous la ressource list.
/groups/{group-id}/sites/root	Accédez à la ressource site d’équipe d’un groupe.
/admin/sharepoint/settings	Accédez aux paramètres de niveau administrateur du organization.

Les sites peuvent également être traités par le chemin d’accès à l’aide du nom d’hôte SharePoint, suivi d’un signe deux-points et du chemin d’accès relatif au site. Vous pouvez éventuellement revenir à l’adressage du modèle de ressource en plaçant un autre signe deux-points à la fin.

Path	Description
/sites/contoso.sharepoint.com:/teams/hr	Site associé à https://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive	Accédez au lecteur par défaut pour ce site.

Remarque pour les développeurs de SharePoint

L’API SharePoint pour Microsoft Graph comporte quelques différences clés avec les API CSOM. La ressource site correspond à SPWeb. La ressource site racine (SPWeb) dans une collection de sites a une facette siteCollection, qui contient des informations sur la ressource SPSite. Les ID de sites étant uniques au sein de leur collection de sites, définir un site en fonction de l’ID nécessite de fournir l’identificateur de collection de sites et l’identificateur de site.

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

Une URL construite avec uniquement le nom d’hôte pointe vers le site racine (SPWeb) dans la collection de sites par défaut.

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

Une URL construite avec uniquement le nom d’hôte et l’ID siteCollection (SPSite) pointe vers le site racine (SPWeb) dans la collection de sites donnée.

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

Une URL construite avec uniquement l’ID siteCollection (SPSite) pointe vers le site racine (SPWeb) dans la collection de sites donnée.

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

Mappage d’URL d’API REST SharePoint v1 à des URL Microsoft API Graph

Les exemples suivants aident les développeurs à se familiariser avec les modèles d’URL de l’API REST SharePoint v1 à adapter leurs cas d’usage à des modèles d’URL microsoft API Graph similaires.

Modèle 1

Accédez au site associé à l’URL spécifiée SPWeb .

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

Exemple 1

L’exemple suivant retourne des informations sur le site associé à l’URL SPWebhttps://contoso.sharepoint.com/teams/hr/benefits. Notez que benefits est un SPWeb dans la collection de sites (SPSite) à l’emplacement https://contoso.sharepoint.com/teams/hr.

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

Modèle 2

Accédez à l’élément de liste associé aux composants suivants.

Composant	Description
{hostname}	Nom d’hôte du site.
{site-server-relative-url}	URL relative du serveur du site (`SPWeb`).
{list-id}	ID GUID de la liste (`SPList`) dans le site.
{item-id}	GUID ou ID entier de l’élément de liste (`SPListItem`) dans la liste.

L’exemple suivant montre une requête qui contient les composants précédents.

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

Exemple 2

L’exemple suivant retourne des informations sur le avec l’ID SPListItem42 entier qui appartient à la liste avec l’ID 5771e865-4e91-48b8-a0de-35a25d4e52feGUID . Cette liste appartient au site associé à l’URL SPWebhttps://contoso.sharepoint.com/teams/hr/benefits.

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

Partager via