SharePoint 2013

Article
2015-09-30

Comprendre et utiliser l'interface REST de SharePoint 2013

SharePoint 2013 offre une interface Representational State Transfer (REST) qui ouvre la plateforme de développement SharePoint 2013 aux langages et technologies Web standard. Les capacités de SharePoint sont disponibles depuis longtemps pour les applications Web via le modèle objet client, mais ces API ne sont disponibles que pour les langages et applications .NET. L'interface complète REST dans SharePoint 2013 rend l'accès possible à la plupart des fonctionnalités et entités SharePoint avec les langages Web standard tels que JavaScript ou PHP, et n'importe quel langage ou pile technologique prenant en charge REST.

Par ailleurs, comme l'interface REST ne nécessite pas de référencer les assemblys clients, cela vous permet de limiter le volume de vos applications Web, ce qui est un point particulièrement important dans le cadre d'applications mobiles. REST présente des avantages évidents pour les applications mobiles écrites pour des plateformes autres que Microsoft, telles que les périphériques iOS et Android, mais c'est aussi une ressource utile pour les développeurs d'applications Windows 8. Une application Windows 8 écrite en HTML5 et JavaScript nécessiterait l'interface REST pour toute opération SharePoint, et les développeurs C# pour qui la taille de leurs applications est importante devraient aussi envisager d'utiliser REST. Cet article va démontrer comment utiliser cette interface pour incorporer la puissance de la plateforme SharePoint à vos applications et effectuer des opérations avancées avec les entités SharePoint.

Principes fondamentaux

Avant de pouvoir faire quoi que ce soit avec SharePoint, votre application Web distante ou mobile doit obtenir une autorisation d'accès. Dans SharePoint 2013, il existe deux approches générales permettant d'autoriser l'accès à un site SharePoint (que vous utilisiez REST ou non). La première implique l'authentification d'un utilisateur SharePoint et dans ce cas votre application bénéficie du même accès aux données et fonctionnalités SharePoint que l'utilisateur. Les différentes façons vous permettant d'authentifier un utilisateur à partir d'une application mobile ou Web dépassent le cadre de cet article. Toutefois, nous allons mentionner deux nouvelles options dans SharePoint 2013 car elles ont un impact sur la manière de construire vos requêtes REST :

Si vous effectuez un appel dans SharePoint à partir d'une application hébergée à distance qui ne peut pas utiliser de code côté client (HTML et JavaScript) de manière exclusive, et qu'il n'y pas de pare-feu entre SharePoint et votre application, vous pouvez utiliser des jetons OAuth 2.0 avec le service de contrôle d'accès Microsoft (ACS) comme serveur de jeton sécurisé.
Si le code côté client et les permissions d'un utilisateur qui s'est connecté à SharePoint sont suffisants, la bibliothèque JavaScript inter-domaines (bit.ly/12kFwSP) représente alors une bonne alternative à OAuth. La bibliothèque inter-domaines est aussi une alternative pratique à OAuth chaque fois que vous effectuez des appels distants à travers un pare-feu. L'article de la bibliothèque MSDN « Options d'accès aux données dans SharePoint 2013 » (bit.ly/WGvt9L) décrit ces options en détail.

Utilisation d'OAuth L'article de la bibliothèque MSDN « Autorisation et authentification des apps dans SharePoint 2013 » (bit.ly/XAyv28) explique en détail le fonctionnement d'OAuth dans SharePoint 2013 et la procédure permettant d'obtenir un jeton d'accès pour votre application. Une fois que vous avez un jeton, vous devez le transmettre avec chaque requête REST. Vous effectuez cette opération en ajoutant un en-tête Authorization qui transmet le jeton d'accès comme étant sa valeur, précédé de « Bearer » :

Authorization: Bearer access_token

Vous trouverez des exemples de code C# et JavaScript qui effectuent ce type d'opérations dans la section « Lire des données à l'aide de l'interface REST SharePoint 2013 » de l'article de la bibliothèque MSDN « Procédure : effectuer des opérations de base à l'aide de terminaux REST SharePoint 2013 » (bit.ly/13fjqFn). Cet exemple, qui récupère toutes les listes d'un site SharePoint, vous montre à quoi ressemble une requête REST de base qui passe un jeton OAuth :

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http:// <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();

