Effectuer des opérations de base à l’aide de terminaux REST SharePoint

Vous pouvez effectuer des opérations CRUD (create, read, update et delete ; créer, lire, mettre à jour et supprimer) de base à l’aide de l’interface REST (Representational State Transfer) fournie par SharePoint. L’interface REST expose toutes les entités et les opérations SharePoint qui sont disponibles dans les autres API de client SharePoint. L’un des avantages de REST est que vous n’avez pas à ajouter de références à des assemblys de client ou des bibliothèques SharePoint. Vous envoyez des requêtes HTTP aux points de terminaison appropriés afin de récupérer ou de mettre à jour des entités SharePoint, telles que les sites web, les listes et les éléments de liste.

Pour lire une présentation de l’interface REST SharePoint et de son architecture, consultez la rubrique Découverte du service REST SharePoint.

Pour savoir comment utiliser les entités principales de SharePoint, consultez les articles Utilisation d’une liste et de ses éléments avec REST et Utilisation des dossiers et des fichiers avec REST.

Pour obtenir un exemple qui vous montre comment effectuer un grand nombre de ces opérations dans le contexte d’une application web ASP.NET écrite en C#, consultez l’article SharePoint-Add-in-REST-OData-BasicDataOperations.

Pour plus d’informations sur les ensembles d’API disponibles sur la plateforme SharePoint, reportez-vous à Choisir l’ensemble d’API approprié dans SharePoint.

Pour plus d’informations sur l’utilisation des autres API clientes, reportez-vous aux articles suivants :

• Effectuer des opérations de base avec du code de bibliothèque JavaScript dans SharePoint- Effectuer des opérations de base avec du code de bibliothèque client dans SharePoint
• Créer des applications Windows Phone accédant à SharePoint

Opérations HTTP dans les services REST SharePoint

Les points de terminaison du service REST SharePoint correspondent aux types et aux membres dans les modèles objet client SharePoint. En utilisant des requêtes HTTP, vous pouvez utiliser ces points de terminaison REST pour effectuer des opérations CRUD (Create, Read, Update et Delete ; créer, lire, mettre à jour et supprimer) classiques sur des entités SharePoint comme des listes et des sites.

En général, les points de terminaison qui représentent des opérations Read correspondent à des commandes HTTP GET, les points de terminaison qui représentent des opérations de création correspondent à des commandes HTTP POST, et ceux qui représentent des opérations de mise à jour ou d’insertion correspondent à des commandes HTTP PUT.

Dans SharePoint, les commandes POST permettent de créer des entités, telles que des listes et des sites. Le service REST SharePoint prend en charge l'envoi de commandes POST incluant des définitions d'objet à des points de terminaison représentant des collections. Par exemple, vous pouvez envoyer une commande POST incluant une nouvelle définition d'objet de liste au format ATOM à l'URL suivante pour créer une liste SharePoint :

http://<site url>/_api/web/lists

Pour les opérations POST, toutes les propriétés qui ne sont pas obligatoires sont définies sur leur valeur 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.

Les opérations PUT et MERGE permettent de mettre à jour des objets SharePoint existants. Les points de terminaison de service qui représentent une opération set sur une propriété d'objet prennent en charge à la fois les demandes PUT et MERGE. Pour les demandes MERGE, la définition des propriétés est facultative ; toute propriété que vous ne définissez pas de manière explicite conserve sa valeur actuelle. Cependant, pour les commandes PUT, toutes les propriétés que vous ne définissez pas de manière explicite sont configurées sur leur valeur par défaut. De plus, si vous ne spécifiez pas toutes les propriétés obligatoires pour les mises à jour d'objet lors de l'utilisation des commandes HTTP PUT, le service REST renvoie une exception.

Utilisez la commande HTTP DELETE sur l'URL d'un point de terminaison spécifique pour supprimer l'objet SharePoint représenté par ce point de terminaison. Dans le cas des objets recyclables, tels que les listes, les fichiers et les éléments de liste, une opération Recycle est réalisée.

Lecture de données à l’aide de l’interface REST SharePoint

