Découverte du service REST SharePoint

SharePoint inclut un service nommé REST (Representational State Transfer), comparable aux modèles objet client existants de SharePoint. Les développeurs peuvent désormais interagir à distance avec les données de SharePoint à l’aide de n’importe quelle technologie qui prend en charge les requêtes web REST. Cela signifie que les développeurs peuvent effectuer des opérations CRUD (Create, Read, Update et Delete) à partir de leurs applications clientes, de leurs solutions et de leurs compléments SharePoint, en utilisant les technologies web REST et la syntaxe Open Data Protocol (OData) standard.

Conditions préalables

Cette rubrique demande une connaissance de base sur REST et la création de demandes REST.

Fonctionnement du service REST SharePoint

SharePoint ajoute la possibilité d’interagir à distance avec les sites SharePoint à l’aide de REST. Désormais, vous pouvez interagir directement avec les objets SharePoint en utilisant une technologie prenant en charge les fonctionnalités REST standard.

Pour accéder aux ressources SharePoint à l’aide de REST, créez une requête HTTP RESTful à l’aide de la norme OData (Open Data Protocol), qui correspond à l’API du modèle objet client désirée. Par exemple :

CSOM

var items = List.GetByTitle(listname).GetItems();

http

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Le service web client.svc dans Sharepoint gère la requête HTTP et renvoie la réponse appropriée au format Atom ou JSON (JavaScript Object Notation). Votre application cliente doit ensuite effectuer une analyse syntaxique de cette réponse. La figure suivante présente un aperçu de haut niveau de l’architecture REST SharePoint.

Architecture de service REST SharePoint

En raison de la fonctionnalité et de la facilité d’utilisation fournies par les modèles objet client, ceux-ci demeurent l’option de développement principale pour la communication avec les sites SharePoint à l’aide .NET Framework, de Silverlight (désormais déconseillé) ou de JavaScript.

Utiliser des commandes HTTP avec le service REST SharePoint

Pour utiliser les fonctionnalités REST intégrées dans SharePoint, vous devez créer une requête HTTP RESTful en utilisant la norme OData, qui correspond à l’API du modèle objet client que vous souhaitez utiliser. Le service web client.svc gère la requête HTTP et renvoie la réponse appropriée au format Atom ou JSON. L’application cliente doit ensuite effectuer une analyse syntaxique de cette réponse.

Les points de terminaison du service REST SharePoint correspondent aux types et aux membres dans les modèles objet client SharePoint. Avec des requêtes HTTP, vous pouvez utiliser ces points de terminaison REST pour effectuer des opérations CRUD standard sur des entités SharePoint, telles que les listes et les sites.

Si vous voulez effectuer cette opération sur un point de terminaison	Utilisez cette requête HTTP	N’oubliez pas
Lire une ressource	GET
Créer ou modifier une ressource	POST	Utilisez POST pour créer des entités telles que des listes et des sites. Le service REST SharePoint prend en charge l’envoi de commandes OST qui incluent les définitions d’objet vers les points de terminaison qui représentent des collections. Pour les opérations POST, les propriétés qui ne sont pas obligatoires sont définies sur leurs valeurs par défaut. Si vous tentez de définir une propriété en lecture seule dans le cadre d’une opération POST, le service renvoie une exception.
Mettre à jour ou insérer une ressource	PUT	Utilisez les opérations PUT et MERGE pour mettre à jour des objets SharePoint existants. Tous les points de terminaison de service qui représentent une opération de définition de propriété d’objet prennent en charge les demandes PUT et MERGE. Pour les demandes MERGE, la définition de propriétés est facultative. Les propriétés que vous ne définissez pas explicitement conservent leur valeur en cours. Pour les requêtes PUT, si vous ne spécifiez pas toutes les propriétés requises dans les mises à jour d’objet, le service REST renvoie une exception. En outre, les propriétés facultatives que vous ne spécifiez pas explicitement sont définies sur leur valeur par défaut.
Supprimer une ressource	DELETE	Utilisez la commande HTTP DELETE sur l'URL spécifique du point de terminaison pour supprimer l'objet SharePoint représenté par ce point de terminaison. Il existe des objets recyclables, comme des listes, des fichiers et des éléments de liste dans lesquels cette action entraîne une opération Recycle.

Construire des URL REST pour accéder à des ressources SharePoint

Dès que possible, l'URI de ces points de terminaison REST imite la signature de l'API de la ressource dans le modèle objet client SharePoint. Les principaux points d'entrée pour le service REST représentent la collection de sites et le site du contexte spécifié.

Pour accéder à une collection de sites spécifique, utilisez la construction suivante :

https://{site_url}/_api/site

Pour accéder à un site spécifique, utilisez la construction suivante :

https://{site_url}/_api/web

Dans chaque cas, server représente le nom du serveur et site le nom du site spécifique ou son chemin d’accès.

À partir de là, vous pouvez créer des URI REST plus spécifiques en « parcourant » le modèle objet à l’aide des noms des API du modèle objet client séparés par une barre oblique (/).

Cette syntaxe ne s’applique pas aux API REST SocialFeedManager et SocialFollowingManager. Pour plus d’informations, reportez-vous aux rubriques suivantes :

• Référence de l’API REST des flux sociaux pour SharePoint
• Référence de l’API REST de suivi des personnes et du contenu pour SharePoint

Pour obtenir des instructions supplémentaires permettant de déterminer l’URI des points de terminaison REST SharePoint à partir de la signature des API de modèle objet client correspondantes, consultez la rubrique Déterminer les URI de point de terminaison du service REST SharePoint.