Utilisation de la bibliothèque JavaScript inter-domaines La bibliothèque inter-domaines SharePoint est contenue dans le fichier SP.RequestExecutor.js, situé dans le répertoire /_layouts/15/ virtuel sur des serveurs SharePoint. Pour l'utiliser, chargez ce fichier sur une page Web distante. En JavaScript, créez un objet SP.RequestExecutor et appelez sa méthode executeAsync method. En paramètre de cette méthode, vous transmettez les informations dont elle a besoin pour construire une requête HTTP vers le service REST. Les principales différences entre des appels REST utilisant OAuth et des appels REST utilisant la bibliothèque inter-domaines résident dans le fait que pour les derniers, vous n'avez pas besoin de transmettre un jeton d'accès dans la requête, mais vous devez spécifier (dans l'URL RESTful) le site Web SharePoint qui servira de site de contexte client. L'article de la bibliothèque MSDN « Procédure : accès à des données SharePoint 2013 à partir d'applications distantes à l'aide de la bibliothèque inter-domaines » (bit.ly/12kFwSP) traite de ces détails (et notamment de la différence entre un Web d'application et un Web hôte) de manière plus approfondie. Cet exemple, qui récupère toutes les listes d'un site SharePoint, vous montre à quoi ressemble une requête REST utilisant 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",
  headers: { "Accept": "application/json; odata=verbose" },
  success: successHandler,
    error: errorHandler
    }
      );

Construction d'URL RESTful Le service REST de SharePoint est implémenté dans un fichier client.svc dans le dossier virtuel /_vti_bin sur le site Web SharePoint. Cela dit, SharePoint 2013 prend en charge l'abréviation « _api » comme substitut de « _vti_bin/client.svc ». C'est l'URL de base de chaque point de terminaison :

http://<domain>/<site url>/_api/

Les URL relatives au service de points de terminaison spécifiques sont ajoutées à cette base. Par exemple, vous pouvez récupérer les listes d'un site SharePoint à l'aide de cette URL :

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

Vous pouvez obtenir une référence à une liste en particulier en spécifiant son ID ou, comme dans l'exemple suivant, son titre :

_api/web/lists/getByTitle('samplelist')/

Le « web » dans ces exemples n'est pas un espace réservé : il s'agit du nom d'un objet de la classe Web dans le modèle objet client SharePoint. « lists » est le nom d'une propriété de collection et « getByTitle » est une méthode de cet objet de collection. Ce paradigme permet à Microsoft de combiner la référence de l'API pour les points de terminaison au modèle objet JavaScript. Vous trouverez des exemples en consultant respectivement SP.Web.lists et SP.ListCollection.getByTitle aux adresses bit.ly/14a38wZ et bit.ly/WNtRMO. En outre, la syntaxe reflète approximativement la structure d'une location SharePoint. Vous obtenez des informations sur une collection de sites avec _api/site, des informations sur un site Web SharePoint avec _api/web et des informations sur toutes les listes dans un site Web avec _api/web/lists. La dernière URL fournit une collection de listes qui comprend toutes les listes sur le site SharePoint. Vous pouvez également regarder comment ces objets sont représentés en XML en naviguant jusqu'à ces URL sur votre collection de sites de développement.

Chaque classe principale du modèle objet de contenu SharePoint est disponible, dont la collection de sites, les sites Web, les listes, les dossiers, les champs et les éléments de liste. Vous pouvez obtenir des informations sur les utilisateurs à l'aide des classes SP.User (bit.ly/15M4fzo), SP.UserCollection (bit.ly/16TQTnW), SP.Group (bit.ly/X55Pga) et SP.GroupCollection (bit.ly/ZnFHbG). Le tableau de la figure 1 présente des exemples de différents points de terminaison pour les opérations de lecture.

Figure 1 Points de terminaison pour les opérations de lecture

