Использование Microsoft Graph в решении

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

Прежде чем начинать, выполните следующие действия, чтобы получить базовые навыки создания клиентской веб-части:

• Создайте свою первую веб-часть.
• Подключите веб-часть к SharePoint.
• Выполните развертывание клиентской веб-части на странице SharePoint

Вы также можете сделать это, просмотрев это видео на youTube-канале Microsoft 365 Platform Communtiy (PnP):

Создайте проект SharePoint Framework для использования Microsoft Graph

1. Создайте каталог проекта в любом расположении:

   md graph-apis
   

2. Перейдите к каталогу проекта:

   cd graph-apis
   

3. Создайте новый проект, запустив генератор Yeoman для SharePoint из созданного вами нового каталога:

   yo @microsoft/sharepoint
   

   Генератор Yeoman для SharePoint предложит вам ответить на ряд вопросов. Для всех вопросов, за исключением приведенных ниже, примите параметры по умолчанию:

   • Предоставить администратору клиента возможность развернуть решение на всех сайтах сразу, не запуская развертывание компонентов или добавление приложений на сайтах?: Да
   • Какой тип клиентского компонента нужно создать?: WebPart
   • Как называется ваша веб-часть?: MyFirstGraphWebPart
   • Какую инфраструктуру вы хотели бы использовать?: нет инфраструктуры

   После этого Yeoman устанавливает необходимые зависимости и формирует шаблоны файлов решения. Создание решения может занять несколько минут. Yeoman поддерживает проект, чтобы также включить вашу веб-часть MyFirstGraphWebPart.

4. Затем введите следующую команду, чтобы открыть проект веб-части в Visual Studio Code:

   code .
   

Включение типов Microsoft Graph для облегчения разработки TypeScript

1. В консоли введите следующее, чтобы установить объявления типов Microsoft Graph для улучшения процесса разработки

   npm install @microsoft/microsoft-graph-types
   

Обновление манифеста решения с необходимыми запросами разрешений Microsoft Graph

При использовании SharePoint Framework не требуется явно создавать приложения Azure Active Directory для управления разрешениями для ваших решений. Вместо этого вы можете запросить необходимые разрешения в пакете решения, и тогда администратор клиента Microsoft 365 может предоставить запрошенные разрешения для всех решений в целом или для этого отдельного решения (изолированного решения).

Примечание.

Администраторы клиентов также могут управлять разрешениями API с помощью командлетов PowerShell, поэтому нет необходимости включать разрешения в пакет решения.

В этом случае мы включим в пакет разрешения для конкретного решения.

1. Откройте файл ./config/package-solution.json.

2. Обновите раздел решения, включив в него запрос на предоставление разрешения, как показано в следующем разделе кода, с помощью элемента webApiPermissionRequests. В этом случае мы получим доступ к электронной почте пользователя, поэтому мы запросили разрешения для области Mail.Read.

   {
     "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
     "solution": {
       //...
   
       "webApiPermissionRequests": [
         {
           "resource": "Microsoft Graph",
           "scope": "Mail.Read"
         }
       ]
   
       //...
     }
   }
   

Обновление кода для вызова Microsoft Graph

В этом случае мы модифицируем код, чтобы с помощью Microsoft Graph получить доступ к последним пяти сообщениям электронной почты текущего пользователя.

1. Откройте ./src/webparts/helloWorld/MyFirstGraphWebPartWebPart.ts.

2. Добавьте следующие операторы import после имеющихся операторов import в верхней части файла:

   import { MSGraphClientV3 } from '@microsoft/sp-http';
   import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
   

3. Обновите метод render(), как показано ниже. Обратите внимание, как мы используем объект MSGraphClientV3 для вызовов Microsoft Graph. Этот объект абстрагирует обработку маркеров доступа, поэтому разработчик может сосредоточиться на своей бизнес-логике.

   public render(): void {
     this.context.msGraphClientFactory
     .getClient('3')
     .then((client: MSGraphClientV3): void => {
       // get information about the current user from the Microsoft Graph
       client
       .api('/me/messages')
       .top(5)
       .orderby("receivedDateTime desc")
       .get((error, messages: any, rawResponse?: any) => {
   
         this.domElement.innerHTML = `
         <div class="${styles.myFirstGraphWebPart}">
           <div>
               <h3>Welcome to SharePoint Framework!</h3>
               <p>
                   The SharePoint Framework (SPFx) is a extensibility model for Microsoft Viva, Microsoft Teams and SharePoint. It's the easiest way to extend Microsoft 365 with automatic Single Sign On, automatic hosting and industry standard tooling.
               </p>
           </div>
           <div id="spListContainer" />
         </div>`;
   
         // List the latest emails based on what we got from the Graph
         this._renderEmailList(messages.value);
       });
     });
   }
   

