Partager via


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 :

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

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

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 :

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

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.