Доступ до даних Microsoft 365 та управління за допомогою Microsoft Graph

Оптимізуйте доступ та управління даними Microsoft 365 за допомогою Aspose.Email Graph Client

Microsoft Graph це REST API для доступу до даних Microsoft 365. Реалізація Graph Client у Aspose.Email для .NET дозволяє доступ до Microsoft Graph з нашого API. У наведених нижче прикладах ми створимо екземпляр MS Graph Client, передаючи токен. Потім розглянемо основні методи управління папками, їх оновлення, копіювання та видалення. Повідомлення, їх вміст та вкладення також можна отримувати або змінювати за допомогою нашого MS Graph Client. Управління категоріями, правилами, блокнотами та перевизначеннями є розширеною функцією Microsoft Graph Client від Aspose.Email.

Автентифікація та запит з IGraphClient за допомогою MSAL у .NET

Щоб взаємодіяти зі службами Microsoft Graph, вам потрібно створити IGraphClient об’єкт. Після автентифікації цей клієнт дозволяє виконувати різні запити сервісу. The GetClient метод, який створює IGraphClient, вимагає ITokenProvider реалізацію як перший параметр. Це ITokenProvider відповідає за надання необхідного токена автентифікації. Щоб отримати токен, ми використаємо Microsoft Authentication Library (MSAL) для .NET.

Ось як налаштувати процес автентифікації:

Крок 1: Налаштування автентифікації

Наступні кроки допоможуть вам отримати токен авторизації:

1. Створіть клас AccessParameters.

   Визначте клас AccessParameters для зберігання ваших облікових даних.

public class AccessParameters
{
    public string TenantId { get; init; }
    public string ClientId { get; init; }
    public string ClientSecret { get; init; }
    public string UserId { get; init; }
    public Uri Authority => new ($"https://login.microsoftonline.com/{TenantId}");
    public string ApiUrl => "https://graph.microsoft.com/.default";
}

2. Додайте Пакет MSAL.NET.

   Встановіть Microsoft.Identity.Client Пакет NuGet, який містить бінарники MSAL.NET, необхідні для аутентифікації.

3. Реалізуйте інтерфейс ITokenProvider.

   Створіть GraphTokenProvider клас, який реалізує ITokenProvider інтерфейс. Цей клас буде використовувати бібліотеку MSAL.NET для отримання токена доступу.

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Aspose.Email.Clients;

