Microsoft Graph to Manage Mailboxes in C#

האינטגרציה של Microsoft Graph API וספריית Aspose.Email עבור .NET עם יישום דואר אלקטרוני מאפשרת למפתחים לגשת בקלות ולשנות נתוני תיבת דואר, לבצע פעולות כמו שליפת הודעות, שליפת היררכיות תיקיות ושמירת דוא"ל בפורמטים שונים. במאמר זה, נחקור כיצד לנצל את השילוב החזק הזה בעיבוד וניהול תיבות דואר.

מצגת Microsoft Graph

Microsoft Graph היא פלטפורמת API מקיפה המוצעת על ידי Microsoft המציעה נקודת קצה מאוחדת לגישה למגוון רחב של שירותי ומידע של Microsoft. היא משמשת כשער לנתונים העצומים הזמינים ב-Microsoft 365, כולל תיבות דואר Outlook, לוחות שנה, אנשי קשר, OneDrive, Teams ועוד.

עם Microsoft Graph, מפתחים יכולים לבנות יישומים שמתקשרים ללא בעיות עם נתוני המשתמשים ותובנותיהם ברחבי מערכת הענן של Microsoft. זה מושג באמצעות APIs ו-SDKs מבוססי REST שמספקים את האמצעים לאותנטיקציה, אישור ושאילתת הנתונים בקלות.

על ספריית Aspose.Email עבור .NET

Aspose.Email עבור .NET היא ספרייה עשירה בתכונות שמאפשרת למפתחים לעבוד עם קבצי דואר אלקטרוני ופרוטוקולים ביישומי .NET שלהם. היא מספקת מערך חזק של APIs ליצירה, שינוי והמרת הודעות דואר אלקטרוני בפורמטים שונים, כמו MSG, EML ו-MBOX. בנוסף, הספרייה תומכת בפרוטוקולי דואר אלקטרוני כמו SMTP, POP3 ו-IMAP, המאפשרים ניהול דואר אלקטרוני מגוון.

במדריך הזה, נשתמש ב-Aspose.Email כדי לתקשר עם Microsoft Graph, לעבד נתוני תיבת דואר באופן תכנותי. עם ה-GraphClient של Aspose.Email, נוכל לבצע ביעילות פעולות בתיבת דואר על ידי אותנטיקציה עם Microsoft Graph.

כדי להתחיל להשתמש בספרייה, עליך לשלב אותה בפרויקט שלך. הדרך הקלה ביותר להשיג את Aspose.Email עבור .NET היא באמצעות מנהל חבילות NuGet:

  • פתח את הפרויקט שלך ב-Visual Studio.
  • נווט ל-Tools > מנהל חבילות NuGet > ניהול חבילות NuGet עבור הפתרון.
  • חפש את Aspose.Email.
  • בחר את החבילה ולחץ על התקן.

לחילופין, תוכל להשתמש בקונסולת מנהל החבילות:

Install-Package Aspose.Email

כמו כן, תוכל להוריד את הגרסה האחרונה של ה-API ישירות מה-אתר 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. אסוף ערכי תצורה:

    • השג את Tenant ID, Client ID ו-Client 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($"The token acquired from {result.AuthenticationResultMetadata.TokenSource} {Environment.NewLine}");
        }
        catch (MsalServiceException ex)
        {
            Console.WriteLine($"Error Acquiring Token:{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 כדי לייצג כל תיקייה בהיררכיה:

// Represents a node in a folder hierarchy,
// extending the properties of FolderInfo and storing a collection of subfolders.
class FolderNode
{
    // Gets the FolderInfo object representing the folder information.
    public FolderInfo Folder { get; }
    
    // Gets the collection of subfolders contained within the current folder.
    public List<FolderNode?> SubFolders { get; }

    // Initializes a new instance of the FolderNode class with the specified FolderInfo object.
    public FolderNode(FolderInfo folder)
    {
        Folder = folder;
        SubFolders = new List<FolderNode?>();
    }
    
    // Prints all folders in a hierarchical manner starting from the current node.
    public void PrintHierarchy()
    {
        PrintFolderNode(this, 0);
    }

    private void PrintFolderNode(FolderNode node, int indentLevel)
    {
        // Print current folder node with indentation
        Console.WriteLine($"{new string(' ', indentLevel * 2)}{node}");

        // Recursively print subfolders
        foreach (var subFolder in node.SubFolders)
        {
            PrintFolderNode(subFolder, indentLevel + 1);
        }
    }

    // Get the folder Display Name.
    public override string ToString()
    {
        return $"{Folder.DisplayName} ({Folder.ContentCount})";
    }
}

כדי לשלוף את כל היררכיית התיקיות, ניצור את מחלקת FolderHierarchy, המשתמשת ב-GraphClient כדי לרשום את כל התיקיות באופן רקורסיבי. כך זה עובד:

static class FolderHierarchy
{
    // Retrieves all folders in the mailbox recursively and returns a hierarchical collection of FolderNode objects.
    public static List<FolderNode> Retrieve(IGraphClient client)
    {
        // Retrieve root folders
        var rootFolders = client.ListFolders();
        var allFolders = new List<FolderNode>();

        // Retrieve subfolders recursively
        foreach (var folder in rootFolders)
        {
            var folderNode = new FolderNode(folder);
            RetrieveSubFolders(client, folderNode);
            allFolders.Add(folderNode);
        }

        return allFolders;
    }

    // Retrieves subfolders recursively and adds them to the parent FolderNode's SubFolders property.
    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, תוכל בקלות לחדור לתיבת הדואר ולגלות את מבנה התיקיות שלה. כך תוכל להשיג זאת:

// Retrieve the folder hierarchy from the mailbox
var folderNodes = FolderHierarchy.Retrieve(client);

// Print the folder hierarchy in a structured format
foreach (var folderNode in folderNodes)
{
    folderNode.PrintHierarchy();
}

שלב 3: שלוף תיקיות לפי שם

לאחר שהיררכיית התיקיות נשלפה, תוכל לאתר תיקיות ספציפיות לפי שם. בין אם אתה מעוניין לגשת לתיבת הדואר הנכנס או לכל תיקיה מותאמת אישית, המתודה הזו מבטיחה שאתה יכול לאתר אותן במהירות:

// Specify the folder name you're looking for
string targetFolderName = "Inbox";

// Locate the target folder by name
var targetFolder = folderNodes.FirstOrDefault(
    folderNode => folderNode.Folder.DisplayName.Equals(targetFolderName, StringComparison.OrdinalIgnoreCase))
    ?.Folder;

רשימת הודעות בתיקיה שנבחרה

עם היררכיית התיקיות שנשלפה בהצלחה, השלב הבא הוא לחדור לתוכן של תיקיות ספציפיות. דמיין שהגעת לתיבת הדואר הנכנס שלך; עכשיו אתה רוצה לראות את כל ההודעות שהיא מחזיקה.

בחלק זה, נחקור כיצד לרשום הודעות בתוך תיקיה ספציפית באמצעות ה-GraphClient ו-Aspose.Email עבור .NET.

ברגע שיש לך את התיקיה, רשימת ההודעות בתוכה היא פשוטה. ה-GraphClient מספק את המתודה ListMessages כדי לשלוף את כל ההודעות בתיקיה, אותן תוכל לעבד או להציג.

כך נראה הקוד לרשימת הודעות בתיקיה שנבחרה:

Console.WriteLine("Listing messages in the specified folder...");

// Call the client method to list messages in the selected folder
var messageInfoCollection = client.ListMessages(targetFolder.ItemId);

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

// Print out the subject lines of the messages
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.

ראו גם