Exemples de point de terminaison REST SharePoint

Le tableau suivant contient des exemples types d’URL de point de terminaison REST pour vous aider à utiliser les données de SharePoint. Ajoutez http://server/site/_api/ au début des fragments d’URL fournis dans le tableau pour composer une URL REST complète. Lorsque c’est nécessaire pour les commandes POST, le tableau contient des exemples de données que vous devez transmettre dans le corps de la requête HTTP pour créer l’élément SharePoint spécifié. Les éléments entre guillemets représentent des variables que vous devez remplacer par vos valeurs.

Description	Point de terminaison d’URL	Méthode HTTP	Contenu du corps
Extrait le titre d’un site	web/title	GET	Non applicable
Récupère toutes les listes sur un site	lists	GET	Non applicable
Récupère les métadonnées d’une seule liste	lists/getbytitle('listname')	GET	Non applicable
Extrait les éléments d’une liste	lists/getbytitle('listname')/items	GET	Non applicable
Récupère une propriété spécifique d’une liste (dans ce cas, le titre de la liste)	lists/getbytitle('listname')?select=Title	GET	Non applicable
Crée une liste	lists	POST	Voir les exemples
Ajoute un élément dans une liste	lists/getbytitle('listname')/items	POST	Voir les exemples

Crée une liste exemple de données :

{
  "__metadata": {
    "type": "SP.List"
  },
  "AllowContentTypes": true,
  "BaseTemplate": 104 ,
  "ContentTypesEnabled": true,
  "Description": "My list description ",
  "Title": "RestTest "
}

Ajoute un élément dans une liste exemple de données :

{
  "__metadata": {
    "type": "SP.Data.listname.ListItem"
  },
  "Title": "MyItem"
}

Dans la fonction JSON ci-dessus, remplacez ListName par le nom de votre liste SharePoint en omettant les espaces.

Prise en charge du traitement par lots

Le service REST SharePoint Online (et SharePoint sur site 2016 et ultérieur) prend en charge la combinaison de plusieurs requêtes en un seul appel au service à l’aide de l’option de requête $batch OData. Pour obtenir plus d’informations et des liens vers des exemples de code, consultez la rubrique Créer des requêtes de lots avec l’API REST.

Ressources OData

• Développement d’applications orientées services avec WCF
• Open Data Protocol
• Conventions pour les URI de protocole OData
• Opérations de service d’adressage
• Opérations de protocole OData
• Erreurs

Ressources service REST SharePoint

Pour en savoir plus sur l’utilisation du service REST SharePoint, utilisez les ressources ci-dessous.

Titre	Description
Effectuer des opérations de base à l’aide de terminaux REST SharePoint	Effectuer des opérations CRUD (create, read, update et delete) de base à l’aide de l’interface REST Sharepoint.
Utilisation d’une liste et de ses éléments avec REST	Effectuer des opérations CRUD (create, read, update et delete) de base sur les listes et les éléments de liste à l’aide de l’interface REST SharePoint.
Utilisation des dossiers et des fichiers avec REST	Effectuer des opérations CRUD (create, read, update et delete) de base sur les dossiers et les fichiers à l’aide de l’interface REST SharePoint.
Naviguer dans la structure de données SharePoint représentée dans le service REST	Démarrer à partir d’un point de terminaison REST pour un élément SharePoint donné et accéder aux éléments connexes, tels que les sites parents ou la structure de la bibliothèque dans laquelle cet élément réside.
Déterminer les URI de point de terminaison du service REST SharePoint	Consignes générales pour la détermination des URI de point de terminaison REST SharePoint à partir de la signature des API de modèle objet client correspondantes.
Utiliser les opérations de requête OData dans les demandes REST SharePoint	Utiliser une large gamme d’opérateurs de chaîne de requête OData pour sélectionner, filtrer et trier les données que vous demandez à partir du service REST SharePoint.
Créer des requêtes de lots avec l’API REST	Combiner plusieurs requêtes dans un seul appel au service REST.
Synchroniser les éléments SharePoint à l’aide du service REST	Synchroniser des éléments entre SharePoint et vos compléments ou services à l’aide de la ressource GetListItemChangesSinceToken, qui est intégrée au service REST SharePoint.
Charger un fichier à l’aide de l’API REST et de jQuery	Les exemples de code fournis dans cet article utilisent l’interface REST et les demandes AJAX de jQuery pour ajouter un fichier local à la bibliothèque Documents, puis modifier les propriétés de l’élément de liste qui représente le fichier chargé.
Définir des autorisations personnalisées sur une liste à l’aide de l’interface REST	Les sites SharePoint, les listes et les éléments de liste sont des types d’objet SecurableObject, qui héritent des autorisations de leurs parents. Pour définir des autorisations personnalisées pour un objet, vous devez briser sa relation d’héritage afin qu’il n’hérite plus des autorisations de son parent, puis définir de nouvelles autorisations en ajoutant ou en supprimant des attributions de rôle.
Principes de base du flux de travail SharePoint	Ajoutez une fonctionnalité de recherche aux applications clientes et mobiles à l’aide du service REST de recherche dans SharePoint Server 2013 et toute technologie prenant en charge les requêtes web REST.
Référence de l’API REST des flux sociaux pour SharePoint	Points de terminaison REST SharePoint pour les tâches liées au flux.
Référence de l’API REST de suivi des personnes et du contenu pour SharePoint	Points de terminaison REST SharePoint pour le suivi des personnes et du contenu.
Développer des compléments pour SharePoint	Recherchez des articles et des ressources approfondies pour vous aider à créer des fonctionnalités avancées dans vos compléments SharePoint.