Создание приложений TypeScript с помощью Microsoft Graph

Статья
Developer (Начальный уровень)
23 мин до завершения

В этом руководстве описано, как создать консольное приложение TypeScript, использующее API Microsoft Graph.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений, см. в этом руководстве по проверке подлинности только для приложений.

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

Совет

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

Вы также можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.

Предварительные условия

Прежде чем приступить к работе с этим руководством, необходимо установить Node.js на компьютере разработки.

У вас также должна быть рабочая или учебная учетная запись Майкрософт с почтовым ящиком Exchange Online. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примечание.

Это руководство было написано с Node.js версии 16.14.2. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

Регистрация приложения на портале

Осталось 22 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности пользователей. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.

Регистрация приложения для проверки подлинности пользователей

В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности пользователей с помощью потока кода устройства.

Центр администрирования Microsoft Entra
PowerShell

Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например Graph User Auth Tutorial.

Задайте поддерживаемые типы учетных записей . Доступны следующие варианты:

Вариант	Кто может выполнить вход?
Учетные записи только в этом каталоге организации	Только пользователи в организации Microsoft 365
Учетные записи в любом каталоге организации	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
Учетные записи в любом каталоге организации... и личные учетные записи Майкрософт	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт

Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и сохраните его. Оно понадобится на следующем шаге. Если вы выбрали Учетные записи в этом каталоге организации только для поддерживаемых типов учетных записей, скопируйте идентификатор каталога (клиента) и сохраните его.
Выберите пункт Проверка подлинности в разделе Управление. Найдите раздел Дополнительные параметры и установите переключатель Разрешить общедоступные клиентские потоки на Да, а затем нажмите кнопку Сохранить.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Важно!

Для сценария PowerShell требуется рабочая или учебная учетная запись с ролью администратора приложений, администратора облачных приложений или глобального администратора. Если ваша учетная запись имеет роль разработчика приложений, вы можете зарегистрироваться в Центре администрирования Microsoft Entra.

Создайте файл с именем RegisterAppForUserAuth.ps1 и добавьте следующий код.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForUserAuth.ps1.

Выполните следующую команду, заменив <значение> аудитории нужным значением (см. таблицу ниже).

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

Значение SignInAudience	Кто может выполнить вход?
`AzureADMyOrg`	Только пользователи в организации Microsoft 365
`AzureADMultipleOrgs`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи)
`AzureADandPersonalMicrosoftAccount`	Пользователи в любой организации Microsoft 365 (рабочие или учебные учетные записи) и личные учетные записи Майкрософт
`PersonalMicrosoftAccount`	Только личные учетные записи Майкрософт

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента и проверки подлинности из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Примечание.

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

Создание консольного приложения TypeScript

Осталось 19 мин

Начните с создания проекта Node.js и настройки TypeScript.

Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.
```
npm init
```
Отвечайте на запросы, указав собственные значения или приняв значения по умолчанию.
Выполните следующую команду, чтобы установить TypeScript.
```
npm install -D typescript ts-node
```
Выполните следующую команду, чтобы инициализировать TypeScript.
```
npx tsc --init
```

Установка зависимостей

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

Клиентская библиотека удостоверений Azure для JavaScript для проверки подлинности пользователя и получения маркеров доступа.
Клиентская библиотека JavaScript в Microsoft Graph для выполнения вызовов к Microsoft Graph.
изоморфная выборка для добавления fetch API в Node.js. Это зависимость для клиентской библиотеки JavaScript в Microsoft Graph.
readline-sync для запроса ввода данных у пользователя.

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

npm install @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch readline-sync
npm install -D @microsoft/microsoft-graph-types @types/node @types/readline-sync @types/isomorphic-fetch

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

Создайте файл в корне проекта с именем appSettings.ts и добавьте следующий код.

const settings: AppSettings = {
  clientId: 'YOUR_CLIENT_ID_HERE',
  tenantId: 'common',
  graphUserScopes: ['user.read', 'mail.read', 'mail.send'],
};

export interface AppSettings {
  clientId: string;
  tenantId: string;
  graphUserScopes: string[];
}

export default settings;

Обновите значения в в settings соответствии со следующей таблицей.

Параметр	Значение
`clientId`	Идентификатор клиента для регистрации приложения
`tenantId`	Если вы выбрали параметр, разрешать вход только пользователям в вашей организации, измените это значение на идентификатор клиента. В противном случае оставьте значение `common`.

Проектирование приложения

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

Создайте файл в корне проекта с именем graphHelper.ts и добавьте следующий код заполнителя. Вы добавите дополнительный код этого файла на последующих шагах.
```
export {};
```