public class GraphTokenProvider : ITokenProvider
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes;
    private string? _token;

    public GraphTokenProvider(AccessParameters accessParams)
    {
        _app = ConfidentialClientApplicationBuilder.Create(accessParams.ClientId)
            .WithClientSecret(accessParams.ClientSecret)
            .WithAuthority(accessParams.Authority)
            .Build();

        _app.AddInMemoryTokenCache();

        _scopes = new[] { accessParams.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("Token acquired");
        }
        catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
        {
            Console.WriteLine("Scope provided is not supported");
            result = null;
        }

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

Крок 2: Створення екземпляру ITokenProvider

Після визначення GraphTokenProvider класу, ви можете створити екземпляр AccessParameters і використайте його для створення екземпляру GraphTokenProvider.

var accessParams = new AccessParameters()
{
    TenantId = "Your Tenant ID",
    ClientId = "Your Client ID",
    ClientSecret = "Your Client Secret",
    UserId = "User's Object ID"
};

var tokenProvider = new GraphTokenProvider(accessParams);

Крок 3: Виконання запитів за допомогою IGraphClient

Нарешті, використайте GraphTokenProvider для створення автентифікованого IGraphClient і починайте робити запити до сервісу.

using var client = GraphClient.GetClient(tokenProvider, accessParams.TenantId);

client.Resource = ResourceType.Users;
client.ResourceId = accessParams.UserId;

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

Підключення до кінцевих точок GCC High

The GraphClient підтримує підключення до кінцевих точок GCC High за допомогою EndPoint властивість. Нижче наведено приклад коду, який демонструє, як налаштувати GraphClient для підключення до кінцевої точки GCC High для отримання списку папок та повідомлень.

client.EndPoint = "https://graph.microsoft.us";

var folders = client.ListFolders();
string folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;
var msgs = client.ListMessages(folderId);

Керування папками за допомогою IGraphClient

Перелік папок

Викликавши ListFolders метод з MS Graph Client, за допомогою якого можна отримати список папок. Кожна папка має набір параметрів, таких як DisplayName, які можна прочитати у FolderInfo тип.

var folders = client.ListFolders();

foreach (var folder in folders)
{
    Console.WriteLine(folder.DisplayName);
}

Оновлення папок

Щоб створити папку за допомогою MS Graph Client, використовуйте CreateFolder метод. Ви отримаєте FolderInfo об’єкт та можливість доступу до DisplayName, ItemId, HasSubFolders та інших властивостей.

var folderInfo = client.CreateFolder("FolderName");
folderInfo.DisplayName = "FolderAnotherName";
client.UpdateFolder(folderInfo);

Копіювання папок

CopyFolder метод є ключовим для копіювання об’єкту папки за допомогою MS Graph.

var folderInfo1 = client.CreateFolder("Folder1");
var folderInfo2 = client.CreateFolder("Folder2");
    
// copy Folder2 to Folder1
client.CopyFolder(folderInfo1.ItemId, folderInfo2.ItemId);

Переміщення та видалення папок

Використати MoveFolder метод використовується для переміщення папки, приймає newParentId та itemId. Delete метод використовується для видалення елементу за його id.

var folderInfo1 = client.CreateFolder("Folder1");
var folderInfo2 = client.CreateFolder("Folder2");
    
// move Folder2 to Folder1
client.MoveFolder(folderInfo1.ItemId, folderInfo2.ItemId);
    
// delete Folder1
client.Delete(folderInfo1.ItemId)

Керування повідомленнями за допомогою IGraphClient

MS Graph Client, реалізований в Aspose.Email для .NET, надає набір методів для керування повідомленнями та вкладеннями:

• List messages
• Fetch message
• Create message
• Надіслати message
• CopyMessage message
• Move message
• CreateAttachment
• FetchAttachment
• DeleteAttachment
• ListAttachments

Список повідомлень

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        foreach (var messageInfo in inboxMessages)
        {
            Console.WriteLine(messageInfo.Subject);
        }
    }
}

Фільтрація повідомлень за датою надсилання

The OrderBy метод з колекції бібліотеки дозволяє отримувати повідомлення з різними порядками сортування (за зростанням та спаданням) згідно дати надсилання. Нижче наведено приклад коду, який показує, як сортувати повідомлення за датою надсилання:

IGraphClient client = GraphClient.GetClient(provider, TenantId);

var builder = new GraphQueryBuilder();

// create orderby messages query 'DESC'
builder.SentDate.OrderBy(false);
var messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
var messages = messagePageInfo.Items;

builder.Clear();

// create orderby messages query 'ASC'
builder.SentDate.OrderBy(true);
messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
messages = messagePageInfo.Items;

Перерахування повідомлень з підтримкою посторінкового отримання

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

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

1. Спочатку ініціалізуйте клієнт.
2. Потім встановіть кількість елементів, що відображаються на сторінці, наприклад, 10.
3. Створіть фільтр, щоб отримувати лише неппрочитані повідомлення, використовуючи GraphQueryBuilder клас. builder.IsRead.Equals(false) встановлює умову для фільтрації неппрочитаних повідомлень.
4. Викличте ListMessages метод у об’єкті клієнта, який вказує папку (Inbox) та кількість елементів на сторінку (PageInfo(itemsPerPage)) як параметри. Також передається об’єкт запиту для застосування фільтра неппрочитаних повідомлень. Повернений об’єкт PageInfo (pageInfo) містить отримані повідомлення для поточної сторінки у властивості Items.
5. Створіть цикл, який продовжується, доки не буде досягнута остання сторінка (pageInfo.LastPage має значення false). Отримані повідомлення додаються до існуючого списку повідомлень за допомогою messages.AddRange(pageInfo.Items).

