Microsoft Graph to Manage Mailboxes in C#

يسمح دمج واجهة برمجة تطبيقات Microsoft Graph ومكتبة Aspose.Email لـ .NET مع تطبيق البريد الإلكتروني للمطورين بالوصول بسهولة إلى بيانات صناديق البريد والتلاعب بها، وأداء عمليات مثل جلب الرسائل، واسترجاع هياكل المجلدات، وحفظ رسائل البريد الإلكتروني بتنسيقات مختلفة. في هذه المقالة، سنستكشف كيفية الاستفادة من هذا الجمع القوي في معالجة وإدارة صناديق البريد.

عرض Microsoft Graph

Microsoft Graph هو منصة واجهة برمجة تطبيقات شاملة تقدمها Microsoft توفر نقطة نهاية موحدة للوصول إلى مجموعة واسعة من خدمات وبيانات Microsoft. يعمل كمدخل للبيانات الهائلة المتاحة في Microsoft 365، بما في ذلك صناديق بريد Outlook، والتقاويم، وجهات الاتصال، وOneDrive، وTeams، والمزيد.

مع Microsoft Graph، يمكن للمطورين بناء تطبيقات تتفاعل بسلاسة مع بيانات المستخدمين ورؤاهم عبر نظام Microsoft السحابي. يتم تحقيق ذلك من خلال واجهات برمجة التطبيقات RESTful ومجموعات تطوير البرمجيات التي توفر الوسائل للمصادقة، والتفويض، واستعلام البيانات بسهولة.

حول مكتبة Aspose.Email لـ .NET

Aspose.Email لـ .NET هي مكتبة غنية بالميزات تمكن المطورين من العمل مع ملفات البريد الإلكتروني والبروتوكولات في تطبيقاتهم .NET. توفر مجموعة قوية من واجهات برمجة التطبيقات لإنشاء، والتلاعب، وتحويل رسائل البريد الإلكتروني بتنسيقات مختلفة، مثل MSG، EML، وMBOX. بالإضافة إلى ذلك، تدعم المكتبة بروتوكولات البريد الإلكتروني مثل SMTP، POP3، وIMAP، مما يسمح بإدارة البريد الإلكتروني بشكل مرن.

في هذا الدليل، سنستخدم Aspose.Email للتفاعل مع Microsoft Graph، ومعالجة بيانات صناديق البريد برمجياً. باستخدام GraphClient من Aspose.Email، يمكننا تنفيذ عمليات صناديق البريد بكفاءة من خلال المصادقة مع Microsoft Graph.

للبدء في استخدام المكتبة، تحتاج إلى دمجها في مشروعك. أسهل طريقة للحصول على Aspose.Email لـ .NET هي من خلال مدير حزم NuGet:

  • افتح مشروعك في Visual Studio.
  • انتقل إلى أدوات > مدير حزم NuGet > إدارة حزم NuGet للحل.
  • ابحث عن Aspose.Email.
  • اختر الحزمة وانقر على تثبيت.

بدلاً من ذلك، يمكنك استخدام وحدة التحكم في مدير الحزم:

Install-Package Aspose.Email

يمكنك أيضاً تنزيل أحدث إصدار من واجهة برمجة التطبيقات مباشرة من موقع Aspose.

تهيئة تطبيقك على بوابة Azure

قبل أن نتعمق في الكود، من الضروري تهيئة تطبيقك داخل بوابة Azure لتمكين وصول Microsoft Graph. اتبع هذه الخطوات:

  1. إنشاء تطبيق Azure Active Directory (AAD):

    • انتقل إلى بوابة Azure.
    • انتقل إلى Azure Active Directory > تسجيلات التطبيقات.
    • انقر على تسجيل جديد لإنشاء تطبيق جديد.
    • قدم اسمًا واضبط URI إعادة التوجيه إذا لزم الأمر.
    • انقر على تسجيل لإكمال العملية.

  2. تعيين أذونات API:

    • في تطبيقك المسجل، انتقل إلى أذونات API.
    • انقر على إضافة إذن > Microsoft Graph.
    • اختر أذونات التطبيق لاستدعاءات الخادم إلى الخادم.
    • اختر الأذونات اللازمة مثل Mail.Read، Mail.ReadWrite، User.Read، إلخ.
    • انقر على إضافة أذونات للتطبيق.

  3. إنشاء سر العميل:

    • انتقل إلى الشهادات والأسرار في تطبيقك.
    • انقر على سر عميل جديد وقدم وصفًا.
    • اضبط فترة انتهاء صلاحية، ثم انقر على إضافة.
    • لاحظ قيمة سر العميل المولدة، حيث ستحتاج إليها لاحقًا.

  4. جمع قيم التكوين:

    • احصل على معرف المستأجر، معرف العميل، وسر العميل من صفحة نظرة عامة على تطبيقك وقسم الأسرار.
    • ستستخدم هذه القيم للمصادقة والتفاعل مع Microsoft Graph.

بمجرد تكوين تطبيقك، يمكنك المضي قدمًا في مهام التطوير.

الحصول على رمز الوصول وتهيئة GraphClient

قبل الغوص في عمليات صناديق البريد، نحتاج إلى فتح الباب أمام نظام Microsoft Graph الواسع من البيانات والخدمات. يتم منح هذا الوصول من خلال رمز وصول OAuth 2.0 - مفتاح رقمي يخول تطبيقك للتفاعل مع Microsoft Graph نيابة عن مستخدم أو خدمة. تخيل أنه كرمز آمن يمنحك الدخول إلى عالم كامل من الاحتمالات، من جلب رسائل البريد الإلكتروني إلى إدارة جهات الاتصال وما وراء ذلك.

الخطوة 1: إعداد ملف التكوين

الخطوة الأولى في الحصول على الرمز هي إعداد ملف تكوين يخزن التفاصيل الأساسية مثل معرف المستأجر، معرف العميل، وسر العميل لتطبيقك. هذه القيم هي بيانات اعتماد تطبيقك وتعمل كمعرفات عند التواصل مع خوادم 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();

        // في الذاكرة تخزين الرموز (تخزين تطبيقات ومستخدمين)
        _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 لمجلد الأب.
    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 المدونة.

انظر أيضًا