Создайте файл в корне проекта с именем index.ts и добавьте следующий код.

import * as readline from 'readline-sync';
import { DeviceCodeInfo } from '@azure/identity';
import { Message } from '@microsoft/microsoft-graph-types';

import settings, { AppSettings } from './appSettings';
import * as graphHelper from './graphHelper';

async function main() {
  console.log('TypeScript Graph Tutorial');

  let choice = 0;

  // Initialize Graph
  initializeGraph(settings);

  // Greet the user by name
  await greetUserAsync();

  const choices = [
    'Display access token',
    'List my inbox',
    'Send mail',
    'Make a Graph call',
  ];

  while (choice != -1) {
    choice = readline.keyInSelect(choices, 'Select an option', {
      cancel: 'Exit',
    });

    switch (choice) {
      case -1:
        // Exit
        console.log('Goodbye...');
        break;
      case 0:
        // Display access token
        await displayAccessTokenAsync();
        break;
      case 1:
        // List emails from user's inbox
        await listInboxAsync();
        break;
      case 2:
        // Send an email message
        await sendMailAsync();
        break;
      case 3:
        // Run any Graph code
        await makeGraphCallAsync();
        break;
      default:
        console.log('Invalid choice! Please try again.');
    }
  }
}

main();

Добавьте следующие методы-заполнители в конец файла. Вы будете реализовывать их на последующих шагах.

function initializeGraph(settings: AppSettings) {
  // TODO
}

async function greetUserAsync() {
  // TODO
}

async function displayAccessTokenAsync() {
  // TODO
}

async function listInboxAsync() {
  // TODO
}

async function sendMailAsync() {
  // TODO
}

async function makeGraphCallAsync() {
  // TODO
}

Это реализует базовое меню и считывает выбор пользователя из командной строки.

Добавление проверки подлинности пользователя

Осталось 15 мин

В этом разделе описано, как расширить приложение из предыдущего упражнения для поддержки проверки подлинности с помощью Azure AD. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентскую библиотеку удостоверений Azure для JavaScript в приложение и настроите проверку подлинности для клиентской библиотеки JavaScript в Microsoft Graph.

Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential OAuth2. Клиентская библиотека Microsoft Graph использует эти классы для проверки подлинности вызовов Microsoft Graph.

Настройка клиента Graph для проверки подлинности пользователей

В этом разделе вы будете DeviceCodeCredential использовать класс для запроса маркера доступа с помощью потока кода устройства.

Откройте graphHelper.ts и замените его содержимое следующим.

import 'isomorphic-fetch';
import {
  DeviceCodeCredential,
  DeviceCodePromptCallback,
} from '@azure/identity';
import { Client, PageCollection } from '@microsoft/microsoft-graph-client';
import { User, Message } from '@microsoft/microsoft-graph-types';
// prettier-ignore
import { TokenCredentialAuthenticationProvider } from
  '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials';

import { AppSettings } from './appSettings';

let _settings: AppSettings | undefined = undefined;
let _deviceCodeCredential: DeviceCodeCredential | undefined = undefined;
let _userClient: Client | undefined = undefined;

export function initializeGraphForUserAuth(
  settings: AppSettings,
  deviceCodePrompt: DeviceCodePromptCallback,
) {
  // Ensure settings isn't null
  if (!settings) {
    throw new Error('Settings cannot be undefined');
  }

  _settings = settings;

  _deviceCodeCredential = new DeviceCodeCredential({
    clientId: settings.clientId,
    tenantId: settings.tenantId,
    userPromptCallback: deviceCodePrompt,
  });

  const authProvider = new TokenCredentialAuthenticationProvider(
    _deviceCodeCredential,
    {
      scopes: settings.graphUserScopes,
    },
  );

  _userClient = Client.initWithMiddleware({
    authProvider: authProvider,
  });
}

Замените пустую initializeGraph функцию в index.ts на следующую.

function initializeGraph(settings: AppSettings) {
  graphHelper.initializeGraphForUserAuth(settings, (info: DeviceCodeInfo) => {
    // Display the device code message to
    // the user. This tells them
    // where to go to sign in and provides the
    // code to use.
    console.log(info.message);
  });
}

Этот код объявляет два частных свойства: DeviceCodeCredential объект и Client объект . Функция initializeGraphForUserAuth создает новый экземпляр DeviceCodeCredential, а затем использует его для создания нового экземпляра Client. Каждый раз, когда вызов API выполняется в Microsoft Graph через _userClient, он будет использовать предоставленные учетные данные для получения маркера доступа.

