Connexion aux API SharePoint

Dans vos solutions SharePoint Framework, vous souhaiterez probablement interagir avec les données stockées dans SharePoint. SharePoint propose des API variées pouvant être consommées de plusieurs façons. Cet article présente les options disponibles, leur fonctionnement, et les avantages et inconvénients qu’elles présentent.

Connexion à une API SharePoint à l’aide de la classe SPHttpClient

Vous pouvez utiliser la classe SPHttpClient de SharePoint Framework pour vous connecter aux API REST SharePoint. Une instance prête à l’emploi de la classe SPHttpClient est disponible sur le contexte du composant WebPart/de l’extension. Vous pouvez l’utiliser pour effectuer toutes sortes de demandes web. L’extrait de code suivant montre comment utiliser la classe SPHttpClient pour récupérer le titre du site actuel :

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`, SPHttpClient.configurations.v1)
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: {Title: string}): void => {
    console.log(web.Title);
  });

La classe SPHttpClient propose des fonctionnalités de base permettant d’effectuer les demandes web les plus fréquentes. Il vous permet également de configurer votre demande en spécifiant, par exemple, des en-têtes de requête. Pour émettre une requête web sans récupérer de métadonnées, vous pouvez par exemple utiliser le code suivant :

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata.metadata=none']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Considérations relatives à l’utilisation de la classe SPHttpClient

Lorsque vous utilisez la classe SPHttpClient, prenez en compte les points suivants.

OData v4.0

Par défaut, la classe SPHttpClient utilise la spécification OData v4, laquelle nécessite l’utilisation de odata.metadata au lieu de odata simplement pour contrôler les métadonnées de réponse. Si vous utilisez la directive odata en mode OData v4, un message d’erreur tel que L’en-tête HTTP ACCEPT est manquant ou sa valeur n’est pas valide apparaît. Il est possible de définir spHttpClient sur le mode OData v3.0, en définissant l’en-tête odata-version de requête sur une valeur vide :

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata=nometadata'],
        ['odata-version', '']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Cookies d’authentification

SharePoint Framework propose plusieurs classes pour l’exécution des demandes web. notamment SPHttpClient et HttpClient. Une des différences entre les classes SPHttpClient et HttpClient est que la classe SPHttpClient inclut des cookies d’authentification lors de l’émission des demandes web. Comme les API SharePoint ne sont pas anonymes, vous devez fournir des informations d’authentification sans quoi une réponse 401 Non autorisé sera renvoyée. Étant donné que la classe HttpClient n’inclut pas de cookies d’authentification dans sa demande, son utilisation pour appeler les API REST SharePoint entraînerait l’échec de vos demandes avec une réponse 401 Non autorisé.

Élément de SharePoint Framework

La classe SPHttpClient fait partie de SharePoint Framework et vous n’avez pas besoin de dépendances supplémentaires pour commencer à l’utiliser. Elle est déjà disponible sur la page et, par conséquent, son utilisation n’entraîne pas de dégradation des performances supplémentaire à l’exécution.

Les requêtes REST brutes sont sujettes aux erreurs

La classe SPHttpClient offre une assistance de base pour la communication avec l’API REST SharePoint. Si votre application nécessite des demandes GET ou POST plus complexes, ou utilise des fonctionnalités plus avancées telles que le traitement par lot, vous remarquerez rapidement que l’utilisation de la classe SPHttpClient est fastidieuse et susceptible d’engendrer des erreurs. En pareil cas, il est préférable d’utiliser une alternative telle que la bibliothèque PnPjs qui vous offre une API Fluent dont l’exactitude peut être vérifiée par TypeScript.

Connexion à SharePoint à l’aide de PnPjs

PnPjs est une bibliothèque JavaScript open source permettant de communiquer avec SharePoint et Microsoft 365. Il expose une API Fluent qui vous permet de consommer facilement SharePoint et Microsoft 365 API REST de manière sécurisée. Pour récupérer le titre du site actuel à l’aide de PnPjs, vous devez exécuter le code suivant :

const web = await sp.web
  .select('Title')
  .get<{Title: string;}>();
console.log(web.Title);

Remarque

PnPJS est une solution open source pour laquelle le support est assuré par la communauté active. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.

Notez que le code offre un niveau de détail moins important par rapport à la classe SPHttpClient de SharePoint Framework et que tous les éléments des demandes, à l’exception des noms des propriétés à récupérer, sont fortement typés, ce qui limite les risques d’erreurs d’exécution.

Pour plus d’informations sur la configuration et l’utilisation de PnPjs dans SharePoint Framework, consultez la documentation sur PnPjs disponible à l’adresse https://pnp.github.io/pnpjs/.

Considérations relatives à l’utilisation de PnPjs

Voici quelques considérations dont vous devez tenir compte lorsque vous décidez d’utiliser ou non PnPjs.

Les requêtes REST brutes sont sujettes aux erreurs

La génération de demandes REST brutes à l’aide de la classe SPHttpClient peut engendrer des erreurs. En particulier, si votre application doit exécuter des requêtes POST ou si vous voulez utiliser certaines fonctionnalités plus avancées telles que le traitement par lot, la composition de demandes correctes et l’analyse des réponses sont fastidieuses. Par ailleurs, la seule manière de vérifier que les demandes sont correctes consiste à exécuter le code dans le navigateur. PnPjs vous permet de communiquer avec l’API SharePoint de manière sécurisée pour les types et d’utiliser aisément les fonctionnalités avancées de l’API SharePoint. Vous pouvez ainsi vous concentrer sur la création de votre application plutôt que sur le test de ses demandes.

Projet open source

PnPjs est un projet open source géré par la communauté SharePoint. L’utilisation de PnPjs dans vos solutions n’est encadrée par aucun contrat SLA et le support Microsoft ne pourra pas vous aider si vous deviez rencontrer des problèmes liés à PnPjs. Cela étant dit, PnPjs fait l’objet d’un développement actif et la communauté répond rapidement aux problèmes et questions soumis.

Dépendance supplémentaire

PnPjs est une dépendance supplémentaire que vous devez ajouter à votre projet et gérer au fil du temps. Vous devez suivre ses mises à jour et mettre à niveau votre projet lorsque cela est nécessaire. La communauté derrière PnPjs communique régulièrement concernant l’état du travail en cours, les versions à venir et l’impact éventuel de la mise à niveau vers la version la plus récente.

Charge utile supplémentaire

PnPjs propose un ensemble complet de fonctionnalités pour la communication avec les API SharePoint. La bibliothèque prend en charge les importations sélectives, ce qui permet de limiter l'impact global sur la taille de votre paquet en procédant à une sélection rigoureuse. Pour plus d’informations, consultez la documentation sur https://pnp.github.io/pnpjs/.