URL	Retourne
_api/web/title	Le titre du site actuel
_api/web/lists(guid'<list id>')	Une liste
_api/web/lists/getByTitle('Announcements')/fields	Les colonnes de la liste d'annonces
_api/web/lists/getByTitle('Task')/items	Les éléments de la liste des tâches
_api/web/siteusers	Les utilisateurs du site
_api/web/sitegroups	Les groupes d'utilisateurs du site
_api/web/sitegroups(3)/users	Les utilisateurs du groupe 3
_api/web/GetFolderByServerRelativeUrl('/Shared Documents')	Le dossier racine de la bibliothèque Documents partagés
_api/web/GetFolderByServerRelativeUrl('/Plans')/Files('a.txt')/$value	Le fichier a.txt de la bibliothèque des planifications

Par défaut, les données sont renvoyées en XML au format AtomPub étendu par le format OData, mais vous pouvez récupérer les données au format JSON en ajoutant l'en-tête accept à la requête HTTP :

accept: application/json;odata=verbose

L'utilisation de JSON ou d'Atom (XML) dépend de vos compétences, de la plateforme de programmation que vous utilisez et de savoir si la latence du réseau sera un problème pour votre application. Étant donné que JSON utilise beaucoup moins de caractères, c'est un point à considérer car les charges utiles seront réduites sur le réseau. D'un autre côté, la plupart des plateformes principales, dont Microsoft .NET Framework, disposent de bibliothèques d'analyse XML riches.

Nous décrirons plus tard comment vous pouvez utiliser des opérateurs de requête OData pour sélectionner, filtrer et ordonner les données.

Écriture dans SharePoint Toutes les requêtes précédentes utilisent le verbe HTTP GET. Lorsque vous écrivez dans SharePoint, vos requêtes utilisent le verbe POST, bien qu'en certains cas vous l'écraserez en ajoutant un en-tête X-HTTP-Method à la requête et en spécifiant une valeur PUT, MERGE ou DELETE. En général, POST est utilisé lorsque vous créez un objet, par exemple un site, une liste ou un élément de liste. MERGE est utilisé lorsque vous mettez à jour certaines propriétés d'un objet et que vous voulez que les autres propriétés conservent leurs valeurs actuelles. PUT est utilisé lorsque vous voulez remplacer un élément. Des propriétés qui ne sont pas spécifiquement mentionnées dans la requête sont définies sur leurs valeurs par défaut. DELETE est utilisé lorsque vous souhaitez supprimer une élément.

Chaque requête qui écrit dans SharePoint doit inclure un chiffrement de formulaire. Votre code obtient le chiffrement en tant qu'élément d'un ensemble d'informations renvoyé par le point de terminaison suivant :

_api/contextinfo

Vous devez utiliser le verbe POST dans cette requête (avec un corps vide) et inclure l'en-tête Authorization comme décrit plus haut. Dans certaines infrastructures, vous devrez spécifier que la longueur de la requête POST est 0. Dans la structure renvoyée, une propriété nommée FormDigestValue contient le chiffrement de formulaire. Dans toutes les requêtes POST suivantes, vous ajoutez un en-tête X-RequestDigest et utilisez le chiffrement pour définir sa valeur.

Notez que si vous travaillez avec une application hébergée par SharePoint et une page qui utilise la page maître par défaut pour SharePoint, le chiffrement figure déjà sur la page dans un élément ayant pour ID « __REQUESTDIGEST » (avec deux caractères de soulignement). Ainsi, au lieu d'appeler le point de terminaison contextinfo, vous pouvez simplement lire la valeur à l'aide d'un script, par exemple avec ce code jQuery :

var formDigestValue = $("__REQUESTDIGEST").val()

Évidemment, vous devez ajouter au corps de la requête les données que vous voulez écrire ou une identification des données que vous voulez supprimer. Vous pouvez utiliser soit le format AtomPub/OData, soit le format JSON. Si vous décidez d'utiliser ce dernier, vous devez ajouter un en-tête content-type à la requête comme suit :

content-type: application/json;odata=verbose

Pour consulter un ensemble complet d'exemples d'opérations CRUD de création, lecture, mise à jour et suppression sur les objets SharePoint, reportez-vous à l'article « Procédure : effectuer des opérations de base à l'aide de terminaux REST SharePoint 2013 » à l'adresse bit.ly/13fjqFn.