Тестирование DeviceCodeCredential

Затем добавьте код для получения маркера доступа из DeviceCodeCredential.

Добавьте следующую функцию в graphHelper.ts.

export async function getUserTokenAsync(): Promise<string> {
  // Ensure credential isn't undefined
  if (!_deviceCodeCredential) {
    throw new Error('Graph has not been initialized for user auth');
  }

  // Ensure scopes isn't undefined
  if (!_settings?.graphUserScopes) {
    throw new Error('Setting "scopes" cannot be undefined');
  }

  // Request token with given scopes
  const response = await _deviceCodeCredential.getToken(
    _settings?.graphUserScopes,
  );
  return response.token;
}

Замените пустую displayAccessTokenAsync функцию в index.ts на следующую.

async function displayAccessTokenAsync() {
  try {
    const userToken = await graphHelper.getUserTokenAsync();
    console.log(`User token: ${userToken}`);
  } catch (err) {
    console.log(`Error getting user access token: ${err}`);
  }
}

Выполните следующую команду в интерфейсе командной строки в корне проекта.
```
npx ts-node index.ts
```

Введите 1 при появлении запроса на выбор параметра. Приложение отображает URL-адрес и код устройства.

TypeScript Graph Tutorial

[1] Display access token
[2] List my inbox
[3] Send mail
[4] Make a Graph call
[0] Exit

Select an option [1...4 / 0]: 1
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
enter the code RK987NX32 to authenticate.

Откройте браузер и перейдите по url-адресу. Введите предоставленный код и войдите в систему.

Важно!

Помните о всех существующих учетных записях Microsoft 365, которые вошли в браузер при просмотре страницы https://microsoft.com/devicelogin. Используйте функции браузера, такие как профили, гостевой режим или частный режим, чтобы проверить подлинность в качестве учетной записи, которую вы планируете использовать для тестирования.
После завершения вернитесь к приложению, чтобы увидеть маркер доступа.

Совет

Только для проверки и отладки можно декодировать маркеры доступа пользователей (только для рабочих или учебных учетных записей) с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что scp утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Получение пользователя

Осталось 12 мин

В этом разделе описано, как включить Microsoft Graph в приложение. Для выполнения вызовов Microsoft Graph вы будете использовать клиентскую библиотеку JavaScript Microsoft Graph .

Откройте graphHelper.ts и добавьте следующую функцию.

export async function getUserAsync(): Promise<User> {
  // Ensure client isn't undefined
  if (!_userClient) {
    throw new Error('Graph has not been initialized for user auth');
  }

  // Only request specific properties with .select()
  return _userClient
    .api('/me')
    .select(['displayName', 'mail', 'userPrincipalName'])
    .get();
}

Замените пустую greetUserAsync функцию в index.ts на следующую.

async function greetUserAsync() {
  try {
    const user = await graphHelper.getUserAsync();
    console.log(`Hello, ${user?.displayName}!`);
    // For Work/school accounts, email is in mail property
    // Personal accounts, email is in userPrincipalName
    console.log(`Email: ${user?.mail ?? user?.userPrincipalName ?? ''}`);
  } catch (err) {
    console.log(`Error getting user: ${err}`);
  }
}

Если вы запустите приложение сейчас, после входа в приложение будет приветствовать вас по имени.

Hello, Megan Bowen!
Email: MeganB@contoso.com

Описание кода

Рассмотрим код в getUserAsync функции. Это всего несколько строк, но есть некоторые ключевые детали, которые следует обратить внимание.

Доступ к "мне"

Функция передается /me в _userClient.api построитель запросов, который создает запрос к API get user . Этот API доступен двумя способами:

GET /me
GET /users/{user-id}

В этом случае код вызывает конечную точку GET /me API. Это ярлык, который позволяет получить пользователя, прошедшего проверку подлинности, не зная его идентификатора пользователя.

Примечание.

GET /me Так как конечная точка API получает пользователя, прошедшего проверку подлинности, она доступна только для приложений, использующих проверку подлинности пользователей. Приложения для проверки подлинности только для приложений не могут получить доступ к этой конечной точке.

Запрос определенных свойств

Функция использует select метод в запросе для указания набора необходимых ей свойств. При этом параметр запроса $select добавляется в вызов API.

Строго типизированный тип возвращаемого значения

Функция возвращает объект, User десериализованный из ответа JSON из API. Так как код использует select, только запрошенные свойства будут иметь значения в возвращаемом объекте User . Все остальные свойства будут иметь значения по умолчанию.

