Récupérer et afficher les données de la liste avec l’API REST de SharePoint
Dans cette unité, vous allez apprendre à utiliser l’API SharePoint Framework pour récupérer des données de liste à partir de l’API REST SharePoint.
API REST SharePoint
L’API REST SharePoint est le main moyen d’accéder aux données d’un site SharePoint. Il fonctionne pour les solutions côté client et côté serveur. Les solutions côté client incluent des composants SharePoint Framework et des solutions côté serveur s’exécutent sur un serveur en dehors de votre environnement SharePoint, comme une fonction Azure ou une application web.
Il existe de nombreux sdk et bibliothèques que les développeurs peuvent utiliser pour travailler avec l’API REST SharePoint, notamment le modèle objet côté client SharePoint (CSOM) et la bibliothèque PnPJS (Modèles et pratiques SharePoint).
L’API REST SharePoint permet aux développeurs d’effectuer des opérations CRUD-Q sur des données dans des listes et bibliothèques SharePoint. CRUD-Q désigne les opérations de création, lecture, mise à jour, suppression et interrogation. L’API REST SharePoint utilise les protocoles OData v3 et v4, ce qui vous permet d’utiliser un moyen standard d’effectuer des demandes et d’obtenir des résultats prévisibles. Par défaut, l’API REST SharePoint s’attendra à ce que les demandes soient envoyées et renvoyées au format OData v3. Les développeurs peuvent modifier ce comportement en écrasant l’en-tête de requête HTTP odata-version et en le définissant sur 4 pour utiliser le format OData v4. SharePoint Framework effectue cette opération automatiquement avec une configuration par défaut.
Accéder à l’API REST SharePoint
L’API REST SharePoint vérifie votre identité et vos autorisations avec chaque demande. Vous devez donc inclure les détails de l’autorisation lorsque vous effectuez une demande. Chaque demande est autorisée en incluant un en-tête de requête HTTP authorization qui contient un jeton de porteur Oauth2. Ce jeton est fourni par Microsoft Entra ID après une authentification réussie et accordant les autorisations nécessaires à l’application qui accède à l’API REST SharePoint. Ce jeton d’autorisation est requis lorsque vous envoyez une demande à l’API REST SharePoint à partir d’un emplacement hors du serveur SharePoint.
Lorsque vous envoyez une demande à partir d’un script côté client sur une page SharePoint, vous n’avez pas besoin d’un jeton d’autorisation. Chaque demande inclut un cookie ajouté à votre session de navigateur lorsque vous vous êtes connecté au site SharePoint.
Les en-têtes de requête HTTP sont utilisés pour l’autorisation et pour contrôler la version du protocole OData, la quantité de métadonnées retournées et d’autres éléments. Par exemple, lorsque vous mettez à jour ou supprimez une demande, vous pouvez inclure l’en-tête de requête HTTP if-match pour vérifier que l’élément que vous voulez mettre à jour ou supprimer utilise la même version sur le serveur que celle attendue par votre application. Cet en-tête permet aux développeurs de vérifier qu’ils ne sont pas dans un scénario donnant la priorité à la dernière mise à jour.
Opérateurs de requête OData
Voici un exemple de ce à quoi ressemble une demande OData :
https://{{sharepoint-site}}/sites/site/_api/web/lists/getbytitle('Countries')/items?
$select=Id,Title
&$filter=Title eq 'United States'
&$orderby=ID desc
&$top=1
L’API REST SharePoint démarre avec le point de terminaison _api. Le reste de la portion du chemin d’accès de l’URL (web/lists/getbytitle('Pays')/items dans cet exemple) est utilisé pour faire référence à une ressource spécifique. Dans cet exemple, les éléments de la liste Pays du site SharePoint actuel sont renvoyés.
Notez les paramètres avec le préfixe $ dans la chaîne de requête de l’URL. Il s’agit des opérateurs de requête OData. Les opérateurs de requête OData permettent de contrôler la quantité de données renvoyées dans chaque requête.
L’opérateur de requête $select est utilisé pour indiquer à l’API REST SharePoint de renvoyer uniquement des champs spécifiques pour la collection d’éléments. Sans l’opérateur $select, une collection de propriétés par défaut est renvoyée.
L’opérateur de requête $filter est utilisé pour inclure seulement un sous-ensemble d’éléments de la liste.
L’opérateur de requête $orderby permet aux développeurs de spécifier le champ sur lequel trier les résultats et le sens de l’opération de tri.
Enfin, l’opérateur de requête $top est utilisé pour sélectionner uniquement un sous-ensemble des résultats de la requête.
Dans cet exemple, le dernier élément de la liste intitulé États-Unis est renvoyé dans la réponse et inclut uniquement les propriétés ID et Titre.
SharePoint Framework et API REST SharePoint
SharePoint Framework inclut une API qui simplifie l’envoi de la demande à l’API REST SharePoint. L’API SPHttpClient est disponible dans toutes les solutions SharePoint Framework sur l’objet context. Le SPHttpClient est étendue à l HttpClient API, qui est un wrapper de l’API Fetch inclus dans tous les navigateurs modernes. Elle inclut également un polyfill pour les anciens navigateurs qui ne prennent pas en charge l’API Fetch.
HttpClient est également incluse dans l’API SharePoint Framework. Les développeurs peuvent l’utiliser pour envoyer des requêtes HTTP à n’importe quelle API REST.
L’API SPHttpClient configure automatiquement la requête HTTP avec les en-têtes de requête HTTP requis. Elle définit notamment la version v4 de l’API REST SharePoint et configure la réponse afin de n’inclure que les métadonnées minimales pour chaque élément renvoyé.
Obtenir des éléments de liste avec l’API REST SharePoint et SharePoint Framework
Pour envoyer une demande à l’API REST SharePoint, utilisez l’objet spHttpClient sur l’objet context du composant actuel. Vous allez utiliser la méthode get() ou post() pour envoyer une requête HTTP GET ou HTTP POST.
private async _getListItems(): Promise<ICountryListItem[]> {
const response = await this.context.spHttpClient.get(
this.context.pageContext.web.absoluteUrl + `/_api/web/lists/getbytitle('Countries')/items?$select=Id,Title`,
SPHttpClient.configurations.v1);
if (!response.ok) {
const responseText = await response.text();
throw new Error(responseText);
}
const responseJson = await response.json();
return responseJson.value as ICountryListItem[];
}
Le premier paramètre de la demande correspond au point de terminaison de l’API REST SharePoint auquel vous voulez envoyer une demande. Le deuxième paramètre définit la configuration à utiliser. Celle-ci définit les en-têtes de requête HTTP mentionnés précédemment. Vous pouvez passer un troisième argument pour remplacer les paramètres par défaut, par exemple si vous souhaitez des métadonnées complètes ou aucune métadonnées dans la réponse.
Les méthodes get() et post() renvoient une promesse JavaScript qui vous permet d’examiner les en-têtes de réponse HTTP ou le code d’état de la demande. Si le corps de la réponse contient du code JSON, vous pouvez appeler la méthode json() qui renvoie également une promesse contenant le corps analysé converti en objet JSON.
Résumé
Dans cette unité, vous avez appris à utiliser l’API SharePoint Framework pour récupérer des données de liste à partir de l’API REST SharePoint.