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

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

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

Примечание.

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

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

Совет

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

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

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

Перед началом работы с этим руководством на компьютере разработки должен быть установлен пакет SDK для .NET .

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

Примечание.

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

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

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

В этом упражнении вы зарегистрируете новое приложение в 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 для регистрации приложения. Это связано с тем, что в примере используется динамическое согласие для запроса определенных разрешений для проверки подлинности пользователя.

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

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

Начните с создания консольного проекта .NET с помощью интерфейса командной строки .NET.

Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.
```
dotnet new console -o GraphTutorial
```
После создания проекта убедитесь, что он работает, изменив текущий каталог на каталог GraphTutorial и выполнив следующую команду в интерфейсе командной строки.
```
dotnet run
```
Если это работает, приложение должно вывести .Hello, World!

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

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

Пакеты конфигурации .NET для чтения конфигурации приложения из appsettings.json.
Клиентская библиотека удостоверений Azure для .NET для проверки подлинности пользователя и получения маркеров доступа.
Клиентская библиотека Microsoft Graph .NET для выполнения вызовов к Microsoft Graph.

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

dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph

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

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

Создайте файл в каталоге GraphTutorialс именем appsettings.json и добавьте следующий код.

{
  "settings": {
    "clientId": "YOUR_CLIENT_ID_HERE",
    "tenantId": "common",
    "graphUserScopes": [
      "user.read",
      "mail.read",
      "mail.send"
    ]
  }
}

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

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

Совет

При необходимости эти значения можно задать в отдельном файле с именем appsettings. Development.json или в диспетчере секретов .NET.

Обновите GraphTutorial.csproj , чтобы скопировать appsettings.json в выходной каталог. Добавьте следующий код между строками <Project> и </Project> .
```
<ItemGroup>
  <None Include="appsettings*.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>
```

Создайте файл в каталоге GraphTutorialс именем Settings.cs и добавьте следующий код.

using Microsoft.Extensions.Configuration;

public class Settings
{
    public string? ClientId { get; set; }
    public string? TenantId { get; set; }
    public string[]? GraphUserScopes { get; set; }

    public static Settings LoadSettings()
    {
        // Load settings
        IConfiguration config = new ConfigurationBuilder()
            // appsettings.json is required
            .AddJsonFile("appsettings.json", optional: false)
            // appsettings.Development.json" is optional, values override appsettings.json
            .AddJsonFile($"appsettings.Development.json", optional: true)
            // User secrets are optional, values override both JSON files
            .AddUserSecrets<Program>()
            .Build();

        return config.GetRequiredSection("Settings").Get<Settings>() ??
            throw new Exception("Could not load app settings. See README for configuration instructions.");
    }
}

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

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

Откройте ./Program.cs и замените все его содержимое следующим кодом.

Console.WriteLine(".NET Graph Tutorial\n");

var settings = Settings.LoadSettings();

// Initialize Graph
InitializeGraph(settings);

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

int choice = -1;

while (choice != 0)
{
    Console.WriteLine("Please choose one of the following options:");
    Console.WriteLine("0. Exit");
    Console.WriteLine("1. Display access token");
    Console.WriteLine("2. List my inbox");
    Console.WriteLine("3. Send mail");
    Console.WriteLine("4. Make a Graph call");

    try
    {
        choice = int.Parse(Console.ReadLine() ?? string.Empty);
    }
    catch (System.FormatException)
    {
        // Set to invalid value
        choice = -1;
    }

    switch(choice)
    {
        case 0:
            // Exit the program
            Console.WriteLine("Goodbye...");
            break;
        case 1:
            // Display access token
            await DisplayAccessTokenAsync();
            break;
        case 2:
            // List emails from user's inbox
            await ListInboxAsync();
            break;
        case 3:
            // Send an email message
            await SendMailAsync();
            break;
        case 4:
            // Run any Graph code
            await MakeGraphCallAsync();
            break;
        default:
            Console.WriteLine("Invalid choice! Please try again.");
            break;
    }
}

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

void InitializeGraph(Settings settings)
{
    // TODO
}

async Task GreetUserAsync()
{
    // TODO
}

async Task DisplayAccessTokenAsync()
{
    // TODO
}

async Task ListInboxAsync()
{
    // TODO
}

async Task SendMailAsync()
{
    // TODO
}