Opérations avancées

La puissance de l'interface REST de SharePoint 2013 entraîne un certain degré de complexité. L'interface prend en charge des opérations de tri, de filtrage et d'organisation des données qu'elle renvoie. Elle prend aussi en charge un grand nombre d'opérations propres à SharePoint. Ces capacités supplémentaires ajoutent des fonctionnalités et des avantages que vous ne rencontrez que rarement dans une implémentation REST standard. Certains des facteurs parmi les plus importants que vous rencontrerez en travaillant avec REST et SharePoint sont abordés dans les sections suivantes.

Filtrage, sélection et tri Vous pouvez utiliser les options de requête du système OData pour contrôler le type de données qui est renvoyé et la manière dont il est trié. La figure 2 présente les options prises en charge.

Figure 2 Options de filtrage et de tri des données

Option	Objectif
$select	Spécifie les champs à inclure dans les données renvoyées.
$filter	Spécifie les membres d'une collection, par exemple les éléments d'une liste, qui sont renvoyés.
$expand	Spécifie les champs projetés provenant d'une liste jointe qui sont renvoyés.
$top	Renvoie uniquement les n premiers éléments d'une collection ou liste.
$skip	Ignore uniquement les n premiers éléments d'une collection ou liste et renvoie le reste.
$orderby	Spécifie le champ utilisé pour trier les données avant qu'elles ne soient renvoyées.

Par exemple, pour renvoyer l'auteur, le titre et l'ISBN d'une liste appelée Books, vous utiliseriez ceci :

_api/web/lists/getByTitle('Books')/items?$select=Author,Title,ISBN

Si l'option $select n'est pas utilisée, tous les champs sont renvoyés à l'exception de ceux qui nécessiteraient de nombreuses ressources pour que le serveur les renvoie. Si vous avez besoin de ces champs, vous devez utiliser l'option $select et les spécifier en les nommant. Pour obtenir tous les champs, utilisez $select=‘*’.

Pour obtenir tous les livres écrits par Mark Twain, utilisez :

_api/web/lists/getByTitle('Books')/items?$filter=Author eq 'Mark Twain'

Pour consulter une liste de tous les opérateurs pris en charge par l'option $filter, reportez-vous à l'article de la bibliothèque MSDN « Programmation à l'aide du service REST SharePoint 2013 » à l'adresse bit.ly/Zlqf3e.

Pour trier les livres par titre selon un ordre croissant, utilisez :

_api/web/lists/getByTitle('Books')/items?$orderby=Title asc

Utilisez « desc » au lieu de « asc » pour spécifier un ordre décroissant. Pour trier par champs multiples, spécifiez une liste de champs séparés par des virgules.

Vous pouvez unir plusieurs options à l'aide de l'opérateur « & ». Pour obtenir uniquement le titre des deux premiers livres de Mark Twain, utilisez :

_api/web/lists/getByTitle(
  'Books')/items?$select=Title&$filter=Author eq 'Mark Twain'&$top=2

Le service résoudra complètement chaque option avant d'appliquer la suivante. Par conséquent, chaque option s'applique au jeu de données produit par les options situées à sa gauche dans l'URL. Il en découle que l'ordre dans lequel vous appliquez les options est important. Par exemple, l'URL suivante renvoie les éléments 3-10 :

_api/web/lists/getByTitle('Books')/items?$top=10&$skip=2

Mais, en inversant les deux options, elle renvoie les éléments 3-12 :

_api/web/lists/getByTitle('Books')/items?$skip=2&$top=10

Vous pouvez obtenir les n éléments du bas à l'aide d'une option décroissante $orderby et $top (dans cet ordre). L'URL suivante renvoie les deux éléments du bas :

_api/web/lists/getByTitle('Books')/items?$orderby=ID desc&$top=2

