Керування поштовими скриньками з Microsoft Graph та .NET API

• Презентація Microsoft Graph
• Про бібліотеку Aspose.Email для .NET
• Налаштуйте свій додаток на порталі Azure
• Отримайте токен доступу та ініціалізуйте GraphClient
  • Крок 1: Налаштування конфігураційного файлу
  • Крок 2: Відображення конфігурації JSON на об’єкт C#
  • Крок 3: Отримання токена доступу
  • Крок 4: Ініціалізація GraphClient
• Отримати ієрархію папок та отримати папки за назвою
  • Крок 1: Розуміння ієрархії папок
    • Навігація по структурі папок
  • Крок 2: Отримання ієрархії папок
  • Крок 3: Отримання папок за назвою
• Перелік повідомлень у зазначеній папці

Інтеграція Microsoft Graph API та бібліотеки Aspose.Email для .NET з електронним додатком дозволяє розробникам легко отримувати та маніпулювати даними поштових скриньок, виконувати операції, такі як отримання повідомлень, отримання ієрархії папок та збереження електронних листів у різних форматах. У цій статті ми розглянемо, як використовувати цю потужну комбінацію для обробки та керування поштовими скриньками.

Презентація Microsoft Graph

Microsoft Graph — це комплексна платформа API, надана Microsoft, яка пропонує єдину точку доступу до широкого спектру послуг та даних Microsoft. Вона слугує шлюзом до величезних даних, доступних у Microsoft 365, включаючи поштові скриньки Outlook, календарі, контакти, OneDrive, Teams та інше.

З Microsoft Graph розробники можуть створювати програми, які безперешкодно взаємодіють з даними користувачів та інсайтами в екосистемі хмари Microsoft. Це досягається через RESTful API та SDK, які надають можливості для аутентифікації, авторизації та запитів даних з легкістю.

Про бібліотеку Aspose.Email для .NET

Aspose.Email для .NET — це функціонально насичена бібліотека, яка дозволяє розробникам працювати з електронними файлами та протоколами у своїх .NET додатках. Вона надає міцний набір API для створення, маніпулювання та конвертації електронних повідомлень у різних форматах, таких як MSG, EML та MBOX. Крім того, бібліотека підтримує електронні протоколи, такі як SMTP, POP3 та IMAP, що дозволяє універсальне управління електронною поштою.

У цьому посібнику ми використаємо Aspose.Email для взаємодії з Microsoft Graph, програмно обробляючи дані поштової скриньки. З GraphClient від Aspose.Email ми можемо ефективно виконувати операції з поштовими скриньками, аутентифікуючись з Microsoft Graph.

Щоб почати використовувати бібліотеку, вам потрібно інтегрувати її у свій проект. Найпростіший спосіб отримати Aspose.Email для .NET — це через диспетчер пакетів NuGet:

• Відкрийте свій проект у Visual Studio.
• Перейдіть до Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
• Шукайте Aspose.Email.
• Виберіть пакет і натисніть Install.

Альтернативно, ви можете використовувати Консоль диспетчера пакетів:

Install-Package Aspose.Email

Ви також можете завантажити останню версію API безпосередньо з веб-сайту Aspose.

Налаштуйте свій додаток на порталі Azure

Перед тим, як перейти до коду, важливо налаштувати ваш додаток у порталі Azure, щоб дозволити доступ до Microsoft Graph. Просто виконайте ці кроки:

1. Створіть додаток Azure Active Directory (AAD):

   • Перейдіть до Azure Portal.
   • Перейдіть до Azure Active Directory > Реєстрація додатків.
   • Натисніть Нова реєстрація, щоб створити новий додаток.
   • Введіть ім’я та налаштуйте URI перенаправлення, якщо потрібно.
   • Натисніть Зареєструвати, щоб завершити процес.

2. Встановіть дозволи API:

   • У вашому зареєстрованому додатку перейдіть до Дозволи API.
   • Натисніть Додати дозвіл > Microsoft Graph.
   • Виберіть Дозволи додатка для серверних викликів.
   • Виберіть необхідні дозволи, такі як Mail.Read, Mail.ReadWrite, User.Read тощо.
   • Натисніть Додати дозволи, щоб застосувати.