Pour utiliser les fonctionnalités REST intégrées dans SharePoint, vous devez construire une demande HTTP REST, à l'aide de la norme OData, qui correspond à l'API du modèle d'objet client à utiliser. Chaque entité SharePoint est exposée à un point de terminaison sur le site SharePoint que vous ciblez, et ses métadonnées sont représentées au format XML ou JSON. Vous pouvez effectuer les demandes HTTP dans n'importe quel langage, notamment JavaScript et C#.

Pour lire les informations d’un point de terminaison REST, vous devez en connaître l’URL, ainsi que la représentation OData de l’entité SharePoint qui est exposée au niveau de ce point de terminaison. Par exemple pour récupérer toutes les listes d’un site SharePoint spécifique, vous devez envoyer une requête GET à http://<site url>/_api/web/lists. Vous pouvez accéder à cette URL dans le navigateur et voir le code XML qui est renvoyé. Lorsque vous créez la requête dans le code, vous pouvez spécifier si vous souhaitez recevoir la représentation OData des listes au format XML ou JSON.

Le code C# suivant montre comment définir cette requête GET qui renvoie une représentation JSON de toutes les listes d’un site à l’aide de JQuery. Il suppose également qu’un jeton d’accès OAuth valide est stocké dans la variable accessToken. Si vous effectuez cet appel à partir d’un site web de complément, vous n’avez pas besoin du jeton d’accès comme ce serait le cas avec un complément hébergé dans SharePoint. Notez que vous ne pouvez pas obtenir de jeton d’accès à partir de code exécuté sur un client de navigateur. Vous devez obtenir le jeton d’accès avec du code exécuté sur un serveur.

Pour savoir comment obtenir un jeton d’accès, consultez les articles Flux OAuth avec jetons de contexte pour les compléments SharePoint et Flux OAuth avec code d’autorisation pour les compléments SharePoint.

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

Cette requête est un peu différente si vous écrivez votre complément en JavaScript tout en utilisant la bibliothèque inter-domaines SharePoint. Dans ce cas, vous n’avez pas besoin de fournir de jeton d’accès.

Le code suivant montre ce à quoi cette requête ressemblerait si vous utilisiez la bibliothèque inter-domaines et que vous souhaitiez recevoir la représentation OData des listes au format XML au lieu de JSON. (Atom étant le format de réponse par défaut, vous n’avez pas besoin d’inclure un en-tête Accept.) Pour plus d’informations sur l’utilisation de la bibliothèque inter-domaines, reportez-vous à Accéder à des données SharePoint à partir de compléments à l’aide de la bibliothèque inter-domaines.

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
  {
    url: appweburl +
          "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
          hostweburl + "'",
    method: "GET",
    success: successHandler,
    error: errorHandler
  }
);

Le code de l’exemple suivant vous montre comment demander une représentation JSON de toutes les listes d’un site en utilisant le langage C#. Il part du principe que vous avez un jeton d’accès OAuth que vous stockez dans la variable accessToken.

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Obtention des propriétés qui ne sont pas renvoyées avec la ressource

De nombreuses valeurs de propriété sont retournées lorsque vous récupérez une ressource, mais pour certaines propriétés, vous devez envoyer une requête GET directement au point de terminaison de propriété. Il s’agit typique des propriétés qui représentent des entités SharePoint.

L'exemple suivant montre comment obtenir une propriété en ajoutant le nom de la propriété au point de terminaison de la ressource. L'exemple obtient la valeur de la propriété Author d'une ressource File

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/author

Pour obtenir les résultats au format JSON, ajoutez un en-tête Accept défini sur "application/json;odata=verbose".

Écrire des données à l’aide de l’interface REST

Vous pouvez créer et mettre à jour des entités SharePoint en construisant des demandes HTTP REST pour les points de terminaison adéquats, comme vous le feriez lors de la lecture de données. Dans ce cas, vous utilisez toutefois une demande POST. Lorsque vous mettez à jour des entités, vous passez également une méthode PUT ou MERGE de demande HTTP en ajoutant un de ces termes aux en-têtes de votre demande comme valeur de la clé X-HTTP-Method. La méthode MERGE met uniquement à jour les propriétés de l'entité spécifiée, alors que la méthode PUT remplace l'entité existante par une nouvelle que vous fournissez dans le corps de la méthode POST. Utilisez la méthode DELETE pour supprimer l'entité. Lorsque vous créez ou mettez à jour une entité, vous devez fournir une représentation OData de l'entité à créer ou modifier dans le corps de la demande HTTP.