Перечисление папки "Входящие"

Осталось 10 мин

В этом разделе вы добавите возможность выводить список сообщений в папке "Входящие" пользователя.

Откройте graphHelper.ts и добавьте следующую функцию.

export async function getInboxAsync(): Promise<PageCollection> {
  // Ensure client isn't undefined
  if (!_userClient) {
    throw new Error('Graph has not been initialized for user auth');
  }

  return _userClient
    .api('/me/mailFolders/inbox/messages')
    .select(['from', 'isRead', 'receivedDateTime', 'subject'])
    .top(25)
    .orderby('receivedDateTime DESC')
    .get();
}

Замените пустую ListInboxAsync функцию в index.ts на следующую.

async function listInboxAsync() {
  try {
    const messagePage = await graphHelper.getInboxAsync();
    const messages: Message[] = messagePage.value;

    // Output each message's details
    for (const message of messages) {
      console.log(`Message: ${message.subject ?? 'NO SUBJECT'}`);
      console.log(`  From: ${message.from?.emailAddress?.name ?? 'UNKNOWN'}`);
      console.log(`  Status: ${message.isRead ? 'Read' : 'Unread'}`);
      console.log(`  Received: ${message.receivedDateTime}`);
    }

    // If @odata.nextLink is not undefined, there are more messages
    // available on the server
    const moreAvailable = messagePage['@odata.nextLink'] != undefined;
    console.log(`\nMore messages available? ${moreAvailable}`);
  } catch (err) {
    console.log(`Error getting user's inbox: ${err}`);
  }
}

Запустите приложение, войдите в систему и выберите вариант 2, чтобы получить список папки "Входящие".

[1] Display access token
[2] List my inbox
[3] Send mail
[4] Make a Graph call
[0] Exit

Select an option [1...4 / 0]: 2
Message: Updates from Ask HR and other communities
  From: Contoso Demo on Yammer
  Status: Read
  Received: 12/30/2021 4:54:54 AM -05:00
Message: Employee Initiative Thoughts
  From: Patti Fernandez
  Status: Read
  Received: 12/28/2021 5:01:10 PM -05:00
Message: Voice Mail (11 seconds)
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 5:00:46 PM -05:00
Message: Our Spring Blog Update
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:49:46 PM -05:00
Message: Atlanta Flight Reservation
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:35:42 PM -05:00
Message: Atlanta Trip Itinerary - down time
  From: Alex Wilber
  Status: Unread
  Received: 12/28/2021 4:22:04 PM -05:00

...

More messages available? true

Описание кода

Рассмотрим код в getInboxAsync функции.

Доступ к известным почтовым папкам

Функция передается /me/mailFolders/inbox/messages в _userClient.api построитель запросов, который создает запрос к API списка сообщений . Так как он включает часть /mailFolders/inbox конечной точки API, API будет возвращать только сообщения в запрошенной папке почты. В этом случае, так как папка "Входящие" является хорошо известной папкой по умолчанию в почтовом ящике пользователя, она доступна по известному имени. Доступ к папкам, не используемым по умолчанию, можно получить таким же образом, заменив известное имя свойством идентификатора почтовой папки. Дополнительные сведения о доступных известных именах папок см. в разделе Тип ресурса mailFolder.

Доступ к коллекции

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

Размеры страниц по умолчанию

API, использующие разбиение на страницы, реализуют размер страницы по умолчанию. Для сообщений значение по умолчанию — 10. Клиенты могут запрашивать больше (или меньше) с помощью параметра запроса $top . В getInboxAsyncэто выполняется с помощью .top(25) метода .

Примечание.

Значение, передаваемое в .top() , является верхней границей, а не явным числом. API возвращает количество сообщений до указанного значения.

Получение последующих страниц

Если на сервере доступно больше результатов, ответы коллекции содержат @odata.nextLink свойство с URL-адресом API для доступа к следующей странице. Клиентская библиотека JavaScript предоставляет это свойство объектам PageCollection . Если это свойство не определено, доступны дополнительные результаты.

Значение @odata.nextLink можно передать _userClient.api в , чтобы получить следующую страницу результатов. Кроме того, можно использовать PageIterator объект из клиентской библиотеки для итерации всех доступных страниц.

Сортировка коллекций

Функция использует orderby метод в запросе для запроса результатов, отсортированных по времени получения сообщения (receivedDateTime свойство). Он включает ключевое DESC слово, чтобы сообщения, полученные в последнее время, отображались первыми. При этом параметр запроса $orderby добавляется в вызов API.

Отправка почты