3. Створіть секрет клієнта:

   • Перейдіть до Сертифікати та секрети у вашому додатку.
   • Натисніть Новий секрет клієнта та надайте опис.
   • Встановіть період закінчення терміну дії, потім натисніть Додати.
   • Збережіть згенероване значення секрету клієнта, оскільки вам знадобиться пізніше.

4. Зберіть значення конфігурації:

   • Отримайте ID орендаря, ID клієнта та Секрет клієнта зі сторінки огляду вашого додатку та секції секретів.
   • Ці значення знадобляться для аутентифікації та взаємодії з Microsoft Graph.

Після налаштування вашого додатку ви готові перейти до розробки.

Отримайте токен доступу та ініціалізуйте GraphClient

Перед тим, як заглибитися у операції з поштовими скриньками, нам потрібно відкрити двері до величезної екосистеми даних та послуг Microsoft Graph. Цей доступ надається через токен доступу OAuth 2.0 — цифровий ключ, який авторизує ваш додаток для взаємодії з Microsoft Graph від імені користувача або служби. Уявіть це як безпечний пропуск, який надає вам доступ до цілого всесвіту можливостей, від отримання електронних листів до управління контактами та багато іншого.

Крок 1: Налаштування конфігураційного файлу

Перший крок у отриманні токена — це налаштування конфігураційного файлу, який зберігає важливі деталі, такі як ID орендаря, ID клієнта та Секрет клієнта вашого додатку. Ці значення є обліковими даними вашого додатку та служать ідентифікаторами при спілкуванні з серверами Microsoft.

Ось як може виглядати ваша конфігурація JSON:

{
    "Instance": "https://login.microsoftonline.com/{0}",
    "ApiUrl": "https://graph.microsoft.com/.default",
    "TenantId": "YOUR_TENANT_ID_HERE",
    "ClientId": "YOUR_APP_ID_HERE",
    "ClientSecret": "YOUR_CLIENT_SECRET_HERE",
    "UserId": "YOUR_ID_HERE"
}

Крок 2: Відображення конфігурації JSON на об’єкт C#

Тепер давайте перетворимо цю конфігурацію на об’єкт C#, який наш додаток може використовувати. Ми прочитаємо JSON файл та відобразимо його вміст на клас AuthenticationConfig, переконавшись, що наш додаток знає, де знайти критично важливу інформацію, яка йому потрібна.

class AuthenticationConfig
{
    public string Instance { get; set; }
    public string ApiUrl { get; set; }
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string UserId { get; set; }
    public string Authority => string.Format(CultureInfo.InvariantCulture, Instance, TenantId);
    public string ClientSecret { get; set; }
    
    public static AuthenticationConfig ReadFromJsonFile(string path)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile(path);

        var configuration = builder.Build();
        return configuration.Get<AuthenticationConfig>();
    }
}

Крок 3: Отримання токена доступу

З нашою конфігурацією на місці, настав час отримати токен доступу. Ми реалізуємо клас GraphTokenProvider, який обробляє процес аутентифікації за допомогою Microsoft Authentication Library (MSAL). Цей клас займається важкою роботою — спілкуванням з Microsoft Graph для отримання токена, який надає можливості нашому додатку.

class GraphTokenProvider : ITokenProvider
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes;
    private string? _token;
    
    public GraphTokenProvider(AuthenticationConfig config)
    {
        _app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
            .WithClientSecret(config.ClientSecret)
            .WithAuthority(config.Authority)
            .Build();

        // In memory token caches (App and User caches)
        _app.AddInMemoryTokenCache();
        
        _scopes = new[] { config.ApiUrl }; 
    }

    public void Dispose()
    {
        throw new NotImplementedException();
    }

    public OAuthToken GetAccessToken()
    {
        return GetAccessToken(false);
    }

    public OAuthToken GetAccessToken(bool ignoreExistingToken)
    {
        if (!ignoreExistingToken && _token != null)
        {
            return new OAuthToken(_token);
        }

        _token = GetAccessTokenAsync().GetAwaiter().GetResult();
        return new OAuthToken(_token);
    }
    
    private async Task<string?> GetAccessTokenAsync()
    {
        AuthenticationResult? result;
        
        try
        {
            result = await _app.AcquireTokenForClient(_scopes)
                .ExecuteAsync();
            
            Console.WriteLine($"Токен отримано з {result.AuthenticationResultMetadata.TokenSource} {Environment.NewLine}");
        }
        catch (MsalServiceException ex)
        {
            Console.WriteLine($"Помилка при отриманні токена:{Environment.NewLine}{ex}{Environment.NewLine}");
            result = null;
        }

        if (result == null) return null;
        _token = result.AccessToken;
        return result.AccessToken;
    }
}