Lorsqu'une liste SharePoint possède un champ de recherche vers une autre liste, cela établit une jointure efficace entre les deux. Vous pouvez utiliser l'option $expand pour renvoyer les champs projetés provenant de la liste jointe. Par exemple, si la liste Books possède une champ PublishedBy qui recherche le champ Name dans une liste Publisher, l'URL suivante permet de renvoyer ces noms :

_api/web/lists/getByTitle(
  'Books')/items?$select=Title,PublishedBy/Name&$expand=PublishedBy

Remarquez que vous référencez la colonne de la liste étrangère en utilisant la syntaxe lookup_column_display_name/foreign_column_name, et non foreign_list_name/foreign_column_name. Il est important de remarquer également que vous ne pouvez pas sélectionner de nom de champ de recherche sans le développer.

Utilisation de fichiers et de dossiers La meilleure manière d'accéder à une bibliothèque de documents est de mettre à profit la méthode GetFolderByServerRelativeUrl disponible dans /_api/web. Lorsque vous ajoutez un fichier dans une bibliothèque de documents, vous envoyez le contenu de votre fichier dans le corps de la demande et vous fournissez le nom du fichier dans l'URL :

http://<site url>/_api/web/GetFolderByServerRelativeUrl(
  '/Shared Documents')/Files/add(url='a.txt',overwrite=true)

Point important : lors de la mise à jour de fichiers, vous ne pouvez utiliser que la méthode HTTP PUT. Vous ne pouvez donc pas fusionner le contenu d'un fichier avec un autre fichier déjà stocké dans une bibliothèque de documents. Au lieu de cela, vous devez remplacer une version de fichier par une autre. Vous devez aussi veiller à utiliser l'opérateur $value dans votre URL afin d'avoir accès au contenu du fichier proprement dit, au lieu des métadonnées associées au fichier :

http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/$value

Dans SharePoint, il est recommandé d'extraire les fichiers avant de les modifier. Par conséquent, vous devez extraire un fichier avant de le mettre à jour, puis le réarchiver quand vous avez fini. Les opérations suivantes nécessitent que vous effectuiez des requêtes POST sur ces URL, avec des corps de demande vides :

http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/CheckOut()
http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/CheckIn(comment='Comment', checkintype=0)

La méthode CheckIn requiert deux paramètres. Le paramètre de commentaire vous permet d'ajouter un commentaire à l'archivage et le paramètre checkintype spécifie s'il s'agit d'un archivage mineur (0) ou majeur (1).

Un dernier point important, si vous utilisez du code (JavaScript par exemple) qui s'exécute dans votre client navigateur et que vous voulez télécharger un fichier supérieur à 1,5 Mo, REST est votre unique option. Ce type d'opérations impliquant des fichiers importants (supérieurs à 1,5 Mo) n'est disponible que sur Internet Explorer 10 (et versions ultérieures) et autres navigateurs modernes de millésime comparable. L'exemple de code de la figure 3 vous montre comment télécharger un fichier binaire à l'aide de la bibliothèque inter-domaines.

Figure 3 Téléchargement d'un fichier binaire à l'aide de la bibliothèque inter-domaines

function uploadFileBinary() {
  var executor = new SP.RequestExecutor(appweburl);
  var body = "";
  for (var i = 0; i < 1000; i++) {
    var ch = i % 256;
    body = body + String.fromCharCode(ch);
  }
  var info = {
    url: "_api/web/lists/getByTitle('Shared Documents')/RootFolder/Files/Add(url='a.dat', overwrite=true)",  
    method: "POST",
    binaryStringRequestBody: true,  
    body: body,  
    success: success,  
    error: fail,  
    state: "Update"};
   executor.executeAsync(info);
}

Modification des requêtes Jusqu'ici, nous avons décrit le mode de fonctionnement de REST avec les entités SharePoint accessibles à l'aide d'URL imitant la structure d'un site SharePoint. Cependant, certains types SharePoint ne sont pas accessibles ou représentés de cette manière. Dans le cadre de REST, les types ChangeQuery, ChangeLogItemQuery et ChangeToken comptent parmi les plus importants.

Les objets ChangeQuery vous permettent de demander le journal des modifications SharePoint pour toute mise à jour effectuée sur une collection de sites, un site ou une liste SharePoint. L'interface REST expose une méthode getchanges dans chacun de ces trois emplacements :

