Подключение к API SharePoint

Статья
03/21/2023

В своих решениях SharePoint Framework вы, скорее всего, захотите работать с данными, которые хранятся в SharePoint. SharePoint предлагает широкий набор API, которые можно использовать по-разному. В этой статье мы расскажем, какими они бывают, как работают и какие преимущества и недостатки имеют.

Подключение к API SharePoint с помощью SPHttpClient

SharePoint Framework имеет SPHttpClient, который можно использовать для подключения к REST API SharePoint. Готовый к использованию экземпляр SPHttpClient доступен в контексте веб-части/расширения, и его можно использовать для выполнения всех типов веб-запросов. Ниже показано, как использовать SPHttpClient для получения названия текущего сайта:

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);
  });

SPHttpClient имеет базовые функции для выполнения наиболее распространенных веб-запросов. Он также позволяет настроить запрос, например, указав заголовки запроса. Например, если вы хотите отправить веб-запрос, не извлекая метаданные, используйте следующий код:

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);
  });

Что нужно учитывать при использовании SPHttpClient

При использовании SPHttpClient следует учитывать несколько моментов.

OData версии 4.0

По умолчанию SPHttpClient использует спецификацию OData версии 4, которая для управления метаданными ответа требует использовать параметр odata.metadata, а не просто odata. При использовании директивы odata в режиме OData версии 4 вы получите сообщение об ошибке Заголовок HTTP ACCEPT отсутствует, или его значение недействительно. Можно задать для SPHttpClient режим OData версии 3.0, задав для заголовка odata-version запроса пустое значение:

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);
  });

Файлы cookie для проверки подлинности

В SharePoint Framework существует ряд классов для выполнения веб-запросов. Два из них — это SPHttpClient и HttpClient. Одно из различий между SPHttpClient и HttpClient состоит в том, что SPHttpClient включает файлы cookie для проверки подлинности при отправке веб-запросов. Так как API SharePoint не являются анонимными, необходимо указывать информацию для проверки подлинности, или вы получите ответ "401 Не авторизирован". Так как HttpClient не включает файлы cookie для проверки подлинности в свой запрос, то при его использовании для вызова REST API SharePoint ваши запросы могут завершиться ошибкой 401 Unauthorized.

Компонент SharePoint Framework

SPHttpClient входит в состав SharePoint Framework, и для его использования не нужны дополнительные зависимости. Он уже доступен на странице, поэтому его использование не снижает производительность среды выполнения.

Чистые запросы REST подвержены ошибкам

SPHttpClient имеет базовую поддержку взаимодействия с REST API SharePoint. Если ваши приложения требуют выполнения более сложных запросов GET, POST или используют более сложные возможности, такие как пакетная обработка, то вы быстро заметите, что использовать SPHttpClient сложно; кроме того, это сопряжено с ошибками. В таких случаях мы рекомендуем использовать альтернативный вариант, например библиотеку PnPjs, которая имеет текучий API, правильность которого можно проверить с помощью TypeScript.

Подключение к SharePoint с помощью PnPjs

PnPjs — это библиотека JavaScript с открытым кодом для взаимодействия с SharePoint и Microsoft 365. Она предоставляет текучий API, позволяющий легко использовать REST API SharePoint и Microsoft 365 типобезопасным способом. Чтобы получить заголовок текущего сайта с помощью PnPjs, необходимо выполнить следующий код:

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

Примечание.

PnPJS — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.

Обратите внимание, насколько короче код по сравнению с кодом SPHttpClient SharePoint Framework, и как все элементы запросов, за исключением имен свойств, которые нужно получить, строго типизированы, что уменьшает риск ошибок выполнения.

Дополнительные сведения о том, как установить и использовать PnPjs в SharePoint Framework, см. в документации PnPjs по адресу https://pnp.github.io/pnpjs/.

Что нужно учитывать при использовании PnPjs

Принимая решение о целесообразности использования PnPjs, учитывайте перечисленные ниже моменты.

Чистые запросы REST подвержены ошибкам

При отправке чистых запросов REST с помощью SPHttpClient возможны ошибки. Особенно когда приложению потребуется выполнять запросы POST или вы хотите использовать расширенные возможности, например пакетную обработку запросов, составить правильные запросы и проанализировать ответы будет сложно. Единственный способ проверить правильность запросов — выполнить код в браузере. Используя PnPjs, вы можете передавать данные в API SharePoint в строго типизированном виде и легко использовать дополнительные возможности API SharePoint, что позволяет заниматься созданием приложения, а не тестированием его запросов.

Проект с открытым кодом

PnPjs — это проект с открытым исходным кодом, которым управляет сообщество разработчиков SharePoint. Использование PnPjs в ваших решениях не регламентируется Договором о качестве услуг (SLA), и служба поддержки Майкрософт не поможет вам решить возможные проблемы, связанные с PnPjs. С другой стороны, PnPjs активно развивается, и сообщество быстро отвечает на все отправленные вопросы и сообщения о проблемах.

Дополнительная зависимость

PnPjs — это дополнительная зависимость, которую необходимо добавить в проект и которой необходимо управлять с течением времени. Вам нужно следить за ее обновлениями и при необходимости обновлять проект. Сообщество разработчиков PnPjs регулярно оповещает о статусе текущей работы, запланированных выпусках продукта и последствиях перехода на новую версию (если такие последствия есть).

Дополнительная нагрузка

PnPjs имеет широкий набор возможностей для взаимодействия с API SharePoint. Библиотека поддерживает выборочный импорт, поэтому при внимательной настройке можно уменьшить общее влияние на размер вашего пакета. Дополнительные сведения см. в документации на странице https://pnp.github.io/pnpjs/.

Подключение к API SharePoint