Akses dan Manajemen Data Microsoft 365 dengan Microsoft Graph

Optimalkan Akses dan Manajemen Data Microsoft 365 dengan Aspose.Email Graph Client

Microsoft Graph adalah API REST untuk mengakses data Microsoft 365. Implementasi Graph Client dalam Aspose.Email untuk .NET memungkinkan akses ke Microsoft Graph melalui API kami. Pada contoh di bawah, kami akan membuat sebuah instance MS Graph Client, menyediakan token. Kemudian, kami akan meninjau metode utama untuk mengelola folder, memperbarui, menyalin, dan menghapusnya. Pesan, isi, dan lampirannya juga dapat diakses atau diubah dengan MS Graph Client kami. Mengelola kategori, aturan, notebook, dan overrides merupakan fitur tambahan dari Microsoft Graph Client oleh Aspose.Email.

Autentikasi dan Permintaan dengan IGraphClient menggunakan MSAL di .NET

Untuk berinteraksi dengan layanan Microsoft Graph, Anda perlu membuat sebuah IGraphClient objek. Setelah terautentikasi, klien ini memungkinkan Anda melakukan berbagai permintaan layanan. GetClient metode, yang membuat IGraphClient, memerlukan sebuah ITokenProvider implementasi sebagai parameter pertamanya. Ini ITokenProvider bertanggung jawab menyediakan token autentikasi yang diperlukan. Untuk memperoleh token, kami akan menggunakan Microsoft Authentication Library (MSAL) untuk .NET.

Berikut cara menyiapkan proses autentikasi:

Langkah 1: Menyiapkan Autentikasi

Langkah-langkah berikut akan memandu Anda cara memperoleh token otorisasi:

Buat Kelas AccessParameters.

Definisikan kelas AccessParameters untuk menyimpan kredensial Anda.

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";
}

Tambahkan Paket MSAL.NET**.

Instal Microsoft.Identity.Client Paket NuGet, yang berisi biner MSAL.NET yang diperlukan untuk autentikasi.
Implementasikan Antarmuka ITokenProvider.

Buat sebuah GraphTokenProvider kelas yang mengimplementasikan ITokenProvider antarmuka. Kelas ini akan menggunakan pustaka MSAL.NET untuk memperoleh token akses.

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;
    }

Langkah 2: Buat Instance ITokenProvider

Setelah mendefinisikan GraphTokenProvider kelas, Anda dapat membuat instance dari AccessParameters dan gunakan untuk menginstansiasi 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);

Langkah 3: Buat Permintaan dengan IGraphClient

Akhirnya, gunakan GraphTokenProvider untuk membuat autentikasi IGraphClient dan mulai membuat permintaan layanan.

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

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

Dengan langkah-langkah ini selesai, Anda IGraphClient sekarang siap berinteraksi dengan layanan Microsoft Graph menggunakan permintaan yang terautentikasi.

Menyambungkan ke Endpoint GCC High

The GraphClient mendukung koneksi ke endpoint GCC High dengan menggunakan EndPoint properti. Contoh kode berikut menunjukkan cara mengonfigurasi GraphClient untuk terhubung ke endpoint GCC High untuk menampilkan daftar folder dan mengambil pesan.

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

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

Kelola Folder dengan IGraphClient

Daftar Folder

Dengan memanggil ListFolders metode dari MS Graph Client, memungkinkan untuk mendapatkan daftar folder. Setiap folder memiliki sekumpulan parameter seperti DisplayName, yang dapat dibaca di FolderInfo tipe.

var folders = client.ListFolders();

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

Perbarui Folder

Untuk membuat folder dengan MS Graph Client, gunakan CreateFolder metode. Anda akan mendapatkan sebuah FolderInfo objek dan kemungkinan mengakses DisplayName, ItemId, HasSubFolders, dan properti lainnya.

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

Salin Folder

CopyFolder metode ini adalah metode utama untuk menyalin objek folder dengan MS Graph.

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

Pindah dan Hapus Folder

Gunakan MoveFolder metode ini digunakan untuk memindahkan folder, menerima newParentId dan itemId. Delete metode ini digunakan untuk menghapus metode berdasarkan 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)

Kelola Pesan dengan IGraphClient

MS Graph Client, yang diimplementasikan dalam Aspose.Email untuk .NET, menyediakan sekumpulan metode untuk mengelola pesan dan lampiran:

Daftar Pesan

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);
        }
    }
}

Filter Pesan berdasarkan Tanggal Pengiriman

The OrderBy metode dari koleksi perpustakaan memungkinkan Anda mengambil pesan dengan urutan penyortiran yang berbeda (menaik dan menurun) berdasarkan tanggal pengirimannya. Contoh kode berikut menunjukkan cara mengurutkan pesan berdasarkan tanggal pengiriman:

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;

Enumerasi Pesan dengan Dukungan Paging

API memungkinkan paging dan filtering pesan saat mendaftar. Ini sangat membantu untuk kotak surat dengan volume pesan tinggi, karena menghemat waktu dengan hanya mengambil informasi ringkas yang diperlukan.

Contoh kode dan langkah-langkah di bawah ini menunjukkan cara mengambil pesan dari folder Inbox menggunakan fitur paging dan filtering.