/_api/site (pour les collections de sites)
/_api/web (pour les sites)
/_api/web/lists/list(guid'<list id>') ou /_api/web/lists/getByTitle('list title') (pour les listes)

Vous transmettez une requête à n'importe lequel de ces emplacements en ajoutant /getchanges au chemin d'URL correspondant, puis en envoyant un objet ChangeQuery via le corps POST de votre requête. Une modification de requête simple demandant tous les éléments qui ont été ajoutés à une liste ressemblerait à ceci (en JSON) :

{
  'query': {
    '__metadata': {
      'type': 'SP.ChangeQuery'
    }, 
    'Add': 'true',
    'Item': 'true'
  }
}

La méthode getchanges s'attend à ce qu'un corps de demande contenant une représentation de l'objet ChangeQuery soit présent dans le paramètre de requête. Vous envoyez cette requête à l'URL pour une liste spécifique :

/_api/web/lists/list(guid'<list id>')/getchanges

/_api/web/lists/getByTitle('<list title>')/getchanges

La réponse renvoie un résultat contenant une collection de modifications correspondant à la requête. Si la liste ne comporte qu'un seul élément, le corps de réponse ressemblera à ceci :

{"d":
    {"results":[{
        "__metadata":{
            "id":"https://<site url>/_api/SP.ChangeItema7e7c6e9-2c41-47c3-aae9-2b4a63b7a087",
            "uri":"https://site url/_api/SP.ChangeItem",
            "type":"SP.ChangeItem"},
        "ChangeToken":{"__metadata":{"type":"SP.ChangeToken"},
            "StringValue":"1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111"},
        "ChangeType":1,
        "SiteId":"ce11bfbb-cf9d-4b2b-a642-8673bd48cceb",
        "Time":"2013-02-03T22:17:54Z",
        "ItemId":1,
        "ListId":"482e418a-0900-414b-8902-02248c2e44e8",
        "WebId":"a975b994-fc67-4203-a519-b160175ca967"}]
    }
}

Cette réponse vous indique qu'un seul élément de liste (avec une valeur ItemId de 1) a été ajouté à un moment qui est représenté dans le journal des modifications par un ChangeToken. Vous pouvez utiliser la valeur de chaîne de cet objet pour préciser vos requêtes. Par exemple, vous pouvez spécifier des valeurs pour les propriétés ChangeTokenStart et ChangeTokenEnd de votre objet ChangeQuery pour être sûr d'obtenir les modifications qui ont eu lieu avant ou après un moment précis ou entre deux moments donnés.

Vous pouvez également utiliser la valeur de l'objet ChangeToken lorsque vous utilisez la méthode getListItemChangesSinceToken :

/_api/web/lists/list(guid'<list id>')/getListChangesSinceToken

Cette méthode n'existe que dans l'interface REST. Si vous souhaitez connaître toutes les modifications apportées aux éléments de cette liste depuis l'ajout du premier élément, vous devez construire un objet ChangeLogItemQuery qui contient le jeton de modification :

{
    'query': {
        '__metadata': {
            'type': 'SP.ChangeLogItemQuery'
        }, 
    'ChangeToken':'1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111'
    }
}

Composants SharePoint Server 2013 Toutes les opérations abordées dans cet article s'appliquent aussi bien à SharePoint Foundation 2013 qu'à SharePoint Server 2013, car elles impliquent les mêmes fonctions SharePoint clés. L'interface SharePoint REST expose également plusieurs fonctions des composants SharePoint Server 2013. Ces composants sortent du cadre de cet article, mais vous pouvez vous référer aux ressources suivantes dans le kit de développement logiciel(SDK) pour plus d'informations sur la manière de les utiliser avec REST :

« SharePoint 2013 : Utilisation du service REST de recherche à partir d'une application pour SharePoint » (bit.ly/Mt4szN)
« Commencez à développer avec des fonctionnalités sociales dans SharePoint 2013 » (bit.ly/102qIGM)
« Documentation de référence de l'API REST BCS pour SharePoint 2013 » (bit.ly/10FFMMu)