async Task MakeGraphCallAsync()
{
    // TODO
}

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

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

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

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

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

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

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

Создайте файл в каталоге GraphTutorial с именем GraphHelper.cs и добавьте в этот файл следующий код.
```
using Azure.Core;
using Azure.Identity;
using Microsoft.Graph;
using Microsoft.Graph.Models;
using Microsoft.Graph.Me.SendMail;

class GraphHelper
{
}
```

Добавьте приведенный ниже код в класс GraphHelper.

// Settings object
private static Settings? _settings;
// User auth token credential
private static DeviceCodeCredential? _deviceCodeCredential;
// Client configured with user authentication
private static GraphServiceClient? _userClient;

public static void InitializeGraphForUserAuth(Settings settings,
    Func<DeviceCodeInfo, CancellationToken, Task> deviceCodePrompt)
{
    _settings = settings;

    var options = new DeviceCodeCredentialOptions
    {
        ClientId = settings.ClientId,
        TenantId = settings.TenantId,
        DeviceCodeCallback = deviceCodePrompt,
    };

    _deviceCodeCredential = new DeviceCodeCredential(options);

    _userClient = new GraphServiceClient(_deviceCodeCredential, settings.GraphUserScopes);
}

Замените пустую InitializeGraph функцию в Program.cs на следующую.

void InitializeGraph(Settings settings)
{
    GraphHelper.InitializeGraphForUserAuth(settings,
        (info, cancel) =>
        {
            // Display the device code message to
            // the user. This tells them
            // where to go to sign in and provides the
            // code to use.
            Console.WriteLine(info.Message);
            return Task.FromResult(0);
        });
}

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

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

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

Добавьте к классу GraphHelper следующую функцию:

public static async Task<string> GetUserTokenAsync()
{
    // Ensure credential isn't null
    _ = _deviceCodeCredential ??
        throw new System.NullReferenceException("Graph has not been initialized for user auth");

    // Ensure scopes isn't null
    _ = _settings?.GraphUserScopes ?? throw new System.ArgumentNullException("Argument 'scopes' cannot be null");

    // Request token with given scopes
    var context = new TokenRequestContext(_settings.GraphUserScopes);
    var response = await _deviceCodeCredential.GetTokenAsync(context);
    return response.Token;
}

Замените пустую DisplayAccessTokenAsync функцию в Program.cs на следующую.

async Task DisplayAccessTokenAsync()
{
    try
    {
        var userToken = await GraphHelper.GetUserTokenAsync();
        Console.WriteLine($"User token: {userToken}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting user access token: {ex.Message}");
    }
}

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

.NET Graph Tutorial

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
1
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
enter the code RB2RUD56D to authenticate.

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

Важно!

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

Совет

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

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

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

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

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

public static Task<User?> GetUserAsync()
{
    // Ensure client isn't null
    _ = _userClient ??
        throw new System.NullReferenceException("Graph has not been initialized for user auth");

    return _userClient.Me.GetAsync((config) =>
    {
        // Only request specific properties
        config.QueryParameters.Select = new[] {"displayName", "mail", "userPrincipalName" };
    });
}

Замените пустую GreetUserAsync функцию в Program.cs на следующую.

async Task GreetUserAsync()
{
    try
    {
        var user = await GraphHelper.GetUserAsync();
        Console.WriteLine($"Hello, {user?.DisplayName}!");
        // For Work/school accounts, email is in Mail property
        // Personal accounts, email is in UserPrincipalName
        Console.WriteLine($"Email: {user?.Mail ?? user?.UserPrincipalName ?? ""}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting user: {ex.Message}");
    }
}

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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

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

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

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

public static Task<MessageCollectionResponse?> GetInboxAsync()
{
    // Ensure client isn't null
    _ = _userClient ??
        throw new System.NullReferenceException("Graph has not been initialized for user auth");

    return _userClient.Me
        // Only messages from Inbox folder
        .MailFolders["Inbox"]
        .Messages
        .GetAsync((config) =>
        {
            // Only request specific properties
            config.QueryParameters.Select = new[] { "from", "isRead", "receivedDateTime", "subject" };
            // Get at most 25 results
            config.QueryParameters.Top = 25;
            // Sort by received time, newest first
            config.QueryParameters.Orderby = new[] { "receivedDateTime DESC" };
        });
}

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