Lors de la création, de la mise à jour et de la suppression d'entités SharePoint, il est important de prendre en compte le fait que si vous n'utilisez pas OAuth pour autoriser vos demandes, ces opérations requièrent la transmission de la valeur de chiffrement de la demande du serveur comme valeur d'en-tête X-RequestDigest. Vous pouvez récupérer cette valeur en envoyant une demande POST avec un corps vide à http://<site url>/_api/contextinfo, puis en extrayant la valeur du nœud d:FormDigestValue dans le code XML que renvoie le point de terminaison contextinfo. L'exemple ci-après illustre l'envoi d'une demande HTTP au point de terminaison contextinfo en C#.

HttpWebRequest endpointRequest =(HttpWebRequest)HttpWebRequest.Create(
                                    "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Si vous utilisez le processus d’authentification et d’autorisation décrit dans Autorisation et authentification des compléments SharePoint, vous n’avez pas besoin d’inclure le digest de demande dans vos requêtes.

Si vous utilisez la bibliothèque inter-domaines JavaScript, SP.RequestExecutor gère pour vous la réception et l’envoi de la valeur de chiffrement de formulaire.

Si vous créez un complément SharePoint hébergé sur SharePoint, vous n’avez pas à créer de requête HTTP distincte pour récupérer la valeur de chiffrement de formulaire. Vous pouvez récupérer la valeur dans le code JavaScript à partir d’une page SharePoint (si la page utilise la page maître par défaut), comme illustré dans l’exemple suivant, qui utilise JQuery et crée une liste.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: {
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

L'exemple ci-dessous montre comment mettre à jour la liste créée dans l'exemple précédent. L'exemple change le titre de la liste, utilise JQuery et suppose que vous effectuez cette opération dans un complément hébergé sur SharePoint.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: {
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

La valeur de la clé IF-MATCH dans les en-têtes de demande est l’endroit où vous spécifiez la valeur etag d’une liste ou d’un élément de liste. Cette valeur particulière s’applique uniquement aux listes et éléments de liste, et est destinée à éviter des problèmes de concurrence lorsque vous mettez à jour ces entités. L’exemple précédent utilise un astérisque (*) pour cette valeur et vous pouvez utiliser cette valeur quand vous n’avez aucune raison de vous soucier de problèmes de concurrence. Dans le cas contraire, vous devez obtenir la valeur etag, une liste ou un élément de liste en exécutant une requête GET qui récupère l’entité. Les en-têtes de la réponse HTTP obtenue transmettent la valeur etag comme valeur de la clé ETag. Cette valeur est également incluse dans les métadonnées des entités.

L’exemple suivant présente la balise <entry> ouvrante du nœud XML qui contient les données de liste. La propriété m:etag contient la valeur etag.

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

Création d’un site à l’aide d’une requête REST

L’exemple suivant montre comment créer un site en JavaScript.

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: {
        "accept": "application/json; odata=verbose",
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    success: doSuccess,
    error: doError
});

Différences des requêtes REST en fonction de l’environnement

La création et l'envoi d'une requête HTTP peuvent varier en fonction de la langue, de la bibliothèque et du type de complément, de sorte que vous devez souvent modifier un ou plusieurs composants de requête lorsque vous traduisez une requête d'un environnement à un autre. Par exemple, les requêtes jQuery AJAX utilisent les paramètres data et type pour spécifier le corps et le type de la requête, mais les requêtes de bibliothèque inter-domaines utilisent les paramètres body et method pour spécifier ces valeurs.

Les sections suivantes décrivent les autres différences courantes entre les environnements.

Le mode de réception et d’envoi de la valeur de chiffrement de formulaire dépend du complément.

Lorsque vous envoyez une demande POST, celle-ci doit inclure la valeur de condensé de formulaire dans l'en-tête X-RequestDigest. Cependant, la façon dont vous obtenez et envoyez la valeur diffère selon le complément :

• Dans les compléments hébergés par SharePoint, vous pouvez envoyer uniquement l’en-tête suivant :

  "X-RequestDigest": $("#__REQUESTDIGEST").val()

• Les compléments hébergés dans le cloud qui utilisent OAuth récupèrent d'abord la valeur de condensé de formulaire en envoyant une demande au point de terminaison contextinfo, puis l'ajoutent aux demandes, comme indiqué dans Écrire des données à l'aide de l'interface REST.

• Dans les compléments hébergés dans le cloud qui utilisent la bibliothèque inter-domaines JavaScript, vous n'avez pas besoin de préciser la valeur de condensé de formulaire. Par défaut, SP.RequestExecutor gère ceci automatiquement. (Il gère également la valeur de longueur du contenu.)

Les compléments qui utilisent OAuth doivent transmettre des jetons d’accès dans les requêtes

Les compléments hébergés dans le cloud utilisent OAuth ou la bibliothèque inter-domaines pour autoriser l’accès aux données de SharePoint. Les composants de compléments comportant du code qui s’exécute sur un serveur web distant doivent utiliser OAuth pour autoriser l’accès aux données de SharePoint. Dans ce cas, vous devez inclure un en-tête Authorization pour envoyer le jeton d’accès. Pour obtenir un exemple qui ajoute un en-tête d’autorisation à un objet HTTPWebRequest, reportez-vous à Lecture de données à l’aide de l’interface REST SharePoint.

Pour en savoir plus sur les jetons d’accès OAuth et comment les obtenir, voir Flux OAuth avec jetons de contexte pour les compléments SharePoint et Flux OAuth avec code d’autorisation pour les compléments SharePoint.

Dans les requêtes inter-domaines, les URI de point de terminaison utilisent SP.AppContextSite pour modifier le contexte

Les demandes sont envoyées au point de terminaison de ressource spécifié dans la propriété url de la requête. Les URI de point de terminaison utilisent le format suivant :

<site url>/_api/<context>/<resource> (exemple, https://contoso.com/_api/web/lists)

Les requêtes de bibliothèque inter-domaines utilisent ce format lorsqu'elles accèdent à des données sur le site web de complément ; celui-ci correspond au contexte par défaut pour les requêtes de bibliothèque inter-domaines. Cependant, pour accéder aux données sur le site web hôte ou sur une autre collection de sites, les requêtes doivent initialiser le site web hôte ou une autre collection de sites en tant que contexte. Pour ce faire, elles utilisent le point de terminaison SP.AppContextSite dans l'URI, comme indiqué dans le tableau 1. Les exemples d'URI dans le tableau 1 utilisent l'alias @target pour envoyer l'URL cible dans la chaîne de requête, car l'URL contient un caractère spécial (« : »).

Tableau 1. Utilisation du point de terminaison SP.AppContextSite pour modifier le contexte de la requête

Les compléments SharePoint peuvent obtenir l’URL du site web de complément et celle du site web hôte à partir de la chaîne de requête de la page de complément, comme montré dans l’exemple de code suivant. L’exemple montre également comment indiquer la bibliothèque inter-domaines, qui est définie dans le fichier SP.RequestExecutor.js sur le site web hôte. L’exemple suppose que votre complément se lance à partir de SharePoint. Pour obtenir des instructions sur la configuration de votre contexte SharePoint lorsque votre complément n’est pas lancé à partir de SharePoint, reportez-vous à Flux OAuth avec code d’autorisation pour les compléments SharePoint.

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

Propriétés utilisées dans les requêtes REST

Le tableau 2 montre les propriétés couramment utilisées dans les requêtes HTTP pour le service REST SharePoint.

Tableau 2. Utilisation des propriétés de requête REST dans les requêtes HTTP

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.

Voir aussi

• Découverte du service REST SharePoint
• Accès aux données sécurisé et modèles d’objet client pour les compléments SharePoint
• Utiliser des données externes dans SharePoint
• Ressources OData
• Définir des autorisations personnalisées sur une liste à l’aide de l’interface REST
• Développer des compléments pour SharePoint