Débogage

L'information la plus importante dont vous avez besoin pour effectuer une opération REST est évidemment l'URL correcte. Nous avons évoqué beaucoup d'informations cruciales ici et, pour la majorité de celles qui restent, vous pouvez vous référer au SDK SharePoint. Étant donné que l'interface REST est calquée sur le modèle objet client, vous pouvez vous reporter à la référence de modèle objet JavaScript pour plus d'informations sur les URL du point de terminaison REST. Par exemple, si vous voulez voir les URL disponibles pour utiliser des collections de listes, vous pouvez vous reporter à la documentation de référence de l'objet SP.ListCollection à l'adresse bit.ly/108hI1e.

Vous pouvez également naviguer vers une URL REST en tant qu'utilisateur connecté et afficher la sortie XML de n'importe quelle requête GET afin de voir les données disponibles à chaque point de terminaison ainsi que la manière dont elles sont structurées. Cela ne vous aidera pas pour les requêtes POST, mais cela peut vous permettre de vous familiariser avec les différentes entités SharePoint et les informations disponibles à chaque point de terminaison.

Il est crucial que les requêtes HTTP que vous envoyez à partir de votre code contiennent des URL correctement codées. Lorsque vous lancez une application pour SharePoint à partir de SharePoint, vous pouvez récupérer une URL codée à partir de l'argument de chaîne de requête SPHostUrl mais, dans d'autres contextes, vous risquez de devoir coder l'URL vous-même.

Lorsque vous effectuez davantage d'opérations complexes, tout particulièrement lorsque vous effectuez des opérations nécessitant le verbe HTTP POST, vous devrez utiliser un utilitaire de suivi HTTP afin de déboguer vos requêtes HTTP. SharePoint renvoie un message d'erreur à chaque mauvaise requête que vous faites, et ces messages peuvent vous apprendre beaucoup de choses sur ce qui ne s'est pas bien passé avec vos requêtes. Par exemple, votre application ou utilisateur peut tout simplement ne pas être autorisé à recevoir certains types d'informations de la part de SharePoint. À d'autres moments, vous avez peut-être construit un objet JSON non valide ou assigné une valeur non valide à une propriété.

Certaines infrastructures vous fournissent des utilitaires de suivi HTTP. Vous pouvez utiliser trace.axd (bit.ly/8bnst4) lorsque vous travaillez avec des applications ASP.NET. Si vous envoyez des requêtes directement à partir de votre navigateur, par exemple avec JavaScript, vous pouvez utiliser Fiddler (fiddler2.com/fiddler2). Nous avons utilisé Fiddler pour générer les exemples de réponse HTTP inclus dans cet article.

Utilisation de REST pour communiquer avec SharePoint dans une application PHP

Comme nous l'avons mentionné dans notre introduction, l'interface REST vous permet d'interagir avec SharePoint à l'aide de tous les langages et infrastructures standard communément utilisés par les développeurs Web. Pour le démontrer, nous avons publié un exemple d'application PHP illustrant la manière dont vous pouvez interagir avec un site SharePoint à partir d'une application Web distante écrite en PHP. Il s'agit d'une application pour SharePoint particulière, conçue pour être lancée à partir d'un site SharePoint Office 365 et exécutée à partir d'un site Web Windows Azure. Cette architecture simplifie certaines étapes, par exemple la publication du site Web, mais le code PHP de l'exemple peut s'exécuter sur n'importe quelle architecture qui prend en charge le PHP.

Vous pouvez afficher et télécharger l'exemple à partir de la page de la galerie de code à l'adresse bit.ly/ZQsmvP. L'exemple illustre un certain nombres de points, comme l'utilisation de fichiers et de dossiers avec REST, l'obtention d'un jeton d'accès OAuth à partir d'une application PHP et l'utilisation de la bibliothèque inter-domaines JavaScript. Plus important encore dans le contexte de notre article, il montre comment récupérer des fichiers à partir de et télécharger des fichiers vers une bibliothèque de document SharePoint à l'aide de REST et de PHP.