//  reading unread messages with paging
using var client = GraphClient.GetClient(tokenProvider, config.Tenant);

// paging option
var itemsPerPage = 10;
// create unread messages filter
GraphQueryBuilder builder = new GraphQueryBuilder();
builder.IsRead.Equals(false);
var query = builder.GetQuery();

// list messages
var pageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(itemsPerPage), query);
var  messages = pageInfo.Items;

while (!pageInfo.LastPage)
{
    pageInfo = client.ListMessages(KnownFolders.Inbox, pageInfo.NextPage, query);
    messages.AddRange(pageInfo.Items);
}

// set messages state as read
foreach (var message in messages)
{
    client.SetRead(message.ItemId);
}

Отримання повідомлень

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        if (inboxMessages.Count > 0)
        {
            // fetch the first message in inbox
            var msg = client.FetchMessage(inboxMessages[0].ItemId);
            
            Console.WriteLine(msg.BodyHtml);
        }
        
    }
}

Створення повідомлень

var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);

// create message in inbox
client.CreateMessage(KnownFolders.Inbox, msg);

Надсилання повідомлень

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "[e-mail]");

// send message
client.Send(msg);

Надсилання чернеток повідомлень

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "[e-mail]");

// add message to Draft folder
var draftMessage = client.CreateMessage(KnownFolders.Drafts, msg);

// send a draft message
client.Send(draftMessage.ItemId);

Надсилання EML‑повідомлень

Створення та надсилання електронних листів просте за допомогою об’єкта MailMessage. Нижче наведено приклад коду, який демонструє, як створити та надіслати електронний лист за допомогою Graph API:

// prepare the message
var eml = new MailMessage
{
    From = "[e-mail]",
    To = "[e-mail], [e-mail]",
    Subject = "New message",
    HtmlBody = "<html><body>This is the HTML body</body></html>"
};

// send the message
graphClient.Send(eml);
graphClient.Create(KnownFolders.Inbox, eml);

Копіювання повідомлень

// copy message to Inbox folder
var copiedMsg = client.CopyMessage(KnownFolders.Inbox, msg.ItemId);

Переміщення повідомлень

// move message to Inbox folder
var movedMsg = client.MoveMessage(KnownFolders.Inbox, msg.ItemId);

Керування вкладеннями

// create an attachment
var attachment = new MapiAttachment();
attachment.SetProperty(KnownPropertyList.DisplayName, "My Attachment");
attachment.SetProperty(KnownPropertyList.AttachDataBinary, new byte[1024]);

// add an attachment to message
var createdAttachment = client.CreateAttachment(messageInfo.ItemId, attachment);

// fetch a message attachment
var fetchedAttachment = client.FetchAttachment(createdAttachment.ItemId);

// delete a message attachment 
client.DeleteAttachment(createdAttachment.ItemId);

// list the message attachments
var attachments = client.ListAttachments(messageInfo.ItemId);   

Керування елементами Outlook за допомогою Graph Client

Керування подіями календаря

Aspose.Email надає API для доступу, керування та взаємодії з подіями календаря. Для цих цілей він пропонує наступні методи у IGraphClient interface:

• ListCalendars() — Повертає колекцію інформації про календарі.
• ListCalendarItems(string id) — Повертає колекцію елементів календаря, пов’язаних з вказаним ідентифікатором календаря.
• FetchCalendarItem(string id) — Отримує певний елемент календаря за вказаним ідентифікатором.
• CreateCalendarItem(string calId, MapiCalendar mapiCalendar) — Створює новий елемент календаря у вказаному календарі.
• UpdateCalendarItem(MapiCalendar mapiCalendar) — Оновлює існуючий елемент календаря.
• UpdateCalendarItem(MapiCalendar mapiCalendar, UpdateSettings updateSettings) — Оновлює існуючий елемент календаря з вказаними параметрами оновлення.

