Déterminer les URI de point de terminaison du service REST SharePoint
Conseil
Avant de commencer, consultez les ressources suivantes :
Découverte du service REST SharePointNaviguer dans la structure de données SharePoint représentée dans le service REST
Structure des URI de point de terminaison REST SharePoint
Avant de pouvoir accéder à une ressource SharePoint à l'aide du service REST, vous devez d'abord détecter le point de terminaison d'URI qui pointe vers cette ressource. 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. Par exemple :
Dans certains cas, l’URI de point de terminaison diffère de la signature de modèle objet client correspondante, afin d’assurer la conformité avec les conventions REST ou OData.
La figure suivante montre la structure de la syntaxe générale des URI REST SharePoint.
Structure de la syntaxe d’URI REST SharePoint**
Certains points de terminaison pour les ressources SharePoint s’écartent de cette structure de syntaxe :
- Méthodes qui nécessitent des types complexes en tant que paramètres. Si la méthode de modèle objet client correspondante exige que des types complexes soient transmis en tant que paramètres, le point de terminaison REST peut dévier de cette construction syntaxique pour justifier les limitations REST.
- Méthodes et propriétés statiques. Les points de terminaison REST s’écartent de cette structure de syntaxe pour les URI qui représentent des méthodes et propriétés statiques.
Déterminer les points de terminaison du service REST SharePoint
Pour créer un point de terminaison REST pour une ressource SharePoint, procédez comme suit :
Démarrez avec la référence de service REST :
https://{site_url}/_apiSpécifiez le point d'entrée approprié. Par exemple :
https://{site_url}/_api/webNaviguez du point d'entrée vers les ressources spécifiques auxquelles vous voulez accéder. Ceci inclut la spécification de paramètres pour les points de terminaison correspondant aux méthodes dans le modèle objet client. Par exemple :
https://{site_url}/_api/web/lists/getbytitle('{list_name}')
Référencer le service REST SharePoint dans votre URI de point de terminaison
Utilisez _api pour indiquer le service REST SharePoint dans l’URI de vos points de terminaison. Le service REST fait partie du service web client.svc. Toutefois, pour faciliter la composition des URI REST et raccourcir leur chemin de base, le service REST utilise _api pour vous éviter de référencer explicitement le service web client.svc.
Le service REST reconnaît et accepte tout de même les URI qui spécifient le service web client.svc. Par exemple, vous pouvez utiliser l’URI https://{site_url}/_vti_bin/client.svc/web/lists au lieu de https://{site_url}/_api/web/lists. Toutefois, l’utilisation de _api est préférée. Les URL ayant une limite de 256 caractères, l’utilisation de _api permet de réduire l’URI de base et de laisser plus de caractères pour le reste de l’URL.
Spécifier les points d’entrée pour le service REST SharePoint
Les points d’entrée principaux pour le service REST représentent la collection de sites et le site du contexte spécifié. Ainsi, ces points d’entrée correspondent aux propriétés ClientContext.Site et ClientContext.Web des modèles objet client.
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
Outre /site et /web, le service REST inclut d’autres points d’accès permettant aux développeurs de naviguer vers des fonctionnalités spécifiques. Le tableau suivant répertorie certains de ces points d’accès.
| Fonctionnalités | Point d’accès |
|---|---|
| Site | https://{site_url}/_api/site |
| Web | https://{site_url}/_api/web |
| Profil utilisateur | https://{site_url}/_api/SP.UserProfiles.PeopleManager |
| Rechercher | https://{site_url}/_api/search |
Naviguer vers les ressources spécifiques auxquelles vous voulez accéder
À partir de là, créez des points de terminaison 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 (/). Le tableau suivant présente des exemples d’appels de modèle objet client et leur point de terminaison REST correspondant.
| API de modèle objet client | Point de terminaison REST |
|---|---|
| ClientContext.Web.Lists | https://{site_url}/_api/web/lists |
| ClientContext.Web.Lists[guid] | https://{site_url}/_api/web/lists('<guid>') |
| ClientContext.Web.Lists.GetByTitle("Title") | https://{site_url}/_api/web/lists/getbytitle('<Title>') |
L’URI des points de terminaison ne tient pas compte des majuscules et des minuscules. Par exemple, dans le tableau précédent, /getbytitle permet de spécifier l’équivalent REST de la méthode GetByTitle().
Spécifier des paramètres dans les URI de point de terminaison REST
SharePoint étend la spécification OData pour vous permettre d'utiliser des parenthèses pour spécifier les paramètres de méthode et les valeurs d'index. Cela permet d'éviter les problèmes de levée d'ambiguïté potentiels dans les URI qui contiennent plusieurs paramètres portant un nom identique. Par exemple, les deux URI suivants contiennent des paramètres au nom identique :
https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')
https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')
Pour spécifier plusieurs paramètres, incluez le paramètre en tant que paire nom-valeur et séparez les paramètres par des virgules. Par exemple :
https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)
La figure suivante illustre la syntaxe de paramètre REST SharePoint.
Syntaxe de paramètre REST SharePoint
Types complexes en tant que paramètres pour le service REST
Certaines méthodes dans le modèle objet client exigent une grande charge utile en tant que paramètre. Pour que les points de terminaison REST conservent la parité de fonctionnalités avec les API de modèle objet client correspondantes, les points de terminaison doivent accepter un type complexe en tant que paramètre. Dans ce cas, le service REST étend le protocole OData existant pour permettre à ces points de terminaison REST d'accepter un type complexe unique en tant que paramètre. Ceci s'applique uniquement aux opérations POST et vous devez transmettre le type complexe au format Atom ou JSON, conformément aux normes OData.
Par exemple, la méthode ListCollection.Add utilise un objet Microsoft.SharePoint.Client.ListCreationInformation comme paramètre. Pour ajouter une liste à un site spécifié, composez le point de terminaison REST approprié comme suit :
POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
{ "d" : {
"results": {
"__metadata": {
"type": "SP.ListCreationInformation"
},
"CustomSchemaXml": "…large payload…/",
"Description": "desc",
"DocumentTemplateType": "1",
"TemplateType": "101",
"Title": "Announcements"
}
}
}
Utilisation d’alias de paramètre dans les appels de service REST
Vous pouvez utiliser la sémantique « alias de paramètre » dans OData pour transmettre des paramètres à un point de terminaison REST SharePoint. Dans l'alias de paramètre, la valeur de paramètre est identifiée par un alias dans l'appel de paramètre et la valeur réelle est spécifiée dans la chaîne de requête de l'URI. Ceci vous permet de prendre en charge plusieurs types de caractères et une mise en forme cohérente à l'aide de la chaîne de requête.
Par exemple, les deux URI REST suivants sont équivalents :
Spécifiez la valeur du paramètre directement :
https://{site_url}/_api/web/applyWebTemplate("STS#0")
Utilisez un alias de paramètre et spécifiez la valeur de paramètre réelle dans la chaîne de requête de l'URI :
https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"
En revanche, le service REST SharePoint ne prend pas en charge la transmission de types complexes via l'alias de paramètre. Par exemple, l'URI suivant, qui contient un type complexe dans l'alias de paramètre, n'est pas pris en charge :
https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}
Syntaxe d’alias de paramètre de service REST SharePoint
Spécification de dictionnaires en tant que valeurs de paramètre
Pour les points de terminaison REST correspondant aux méthodes qui utilisent des dictionnaires Dictionary<String, String> comme paramètres, transmettez le dictionnaire sous la forme d’une série de paires nom-valeur séparées par des virgules dans la chaîne de requête.
Syntaxe de service REST pour les paramètres du dictionnaire
Dictionary<String, object> est représenté par un objet à valeurs multiples nommé KeyedPropertyValue, avec les propriétés de chaîne suivantes :
- Key Clé de l’objet à valeurs multiples.
- Value Valeur de l’objet.
- ValueType Type de valeur de l'objet. Pour les types valeur simples mappés à des types EDM (Entity Data Model) existants, le service REST retourne la chaîne de type EDM appropriée ; par exemple, « Edm.String ». Si ce n’est pas le cas, le service REST retourne le type de valeur retourné par la fonction Type.ToString .
Spécification de valeurs de paramètre dans la chaîne de requête
Si l'URI REST se termine par un appel de méthode, vous pouvez utiliser la syntaxe de chaîne de requête pour spécifier les valeurs de paramètre de la méthode. Par exemple :
https://{site_url}/_api/web/applyWebTemplate?template="STS#0"
La figure suivante illustre la syntaxe du service REST pour les paramètres dans la chaîne de requête.
Syntaxe de service REST pour les paramètres dans la chaîne de requête
Spécifier des méthodes et des propriétés statiques en tant qu’URI du service REST
Pour créer des URI correspondant aux méthodes ou propriétés statiques, utilisez le nom d'API correspondant du modèle d'objet ECMAScript, en commençant par la déclaration d'espace de noms et en utilisant la notation par points. Par exemple, SP. Utilities.Utility.getImageUrl(imageName) dans le modèle objet client ECMAScript aurait l’équivalent REST suivant :
https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')
Cependant, les propriétés statiques sont accessibles uniquement de façon directe et ne sont pas autorisées dans le cadre d'une composition d'URI plus importante. Par exemple, l'accès direct à la méthode SP.Utility.AssetsLibrary dans REST peut être autorisé comme suit :
https://{site_url}/_api/SP.Utility.assetsLibrary/id
En revanche, l’utilisation de cet emplacement de ressource comme paramètre pour un URI plus complexe, comme dans l’exemple ci-dessous, n’est pas autorisée :
https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)
La figure suivante illustre la syntaxe de membre statique du service REST SharePoint.
Syntaxe de membre statique de service REST SharePoint
Si vous voulez sélectionner, filtrer ou trier les données que vous avez demandées à partir d’un point de terminaison, le service REST SharePoint prend en charge une large gamme d’opérateurs de chaîne de recherche OData. Pour en savoir plus, consultez l’article Utiliser les opérations de requête OData dans les demandes REST SharePoint.