Comme l'application écrit des données sur un site SharePoint, l'une des premières choses qu'elle doit faire (après avoir obtenu un jeton d'accès) est de demander le chiffrement de formulaire à partir de _api/contextinfo. La requête transmet le jeton d'accès dans les en-têtes et configure une requête POST vers une URL SSL. Le code de la figure 4 sera familier pour quiconque aura travaillé avec des objets URL client PHP.

Figure 4 Demande du chiffrement de formulaire

$opts = array (
    'Authorization: Bearer ' .
    $accToken);
$ch = curl_init();
$url = $appweburl . '/_api/contextinfo';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '');
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);

Une fois la requête exécutée, l'application analyse le XML et stocke la valeur du chiffrement de formulaire :

$root = new SimpleXmlElement($result);

$ns = $root->getNameSpaces(TRUE);
$childrenNodes = $root->children($ns['d']);
$formValue = $childrenNodes->FormDigestValue;

Elle stocke également le jeton d'accès dans un cookie. Lorsque l'utilisateur choisit de télécharger un fichier, l'application transmet ces valeurs à un fichier HTML qui construit la requête HTTP permettant de télécharger les fichiers vers une bibliothèque de documents. Avant de configurer la requête, elle lit les données à partir du fichier stocké localement dans un objet String qui sera transmis en tant que corps de la requête POST :

$accToken = $_COOKIE["moss_access_token"];

$url = $_REQUEST["target"] . 
$furl = $_FILES["file"]["tmp_name"];
$file = fopen($furl,"r");
$post_data = fread($file,filesize($furl));
fclose($file);

Les lignes de la figure 5 récupèrent les valeurs du chiffrement de formulaire et du jeton d'accès, puis configurent et exécutent la requête HTTP qui télécharge le fichier.

Figure 5 Exécution de la requête téléchargeant le fichier

"/_api/web/GetFolderByServerRelativeUrl('Lists/SharedDoc')/Files/
add(url='" . $_FILES["file"]["name"] . "',overwrite=true)";
$opts = array (
'X-RequestDigest:' . $_REQUEST["digest"],
'Authorization: Bearer ' . $accToken);
// Initialize cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
// Set URL on which you want to post the Form and/or data
curl_setopt($ch, CURLOPT_URL, $url);
// Data+Files to be posted
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
// Pass TRUE or 1 if you want to wait for and catch the 
// response against the request made
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// For Debug mode; shows up any error encountered during the operation
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
// Execute the request
$response = curl_exec($ch);

Et maintenant ?

Même si elle n'offre pas une parité complète avec le modèle objet client, l'interface REST de SharePoint 2013 est suffisamment complète et puissante pour permettre aux développeurs d'applications Web et mobiles de parvenir à leurs fins, surtout s'ils travaillent avec des infrastructures autres que .NET. Nous avons examiné beaucoup de façons parmi les plus importantes qui vous permettent d'intégrer SharePoint à vos applications à l'aide de l'interface REST, mais il existe beaucoup d'autres possibilités.

Le SDK de SharePoint 2013 contient une collection de ressources pour le développement REST et vous trouverez des liens vers chacune d'entre elles sur la page de la bibliothèque MSDN « API REST de SharePoint 2013, points de terminaisons et exemples » (bit.ly/137q9yk). Cette collection va s'étoffer pour à terme contenir une gamme d'exemples particulièrement large car, comme le démontre l'exemple PHP, l'interface REST étend de manière significative l'univers du développement SharePoint.

Jim Crowley est rédacteur en programmation senior auprès de la division Office. Il écrit de la documentation destinée aux développeurs pour SharePoint 2013. Il a également écrit l'application SharePoint Developer Documentation RSS Reader (bit.ly/YIVbvY) pour Windows Phone 7.

Ricky Kirkham est rédacteur en programmation senior auprès de la division Office et développeur MCPD (Microsoft Certified Professional Developer) pour SharePoint 2010. Kirkham fait partie de l'équipe de documentation destinée aux développeurs Microsoft pour SharePoint depuis 2006.

MERCI à l'expert technique suivant d'avoir relu cet article : Jyoti Jacob (Microsoft)

Partager via