Pertama, inisialisasi klien.
Kemudian, atur jumlah item yang ditampilkan per halaman, misalnya, 10.
Buat filter untuk hanya mengambil pesan belum dibaca menggunakan GraphQueryBuilder kelas. builder.IsRead.Equals(false) mengatur kondisi untuk memfilter pesan belum dibaca.
Panggil ListMessages metode pada objek klien, menentukan folder (Inbox) dan item per halaman (PageInfo(itemsPerPage)) sebagai parameter. Ini juga meneruskan objek query untuk menerapkan filter pesan belum dibaca. Objek PageInfo yang dikembalikan (pageInfo) berisi pesan yang diambil untuk halaman saat ini di properti Items.
Buat loop yang berlanjut hingga halaman terakhir tercapai (pageInfo.LastPage bernilai false). Pesan yang diambil ditambahkan ke daftar pesan yang ada menggunakan 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);
}

Ambil Pesan

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);
        }
        
    }
}

Buat Pesan

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);

Kirim Pesan

// 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);

Kirim Pesan Draf

// 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);

Kirim Pesan EML

Membuat dan mengirim email menjadi mudah menggunakan objek MailMessage. Contoh kode berikut menunjukkan cara membuat dan mengirim pesan email menggunakan 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);

Salin Pesan


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

Pindahkan Pesan

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

Kelola Lampiran


// 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);

Kelola Item Outlook dengan Graph Client

Kelola Acara Kalender

Aspose.Email menyediakan API untuk mengakses, mengelola, dan berinteraksi dengan acara kalender. Untuk tujuan ini, ia menawarkan metode berikut dalam IGraphClient antarmuka:

ListCalendars() - Mengambil koleksi informasi kalender.
ListCalendarItems(string id) - Mengambil koleksi item kalender yang terkait dengan ID kalender yang ditentukan.
FetchCalendarItem(string id) - Mengambil item kalender tertentu berdasarkan ID yang diberikan.
CreateCalendarItem(string calId, MapiCalendar mapiCalendar) - Membuat item kalender baru di kalender yang ditentukan.
UpdateCalendarItem(MapiCalendar mapiCalendar) - Memperbarui item kalender yang ada.
UpdateCalendarItem(MapiCalendar mapiCalendar, UpdateSettings updateSettings) - Memperbarui item kalender yang ada dengan pengaturan pembaruan yang ditentukan.

Contoh kode berikut menunjukkan cara berinteraksi dengan acara kalender dalam klien Microsoft Graph API menggunakan metode yang disediakan oleh 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);

Kelola Kategori

Untuk mengelola kategori dengan MS Graph oleh Aspose.Email untuk .NET, gunakan metode berikut:

// 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);

Kelola Kontak

Aspose.Email menyediakan API untuk mengakses, mengelola, dan berinteraksi dengan item kontak. Untuk tujuan ini, ia menawarkan metode berikut dalam IGraphClient antarmuka:

ListContacts(string id) - Mengambil koleksi kontak MAPI yang terkait dengan ID folder yang ditentukan.
FetchContact(string id) - Mengambil kontak tertentu berdasarkan ID item yang diberikan.
CreateContact(string folderId, MapiContact contact) - Membuat kontak baru di folder yang ditentukan.
UpdateContact(MapiContact contact) - Memperbarui kontak yang ada.

Contoh kode berikut menunjukkan cara berinteraksi dengan kontak dalam klien Microsoft Graph API menggunakan metode yang disediakan oleh 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);

Kelola Override

Untuk mengelola override dengan MS Graph oleh Aspose.Email untuk .NET, gunakan metode berikut:

// 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);

Kelola Aturan

Untuk mengelola aturan dengan MS Graph oleh Aspose.Email untuk .NET, gunakan metode berikut:

// 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;
}

Kelola Notebook

Untuk mengelola notebook dengan MS Graph oleh Aspose.Email untuk .NET, gunakan metode berikut:

// 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();

Manajemen Tugas di Microsoft Graph

Aspose.Email menyediakan pengembang dengan API untuk mengakses, mengelola, dan berinteraksi dengan tugas dan daftar tugas pengguna menggunakan metode berikut dari IGraphClient antarmuka:

ListTaskLists() - Mengambil koleksi informasi daftar tugas.
GetTaskList(string id) - Mengambil daftar tugas tertentu berdasarkan ID yang diberikan.
DeleteTaskList(string id) - Menghapus daftar tugas yang ditentukan. -ListTasks(string id) - Mengambil koleksi tugas yang terkait dengan ID daftar tugas yang ditentukan.
FetchTask(string id) - Mengambil tugas tertentu berdasarkan ID yang diberikan.
CreateTask(MapiTask task, string taskListUri) - Membuat tugas baru dalam daftar tugas yang ditentukan.
UpdateTask(MapiTask task) - Memperbarui tugas yang ada dengan informasi yang diberikan.
UpdateTask(MapiTask task, UpdateSettings updateSettings) - Memperbarui tugas yang ada dengan pengaturan pembaruan yang ditentukan.

Contoh kode berikut menunjukkan cara mengelola daftar tugas:

// 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");

Contoh kode berikut menunjukkan cara mengelola tugas:

// 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);

Membuat Proyek di Azure Active Directory Admin Center Kelola Folder Mail di Microsoft Graph (Aspose.Email)