Крок 4: Ініціалізація GraphClient

Нарешті, ми ініціалізуємо GraphClient, використовуючи отриманий токен. GraphClient виступає нашим мостом до Microsoft Graph, дозволяючи нам безперешкодно взаємодіяти з поштовими скриньками користувачів.

var config = AuthenticationConfig.ReadFromJsonFile("appsettings.json");
var tokenProvider = new GraphTokenProvider(config);

using var client = GraphClient.GetClient(tokenProvider, config.TenantId);
client.Resource = ResourceType.Users;
client.ResourceId = config.UserId;

Отримати ієрархію папок та отримати папки за назвою

Як тільки ви отримали доступ до Microsoft Graph, настав час почати дослідження поштової скриньки. У цьому розділі ми заглибимося в отримання та навігацію по ієрархії папок поштової скриньки, що дозволяє вам отримувати конкретні папки за назвою.

Крок 1: Розуміння ієрархії папок

Навігація по структурі папок

Поштові скриньки мають ієрархічну структуру, подібну до дерева. Коренева папка розгалужується на кілька підпапок, кожна з яких містить свій набір електронних листів і, можливо, ще більше підпапок. Ця вкладена структура дозволяє організовано керувати та легко навігувати електронною поштою.

Давайте визначимо та використаємо клас FolderNode, щоб представляти кожну папку в ієрархії:

// Представляє вузол у ієрархії папок,
// розширюючи властивості FolderInfo та зберігаючи колекцію підпапок.
class FolderNode
{
    // Отримує об'єкт FolderInfo, що представляє інформацію про папку.
    public FolderInfo Folder { get; }
    
    // Отримує колекцію підпапок, що містяться в поточній папці.
    public List<FolderNode?> SubFolders { get; }

    // Ініціалізує новий екземпляр класу FolderNode з вказаним об'єктом FolderInfo.
    public FolderNode(FolderInfo folder)
    {
        Folder = folder;
        SubFolders = new List<FolderNode?>();
    }
    
    // Друкує всі папки в ієрархічному вигляді, починаючи з поточного вузла.
    public void PrintHierarchy()
    {
        PrintFolderNode(this, 0);
    }

    private void PrintFolderNode(FolderNode node, int indentLevel)
    {
        // Друкує поточний вузол папки з відступом
        Console.WriteLine($"{new string(' ', indentLevel * 2)}{node}");

        // Рекурсивно друкує підпапки
        foreach (var subFolder in node.SubFolders)
        {
            PrintFolderNode(subFolder, indentLevel + 1);
        }
    }

    // Отримує відображення назви папки.
    public override string ToString()
    {
        return $"{Folder.DisplayName} ({Folder.ContentCount})";
    }
}

Щоб отримати всю ієрархію папок, ми створимо клас FolderHierarchy, який використовує GraphClient, щоб перерахувати всі папки рекурсивно. Ось як це працює:

static class FolderHierarchy
{
    // Отримує всі папки в поштовій скриньці рекурсивно та повертає ієрархічну колекцію об'єктів FolderNode.
    public static List<FolderNode> Retrieve(IGraphClient client)
    {
        // Отримати кореневі папки
        var rootFolders = client.ListFolders();
        var allFolders = new List<FolderNode>();

        // Отримати підпапки рекурсивно
        foreach (var folder in rootFolders)
        {
            var folderNode = new FolderNode(folder);
            RetrieveSubFolders(client, folderNode);
            allFolders.Add(folderNode);
        }

        return allFolders;
    }

    // Отримує підпапки рекурсивно та додає їх до властивості SubFolders батьківського FolderNode.
    private static void RetrieveSubFolders(IGraphClient client, FolderNode parentFolderNode)
    {
        if (parentFolderNode.Folder.HasSubFolders)
        {
            var subFolders = client.ListFolders(parentFolderNode.Folder.ItemId);
            
            foreach (var subFolder in subFolders)
            {
                var subFolderNode = new FolderNode(subFolder);
                RetrieveSubFolders(client, subFolderNode);
                parentFolderNode.SubFolders.Add(subFolderNode);
            }
        }
    }
}