async Task ListInboxAsync()
{
    try
    {
        var messagePage = await GraphHelper.GetInboxAsync();

        if (messagePage?.Value == null)
        {
            Console.WriteLine("No results returned.");
            return;
        }

        // Output each message's details
        foreach (var message in messagePage.Value)
        {
            Console.WriteLine($"Message: {message.Subject ?? "NO SUBJECT"}");
            Console.WriteLine($"  From: {message.From?.EmailAddress?.Name}");
            Console.WriteLine($"  Status: {(message.IsRead!.Value ? "Read" : "Unread")}");
            Console.WriteLine($"  Received: {message.ReceivedDateTime?.ToLocalTime().ToString()}");
        }

        // If NextPageRequest is not null, there are more messages
        // available on the server
        // Access the next page like:
        // var nextPageRequest = new MessagesRequestBuilder(messagePage.OdataNextLink, _userClient.RequestAdapter);
        // var nextPage = await nextPageRequest.GetAsync();
        var moreAvailable = !string.IsNullOrEmpty(messagePage.OdataNextLink);

        Console.WriteLine($"\nMore messages available? {moreAvailable}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting user's inbox: {ex.Message}");
    }
}

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

Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
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 функции.

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

Функция использует построитель _userClient.Me.MailFolders["Inbox"].Messages запросов, который создает запрос к API списка сообщений . Так как он включает построитель MailFolders["Inbox"] запросов, API возвращает только сообщения в запрошенной папке почты. В этом случае, так как папка "Входящие" является хорошо известной папкой по умолчанию в почтовом ящике пользователя, она доступна по известному имени. Доступ к папкам, не используемым по умолчанию, можно получить таким же образом, заменив известное имя свойством идентификатора почтовой папки. Дополнительные сведения о доступных известных именах папок см. в разделе Тип ресурса mailFolder.

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

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

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

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

Примечание.

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

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

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

Свойство NextPageRequest предоставляет метод, GetAsync который возвращает следующую страницу.

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

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

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

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

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

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

public static async Task SendMailAsync(string subject, string body, string recipient)
{
    // Ensure client isn't null
    _ = _userClient ??
        throw new System.NullReferenceException("Graph has not been initialized for user auth");

    // Create a new message
    var message = new Message
    {
        Subject = subject,
        Body = new ItemBody
        {
            Content = body,
            ContentType = BodyType.Text
        },
        ToRecipients = new List<Recipient>
        {
            new Recipient
            {
                EmailAddress = new EmailAddress
                {
                    Address = recipient
                }
            }
        }
    };

    // Send the message
    await _userClient.Me
        .SendMail
        .PostAsync(new SendMailPostRequestBody
        {
            Message = message
        });
}

Замените пустую SendMailAsync функцию в Program.cs на следующую.

async Task SendMailAsync()
{
    try
    {
        // Send mail to the signed-in user
        // Get the user for their email address
        var user = await GraphHelper.GetUserAsync();

        var userEmail = user?.Mail ?? user?.UserPrincipalName;

        if (string.IsNullOrEmpty(userEmail))
        {
            Console.WriteLine("Couldn't get your email address, canceling...");
            return;
        }

        await GraphHelper.SendMailAsync("Testing Microsoft Graph",
            "Hello world!", userEmail);

        Console.WriteLine("Mail sent.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error sending mail: {ex.Message}");
    }
}

Запустите приложение, войдите в систему и выберите вариант 3, чтобы отправить себе сообщение электронной почты.
```
Please choose one of the following options:
0. Exit
1. Display access token
2. List my inbox
3. Send mail
4. Make a Graph call
3
Mail sent.
```
Примечание.

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

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

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

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

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

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

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

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

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

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

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

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

// This function serves as a playground for testing Graph snippets
// or other code
public async static Task MakeGraphCallAsync()
{
    // INSERT YOUR CODE HERE
}

Замените пустую MakeGraphCallAsync функцию в Program.cs на следующую.
```
async Task MakeGraphCallAsync()
{
    await GraphHelper.MakeGraphCallAsync();
}
```

Выбор API

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

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

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

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

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

Скопируйте код в функцию MakeGraphCallAsync в GraphHelper.cs. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте GraphServiceClient_userClientв .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выбор API

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

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

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

Примеры .NET