4. Также включите следующую вспомогательную функцию для отображения содержимого электронной почты сразу после существующего метода render(). Обратите внимание, как мы используем типы MicrosoftGraph.Message, чтобы улучшить разработку при доступе к данным ответов API.

   private _renderEmailList(messages: MicrosoftGraph.Message[]): void {
     let html: string = '';
     for (let index = 0; index < messages.length; index++) {
       html += `<p class="${styles.welcome}">Email ${index + 1} - ${escape(messages[index].subject)}</p>`;
     }
   
     // Add the emails to the placeholder
     const listContainer: Element = this.domElement.querySelector('#spListContainer');
     listContainer.innerHTML = html;
   }
   

Упаковка и развертывание веб-части в SharePoint

1. Выполните следующие команды, чтобы собрать пакет вашего решения. При этом будет выполнена сборка выпуска проекта с использованием динамической метки в качестве URL-адреса для размещения ресурсов.

   gulp bundle --ship
   

2. Выполните приведенную ниже задачу, чтобы упаковать решение. Это создаст обновленный пакет graph-apis.sppkg в папке sharepoint/solution.

   gulp package-solution --ship
   

Далее необходимо развернуть созданный пакет в каталоге приложений клиента.

Примечание.

Если у вас нет каталога приложений, администратор SharePoint Online может создать его, следуя инструкциям в этом руководстве: Используйте каталог приложений, чтобы сделать настраиваемые бизнес-приложения доступными для вашей среды SharePoint Online.

1. Перейдите в каталог приложений SharePoint вашего клиента.

2. Загрузите или перетащите файл graph-apis.sppkg в каталог приложений.

   

   При этом будет развернут пакет клиентского решения. Так как это клиентское решение с полным доверием, в SharePoint появится диалоговое окно с предложением разрешить развертывание клиентского решения.

   Обратите внимание, что в списке доменов указана среда SharePoint Online. Это вызвано тем, что контент доставляется либо из сети CDN Office 365, либо из каталога приложений (в зависимости от параметров клиента).

   Убедитесь, что выбран параметр Сделать это решение доступным для всех сайтов в организации, чтобы веб-часть можно было легко использовать для клиента.

   Обратите внимание на запрос о переходе на страницу управления API с утвержденными ожидающими разрешениями и список необходимых разрешений, в данном случае Mail.Read для Microsoft Graph.

   

3. Нажмите Развернуть.

   Обратите внимание, что вы можете увидеть, есть ли какие-либо исключения или проблемы в пакете, посмотрев столбец Сообщение об ошибке пакета приложения в Каталоге приложений.

Теперь веб-часть развернута и автоматически доступна на сайтах SharePoint Online, однако важно понимать, что веб-часть не будет работать должным образом, пока запрошенные разрешения не будут утверждены.

Утверждение запрошенных разрешений Microsoft Graph

1. Перейдите к интерфейсам для администрирования клиента SharePoint, расположенным по адресу: https://{{tenant}}-admin.sharepoint.com.

2. Перейдите к разделу Расширенное > управление API в меню слева, чтобы просмотреть ожидающие в настоящее время запросы на разрешения. Обратите внимание, что запрос на разрешение Mail.Read для Microsoft Graph ожидает утверждения.

   

3. Выделите строку ожидающих разрешений и выберите Утвердить или отклонить на панели инструментов.

   

4. Просмотрите запрошенное разрешение на левой панели и выберите Утвердить.

   

Важно!

Учетная запись, используемая для предоставления запрошенных разрешений, должна быть учетной записью администратора клиента. Разрешения администратора SharePoint недостаточно, поскольку операция фактически выполняется в связанном клиенте Azure Active Directory.

На этом этапе запрошенные разрешения, необходимые для веб-части, утверждены и мы можем проверить функциональность.

Использование веб-части в SharePoint

1. Перейдите на сайт, где вы хотите проверить веб-часть. Мы развернули веб-часть, используя опцию развертывания в области клиента, поэтому она будет доступна на любом сайте.

2. Создайте новую современную страницу на сайте или отредактируйте существующую страницу.

3. Используйте условие поиска Graph в средстве выбора веб-частей, чтобы найти свою веб-часть:

   

4. Выберите MyFirstGraphWebPart из списка и обратите внимание, как веб-часть отображает последние пять электронных писем текущего пользователя, используя информацию из Microsoft Graph API

   

См. также

• Использование MSGraphClient для подключения к Microsoft Graph
• Использование Microsoft Graph в SharePoint Framework
• Проводник графиков
• Начните с Microsoft Graph и JavaScript