Осталось 7 мин

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

Откройте graphHelper.ts и добавьте следующую функцию.

export async function sendMailAsync(
  subject: string,
  body: string,
  recipient: string,
) {
  // Ensure client isn't undefined
  if (!_userClient) {
    throw new Error('Graph has not been initialized for user auth');
  }

  // Create a new message
  const message: Message = {
    subject: subject,
    body: {
      content: body,
      contentType: 'text',
    },
    toRecipients: [
      {
        emailAddress: {
          address: recipient,
        },
      },
    ],
  };

  // Send the message
  return _userClient.api('me/sendMail').post({ message: message });
}

Замените пустую sendMailAsync функцию в index.ts на следующую.

async function sendMailAsync() {
  try {
    // Send mail to the signed-in user
    // Get the user for their email address
    const user = await graphHelper.getUserAsync();
    const userEmail = user?.mail ?? user?.userPrincipalName;

    if (!userEmail) {
      console.log("Couldn't get your email address, canceling...");
      return;
    }

    await graphHelper.sendMailAsync(
      'Testing Microsoft Graph',
      'Hello world!',
      userEmail,
    );
    console.log('Mail sent.');
  } catch (err) {
    console.log(`Error sending mail: ${err}`);
  }
}

Запустите приложение, войдите в систему и выберите вариант 3, чтобы отправить себе сообщение электронной почты.
```
[1] Display access token
[2] List my inbox
[3] Send mail
[4] Make a Graph call
[0] Exit

Select an option [1...4 / 0]: 3
Mail sent.
```
Примечание.

Если вы тестируете с помощью клиента разработчика из Программы разработчика Microsoft 365, отправленное сообщение электронной почты может не быть доставлено, и вы можете получить отчет о недоставки. Если это случится с вами, обратитесь в службу поддержки через Центр администрирования Microsoft 365.
Чтобы убедиться, что сообщение получено, выберите вариант 2, чтобы получить список папки "Входящие".

Описание кода

Рассмотрим код в sendMailAsync функции.

Отправка почты

Функция передается /me/sendMail в _userClient.api построитель запросов, который создает запрос к API отправки почты . Построитель запросов принимает объект, Message представляющий сообщение для отправки.

Создание объектов

В отличие от предыдущих вызовов Microsoft Graph, которые считывают только данные, этот вызов создает данные. Для этого с помощью клиентской библиотеки вы создаете экземпляр класса , представляющего данные (в данном случае ), Messageзадаете нужные свойства, а затем отправляете их в вызове API. Так как вызов отправляет данные, post вместо используется getметод .

Необязательно: добавление собственного кода

Осталось 5 мин

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

Обновите приложение

Откройте graphHelper.ts и добавьте следующую функцию.

// This function serves as a playground for testing Graph snippets
// or other code
export async function makeGraphCallAsync() {
  // INSERT YOUR CODE HERE
}

Замените пустую makeGraphCallAsync функцию в index.ts на следующую.

async function makeGraphCallAsync() {
  try {
    await graphHelper.makeGraphCallAsync();
  } catch (err) {
    console.log(`Error making Graph call: ${err}`);
  }
}

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить запрос API в Graph Explorer и использовать созданный фрагмент кода.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.

Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная), добавьте требуемую область разрешений в appSettings.ts.
Чтобы вызвать API с проверкой подлинности только для приложений, ознакомьтесь с руководством по проверке подлинности только для приложений .

Добавление кода

Скопируйте код в функцию makeGraphCallAsync в graphHelper.ts. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте client_userClientв .

Поделиться через

Создание приложений TypeScript с помощью Microsoft Graph

Предварительные условия

Регистрация приложения на портале

Регистрация приложения для проверки подлинности пользователей

Создание консольного приложения TypeScript

Установка зависимостей

Загрузка параметров приложения

Проектирование приложения

Добавление проверки подлинности пользователя

Настройка клиента Graph для проверки подлинности пользователей

Тестирование DeviceCodeCredential

Получение пользователя

Описание кода

Доступ к "мне"

Запрос определенных свойств

Строго типизированный тип возвращаемого значения

Перечисление папки "Входящие"

Описание кода

Доступ к известным почтовым папкам

Доступ к коллекции

Размеры страниц по умолчанию

Получение последующих страниц

Сортировка коллекций

Отправка почты

Описание кода

Отправка почты

Создание объектов

Необязательно: добавление собственного кода

Обновите приложение

Выбор API

Настройка разрешений

Добавление кода

Поздравляем!

Microsoft Graph Toolkit

Примеры TypeScript и JavaScript