الوصول إلى بيانات Microsoft 365 وإدارتها باستخدام Microsoft Graph

تحسين وصول وإدارة بيانات Microsoft 365 باستخدام عميل Aspose.Email Graph

Microsoft Graph هو واجهة برمجة تطبيقات REST للوصول إلى بيانات Microsoft 365. يسمح تنفيذ عميل Graph في Aspose.Email for .NET بالوصول إلى Microsoft Graph من خلال API الخاص بنا. في الأمثلة أدناه، سننشئ نسخة من MS Graph Client مع توفير الرمز. ثم، سنستعرض الطرق الأساسية لإدارة المجلدات، وتحديثها، ونسخها وحذفها. يمكن أيضًا الوصول إلى الرسائل ومحتواها والمرفقات أو تعديلها باستخدام عميل MS Graph الخاص بنا. إدارة الفئات والقواعد والدفاتر والمستبدلات هي ميزة ممتدة لعميل Microsoft Graph من قبل Aspose.Email.

المصادقة والطلب باستخدام IGraphClient مع MSAL في .NET

للتفاعل مع خدمات Microsoft Graph، ستحتاج إلى إنشاء IGraphClient كائن. بمجرد المصادقة، يسمح لك هذا العميل بإجراء طلبات خدمة متعددة. الـ GetClient طريقة، التي تنشئ الـ IGraphClient، تتطلب ITokenProvider التنفيذ كمعاملها الأول. هذه ITokenProvider هي المسؤولة عن توفير رمز المصادقة الضروري. للحصول على الرمز، سنستخدم الـ مكتبة Microsoft Authentication (MSAL) لـ .NET.

إليك كيفية إعداد عملية المصادقة:

الخطوة 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";
}

أضف الـ حزمة MSAL.NET.

قم بتثبيت Microsoft.Identity.Client حزمة NuGet، التي تحتوي على ملفات MSAL.NET الثنائية اللازمة للمصادقة.
تنفيذ واجهة 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

الـ 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، من الممكن الحصول على قائمة المجلدات. يحتوي كل مجلد على مجموعة من المعلمات مثل DisplayName، والتي يمكن قراءتها في FolderInfo نوع.

var folders = client.ListFolders();

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

تحديث المجلدات

لإنشاء مجلد باستخدام عميل MS Graph، استخدم 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. حذف الطريقة تُستخدم لحذف طريقة باستخدام المعرف.

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، المطبق في Aspose.Email لـ .NET، يوفر مجموعة من الطرق لإدارة الرسائل والمرفقات:

List رسائل
Fetch رسالة
Create رسالة
إرسال رسالة
CopyMessage رسالة
نقل رسالة
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);
        }
    }
}

تصفية الرسائل حسب تاريخ الإرسال

الـ 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 باستخدام ميزات التجزئة والتصفية.

أولاً، ابدأ بالعميل.
ثم، قم بتعيين عدد العناصر ليُعرض لكل صفحة، على سبيل المثال، 10.
إنشاء مرشح لاسترجاع الرسائل غير المقروءة فقط باستخدام GraphQueryBuilder الفئة. يقوم builder.IsRead.Equals(false) بتحديد شرط لتصفية الرسائل غير المقروءة.
استدعِ الـ ListMessages طريقة على كائن العميل، تحدد المجلد (Inbox) وعدد العناصر لكل صفحة (PageInfo(itemsPerPage)) كمعاملات. كما تمرّر كائن الاستعلام لتطبيق مرشح الرسائل غير المقروءة. يحتوي كائن PageInfo المرتجع (pageInfo) على الرسائل المسترجعة للصفحة الحالية في الخاصية Items.
أنشئ حلقة تستمر حتى يتم الوصول إلى الصفحة الأخيرة (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("sam@to.com", "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("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// 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("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// 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 = "from@domain.com",
    To = "to1@domain.com, to2@domain.com",
    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

إدارة أحداث التقويم

توفر Aspose.Email واجهات برمجة تطبيقات للوصول إلى أحداث التقويم وإدارتها والتفاعل معها. لهذا الغرض، تقدم الطرق التالية في IGraphClient واجهة:

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، استخدم الطرق التالية:

// 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 واجهات برمجة تطبيقات للوصول إلى عناصر جهات الاتصال وإدارتها والتفاعل معها. لهذا الغرض، تقدم الطرق التالية في IGraphClient واجهة:

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", "jane.smith@example.com", "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، استخدم الطرق التالية:

// Create an user's override
var userOverride = client.CreateOrUpdateOverride
    (new MailAddress("JohnBrown@someorg.com", "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، استخدم الطرق التالية:

// Create a rule
var rule = PrepareRule("user@someorg.com", "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، استخدم الطرق التالية:

// 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 للمطورين واجهات برمجية للوصول إلى مهام المستخدمين وقوائم المهام وإدارتها والتفاعل معها باستخدام الطرق التالية في الـ IGraphClient واجهة:

ListTaskLists() - يسترجع مجموعة من معلومات قوائم المهام.
GetTaskList(string id) - يسترجع قائمة مهام معينة بناءً على المعرف المقدم.
DeleteTaskList(string id) - يحذف قائمة المهام المحددة. -ListTasks(string id) - يسترجع مجموعة من المهام المرتبطة بمعرف قائمة المهام المحدد.
FetchTask(string 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);

إنشاء مشروع في مركز إدارة Azure Active Directory إدارة مجلدات البريد في Microsoft Graph (Aspose.Email)