Крок 2: Отримання ієрархії папок

Використовуючи метод FolderHierarchy.Retrieve, ви можете без зусиль пройти через поштову скриньку, щоб виявити її структуру папок. Ось як ви можете це зробити:

// Отримати ієрархію папок з поштової скриньки
var folderNodes = FolderHierarchy.Retrieve(client);

// Друкуємо ієрархію папок у структурованому форматі
foreach (var folderNode in folderNodes)
{
    folderNode.PrintHierarchy();
}

Крок 3: Отримання папок за назвою

Якщо ви отримали ієрархію папок, ви можете швидко знайти конкретні папки за назвою. Чи цікавить вас доступ до Вхідних повідомлень або будь-якої користувацької папки, цей метод забезпечує швидке їх виявлення:

// Вкажіть назву папки, яку ви шукаєте
string targetFolderName = "Вхідні";

// Знайдіть цільову папку за назвою
var targetFolder = folderNodes.FirstOrDefault(
    folderNode => folderNode.Folder.DisplayName.Equals(targetFolderName, StringComparison.OrdinalIgnoreCase))
    ?.Folder;

Перелік повідомлень у зазначеній папці

Отримавши успішно ієрархію папок, наступним кроком є заглиблення в зміст конкретних папок. Уявіть, що ви навігаєте до своїх Вхідних; тепер ви хочете переглянути всі повідомлення, які вона містить.

У цьому розділі ми розглянемо, як перерахувати повідомлення в межах певної папки, використовуючи GraphClient та Aspose.Email для .NET.

Якщо у вас вже є папка, перелік повідомлень у ній є досить простим. GraphClient надає метод ListMessages для отримання всіх повідомлень у папці, які ви потім можете обробити або відобразити.

Ось код для переліку повідомлень зі зазначеної папки:

Console.WriteLine("Перелік повідомлень у зазначеній папці...");

// Викликаємо метод клієнта для переліку повідомлень у вибраній папці
var messageInfoCollection = client.ListMessages(targetFolder.ItemId);

Console.WriteLine($"{targetFolderName}:");

// Друкуємо теми повідомлень
foreach (var messageInfo in messageInfoCollection)
{
    Console.WriteLine($"     - {messageInfo.Subject}");
}

messageInfoCollection містить основну інформацію про кожен електронний лист. Цю інформацію можна використовувати для відображення резюме, генерування звітів або навіть тригера сповіщень на основі конкретних критеріїв.

Висновок

У цій статті ми дослідили, як використовувати можливості Microsoft Graph і бібліотеки Aspose.Email для .NET для ефективної обробки поштових скриньок, навігації по ієрархіях папок і переліку повідомлень у конкретних папках. Дотримуючись цих кроків, ви можете створити надійні програми, які безперешкодно взаємодіють з даними електронної пошти, надаючи покращену функціональність та користувацький досвід.

Концепції в дії

Якщо ви прагнете побачити ці концепції в дії, ви можете завантажити повнофункціональний приклад робочого додатку. Цей додаток містить вихідний код, описаний у цій статті, і демонструє, як реалізувати ці функції крок за кроком.

Відвідайте наш репозиторій на GitHub, щоб отримати доступ до прикладного додатку: Aspose.Email для .NET - Приклад GraphApp.

Обробка поштових скриньок через Microsoft Graph пропонує безпрецедентний доступ до даних електронної пошти та можливостей управління. З правильними інструментами та техніками ви можете створити складні програми, які надають значущі інсайти та автоматизують складні завдання, врешті-решт підвищуючи продуктивність та задоволення користувачів.

Спробуйте безкоштовно

Крім того, Aspose.Email надає всебічну документацію, розширену API-довідку та різноманітні безкоштовні онлайн-інструменти та додатки для покращення вашого процесу розробки. Розробники також можуть отримати доступ до безкоштовного форуму підтримки для отримання допомоги та інсайтів від спільноти, а також залишатися в курсі останніх порад і навчальних посібників через блог Aspose блог.

Дивіться також

• Підключення до поштової скриньки Microsoft365 за допомогою сучасної аутентифікації в C# .NET
• Створення та надсилання повідомлень за допомогою Microsoft Graph API в C#