Microsoft Graph برای مدیریت صندوق‌های پستی در C#

ادغام Microsoft Graph API و Aspose.Email برای .NET با یک برنامه ایمیل به توسعه‌دهندگان این امکان را می‌دهد که به راحتی به داده‌های صندوق پستی دسترسی پیدا کنند و آن را دستکاری کنند، عملیات‌هایی مانند بازیابی پیام‌ها، بازیابی سلسله‌مراتب پوشه‌ها و ذخیره ایمیل‌ها در فرمت‌های مختلف را انجام دهند. در این مقاله، ما بررسی خواهیم کرد که چگونه از این ترکیب قدرتمند در پردازش و مدیریت صندوق‌های پستی استفاده کنیم.

معرفی Microsoft Graph

Microsoft Graph یک پلتفرم API جامع است که توسط Microsoft ارائه شده و یک نقطه پایانی یکپارچه برای دسترسی به مجموعه وسیعی از خدمات و داده‌های Microsoft ارائه می‌دهد. این پلتفرم به عنوان درگاهی به داده‌های وسیع موجود در Microsoft 365، از جمله صندوق‌های پستی Outlook، تقویم‌ها، مخاطبین، OneDrive، Teams و غیره عمل می‌کند.

با Microsoft Graph، توسعه‌دهندگان می‌توانند برنامه‌هایی بسازند که به طور یکپارچه با داده‌ها و بینش‌های کاربران در اکوسیستم ابری Microsoft تعامل داشته باشند. این امر از طریق APIهای RESTful و 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 بروید.
    • به Azure Active Directory > App registrations بروید.
    • روی New registration کلیک کنید تا یک برنامه جدید ایجاد کنید.
    • یک نام ارائه کرده و URI بازگشت را در صورت نیاز تنظیم کنید.
    • برای تکمیل فرایند روی Register کلیک کنید.

  2. تنظیم مجوزهای API:

    • در برنامه ثبت‌نام شده خود، به API permissions بروید.
    • روی Add a permission > Microsoft Graph کلیک کنید.
    • Application permissions را برای تماس‌های سرور به سرور انتخاب کنید.
    • مجوزهای لازم مانند Mail.Read، Mail.ReadWrite، User.Read و غیره را انتخاب کنید.
    • برای اعمال، روی Add permissions کلیک کنید.

  3. ایجاد یک Client Secret:

    • به Certificates & secrets در برنامه خود بروید.
    • روی New client secret کلیک کرده و یک توضیحات وارد کنید.
    • یک دوره انقضا تنظیم کنید، سپس روی Add کلیک کنید.
    • مقدار تولید شده client secret را یادداشت کنید، زیرا به آن نیاز خواهید داشت.

  4. جمع‌آوری مقادیر پیکربندی:

    • Tenant ID، Client ID و Client Secret را از صفحه نمای کلی و بخش secret برنامه خود بگیرید.
    • شما از این مقادیر برای احراز هویت و تعامل با Microsoft Graph استفاده خواهید کرد.

پس از پیکربندی برنامه خود، آماده‌اید تا به توسعه کارها ادامه دهید.

دریافت توکن دسترسی و راه‌اندازی GraphClient

قبل از اینکه به عملیات صندوق پستی بپردازیم، باید دروازه را به اکوسیستم وسیع داده‌ها و خدمات Microsoft Graph باز کنیم. این دسترسی از طریق یک توکن دسترسی OAuth 2.0 - یک کلید دیجیتال که به برنامه شما اجازه می‌دهد به نمایندگی از یک کاربر یا سرویس با Microsoft Graph تعامل کند - اعطا می‌شود. تصور کنید که این یک مجوز امن است که به شما اجازه ورود به یک جهان کامل از امکانات را می‌دهد، از دریافت ایمیل‌ها تا مدیریت مخاطبین و فراتر از آن.

مرحله 1: راه‌اندازی یک فایل پیکربندی

اولین مرحله در به‌دست آوردن توکن این است که یک فایل پیکربندی راه‌اندازی کنید که جزئیات ضروری مانند Tenant ID، Client ID و Client Secret برنامه شما را ذخیره کند. این مقادیر اعتبارنامه‌های برنامه شما هستند و به عنوان شناسه‌ها هنگام ارتباط با سرورهای 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;
    }

    // زیرپوشه‌ها را به صورت بازگشتی بازیابی کرده و به زیرپوشه‌های والد 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: بازیابی پوشه‌ها بر اساس نام

پس از بازیابی سلسله‌مراتب پوشه، می‌توانید پوشه‌های خاصی را بر اساس نام شناسایی کنید. چه به دنبال دسترسی به Inbox باشید و چه به هر پوشه دلخواه دیگر، این روش اطمینان می‌دهد که می‌توانید به سرعت آن‌ها را پیدا کنید:

// نام پوشه‌ای که به دنبال آن هستید را مشخص کنید
string targetFolderName = "Inbox";

// پوشه هدف را بر اساس نام پیدا کنید
var targetFolder = folderNodes.FirstOrDefault(
    folderNode => folderNode.Folder.DisplayName.Equals(targetFolderName, StringComparison.OrdinalIgnoreCase))
    ?.Folder;

لیست کردن پیام‌ها در پوشه مشخص

با موفقیت بازیابی سلسله‌مراتب پوشه، مرحله بعدی بررسی محتوای پوشه‌های خاص است. تصور کنید که به Inbox خود رفته‌اید؛ حالا می‌خواهید همه پیام‌های موجود در آن را مشاهده کنید.

در این بخش، نحوه لیست کردن پیام‌ها در یک پوشه خاص را با استفاده از 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 گسترده مرجع API، و انواع ابزارها و برنامه‌های آنلاین رایگان برای بهبود فرآیند توسعه شما ارائه می‌دهد. توسعه‌دهندگان همچنین می‌توانند به انجمن پشتیبانی رایگان برای کمک و بینش‌های جامعه دسترسی پیدا کنند و با آخرین نکات و آموزش‌ها از طریق وبلاگ Aspose به‌روز بمانند.

ببینید همچنین