Нижче наведено приклад коду, який демонструє взаємодію з подіями календаря у клієнті Microsoft Graph API за допомогою методів, наданих Aspose.Email:

// List Calendars
CalendarInfoCollection calendars = graphClient.ListCalendars();

// List Calendar Items
MapiCalendarCollection calendarItems = graphClient.ListCalendarItems("calendarId");

// Fetch Calendar Item
MapiCalendar calendarItem = graphClient.FetchCalendarItem("calendarItemId");

// Create Calendar Item
MapiCalendar newCalendarItem = new MapiCalendar(
    location: "Conference Room",
    summary: "Team Meeting",
    description: "Discuss project status and updates.",
    startDate: startDate,
    endDate: endDate
);

MapiCalendar createdCalendarItem = graphClient.CreateCalendarItem("calendarId", newCalendarItem);

// Update Calendar Item
createdCalendarItem.Location = "Zoom Meeting";
MapiCalendar updatedCalendarItem = graphClient.UpdateCalendarItem(createdCalendarItem);

Керування категоріями

Щоб керувати категоріями за допомогою MS Graph від Aspose.Email для .NET, використовуйте наступні методи:

• CreateCategory
• FetchCategory
• ListCategories
• UpdateCategory

// create a custom category with Orange color
var category = client.CreateCategory("My custom category", CategoryPreset.Preset1);

// fetch a category
var fetchedCategory = client.FetchCategory(category.Id);

// update category (change color to brown)
fetchedCategory.Preset = CategoryPreset.Preset2;
var updatedCategory = client.UpdateCategory(fetchedCategory);

// list available categories
var categories = client.ListCategories();

foreach (var cat in categories)
{
    Console.WriteLine(cat.DisplayName);
}

// delete a category
client.Delete(fetchedCategory.Id);

Керування контактами

Aspose.Email надає API для доступу, керування та взаємодії з елементами контактів. Для цих цілей він пропонує наступні методи у IGraphClient interface:

• ListContacts(string id) — Повертає колекцію MAPI‑контактів, пов’язаних з вказаним ідентифікатором папки.
• FetchContact(string id) — Отримує певний контакт за вказаним ідентифікатором елемента.
• CreateContact(string folderId, MapiContact contact) — Створює новий контакт у вказаній папці.
• UpdateContact(MapiContact contact) — Оновлює існуючий контакт.

Нижче наведено приклад коду, який демонструє взаємодію з контактами у клієнті Microsoft Graph API за допомогою методів, наданих Aspose.Email:

// List Contacts
MapiContactCollection contacts = graphClient.ListContacts("contactFolderId");

// Fetch Contact
MapiContact contact = graphClient.FetchContact("contactId");

// Create Contact
MapiContact newContact = new MapiContact("Jane Smith", "[e-mail]", "XYZ Corporation", "777-888-999");

MapiContact createdContact = graphClient.CreateContact("contactFolderId", newContact);

// Update Contact
createdContact.Telephones.PrimaryTelephoneNumber = "888-888-999";

MapiContact updatedContact = graphClient.UpdateContact(createdContact);

Керування перевизначеннями

Щоб керувати перевизначеннями за допомогою MS Graph від Aspose.Email для .NET, використовуйте наступні методи:

• CreateOrUpdateOverride
• ListOverrides
• UpdateOverride

// Create an user's override
var userOverride = client.CreateOrUpdateOverride
    (new MailAddress("[e-mail]", "JohnBrown"), ClassificationType.Focused);

// list the overrides
var overrides = client.ListOverrides();

// update override
userOverride.Sender.DisplayName = "John Brown";
var updatedOverride = client.UpdateOverride(userOverride);

// delete override
client.Delete(updatedOverride.Id);

Керування правилами

Щоб керувати правилами за допомогою MS Graph від Aspose.Email для .NET, використовуйте наступні методи:

• CreateRule
• FetchRule
• UpdateRule
• ListRules

// Create a rule
var rule = PrepareRule("[e-mail]", "User");
var createdRule = client.CreateRule(rule);

// List all rules defined for Inbox
var rules = client.ListRules();

// Fetch a rule
var fetchedRule = client.FetchRule(createdRule.RuleId);

// Update a rule
fetchedRule.DisplayName = "Renamed rule";
fetchedRule.IsEnabled = false;
var updatedRule = client.UpdateRule(createdRule);

// Delete a rule
client.Delete(updatedRule.RuleId);

InboxRule PrepareRule(string email, string displayName)
{
    var rule = new InboxRule()
    {
        DisplayName = "My rule",
        Priority = 1,
        IsEnabled = true,
        Conditions = new RulePredicates(),
        Actions = new RuleActions()
    };

    rule.Conditions.ContainsSenderStrings = new StringCollection { displayName };
    rule.Actions.ForwardToRecipients = new MailAddressCollection
        { new MailAddress(email, displayName, true) };
    rule.Actions.StopProcessingRules = true;

    return rule;
}

Керування блокнотами

Щоб керувати блокнотами за допомогою MS Graph від Aspose.Email для .NET, використовуйте наступні методи:

• CreateNotebook
• CopyNotebook
• FetchNotebook
• ListNotebooks

// create a OneNote notebook
var newNotebook = new Notebook()
{
    DisplayName = "My Notebook"
};
var createdNotebook = client.CreateNotebook(newNotebook);

// fetch a notebook
var fetchedNotebook = client.FetchNotebook(createdNotebook.Id);

// list the notebooks
var notebooks = client.ListNotebooks();

Управління завданнями в Microsoft Graph

Aspose.Email надає розробникам API для доступу, керування та взаємодії зі списками завдань користувачів, використовуючи наступні методи IGraphClient interface:

• ListTaskLists() - Отримує колекцію інформації про списки завдань.
• GetTaskList(string id) - Отримує конкретний список завдань на основі наданого ідентифікатора.
• DeleteTaskList(string id) - Видаляє вказаний список завдань. -ListTasks(string id) - Отримує колекцію завдань, пов’язаних з вказаним ID списку завдань.
• FetchTask(string id) - Отримує конкретне завдання за вказаним ID.
• CreateTask(MapiTask task, string taskListUri) - Створює нове завдання у вказаному списку завдань.
• UpdateTask(MapiTask task) - Оновлює існуюче завдання з наданою інформацією.
• UpdateTask(MapiTask task, UpdateSettings updateSettings) - Оновлює існуюче завдання з вказаними параметрами оновлення.

Наступний зразок коду демонструє, як керувати списками завдань:

// List Task Lists
var taskLists = graphClient.ListTaskLists();

foreach (var tList in taskLists)
{
    Console.WriteLine($"Task List: {tList.DisplayName}");
}

// Get Task List
var taskList = graphClient.GetTaskList("taskListId");

// Delete Task List
graphClient.DeleteTaskList("taskListId");

Наступний зразок коду демонструє, як керувати завданнями:

// List Tasks in a Task List
MapiTaskCollection tasks = graphClient.ListTasks("taskListId");

// Fetch Task
MapiTask task = graphClient.FetchTask("taskId");

// Create Task
var newTask = new MapiTask
{
    Subject = "New Task",
    DueDate = new DateTime(2023, 12, 31),
    Status = MapiTaskStatus.NotStarted
};

MapiTask createdTask = graphClient.CreateTask(newTask, "taskListUri");

// Update Task
createdTask.Subject = "Updated Task Subject";
MapiTask updatedTask = graphClient.UpdateTask(createdTask);

// Update Task with UpdateSettings
var updateSettings = new UpdateSettings { SkipAttachments  = true };
MapiTask updatedTaskWithSettings = graphClient.UpdateTask(createdTask, updateSettings);