هنگام کار با داده‌های Microsoft 365، مانند ایمیل‌ها، تقویم‌ها، مخاطبین یا وظایف، همیشه لازم نیست تمام آیتم‌ها را بازیابی کنید. همچنین مفید است که بتوانید در برنامه‌های ایمیل خود فیلتر، مرتب‌سازی و بازیابی ویژگی‌های خاص داده را انجام دهید. به عنوان مثال، فیلتر کردن پیام‌ها بر اساس فرستنده، مرتب‌سازی رویدادهای تقویم بر حسب تاریخ یا دریافت تنها چند فیلد می‌تواند به سرعت برنامه شما کمک کند.

در همین جا است که پرس‌و‌جوهای OData وارد می‌شوند. Microsoft Graph از OData پشتیبانی می‌کند تا به توسعه‌دهندگان کمک کند داده‌ها را مستقیماً بر روی سرور فیلتر، مرتب‌سازی و انتخاب کنند قبل از این که حتی به برنامه شما ارسال شوند. نتیجه عملکرد سریع‌تر، بارهای داده کوچکتر و برنامه‌های واکنش‌پذیرتر است.

Aspose.Email for .NET این فرآیند را با کلاس [ODataQueryBuilder][2] خود به سادگی انجام می‌دهد. در این مقاله، نحوه کارکرد آن و چگونگی استفاده از آن برای ساخت پرس‌و‌جوهای پویا و قدرتمند Microsoft Graph در C# را بررسی می‌کنیم.

چرا از پرس‌و‌جوهای OData استفاده کنیم؟

API مایکروسافت گراف ویژگی‌های گسترده‌ای ارائه می‌دهد اما هنگام ساخت پرس‌وجوها به‌صورت دستی می‌تواند پیچیده باشد. پارامترهای OData امکان فیلترگذاری، مرتب‌سازی، صفحه‌بندی و انتخاب ویژگی‌ها در سمت سرور را فراهم می‌کنند که پردازش سمت کلاینت را به حداقل می‌رساند. این رویکرد با کاهش انتقال داده و تسریع زمان‌های پاسخ، کارایی را افزایش می‌دهد و برنامه‌های شما را سریع‌تر و مقیاس‌پذیرتر می‌کند.

با پشتیبانی OData، اکنون می‌توانید:

  • فیلتر کردن پیام‌ها، مخاطبین یا رویدادها با استفاده از شرایط سفارشی.
  • مرتب‌سازی داده‌ها با OrderBy برای ترتیب صعودی یا نزولی.
  • انتخاب فقط ویژگی‌های مورد نیاز برای کاهش حجم بار.
  • پیاده‌سازی صفحه‌بندی با استفاده از Top و Skip، ایده‌آل برای صندوق‌های پستی بزرگ.
  • گسترش موجودیت‌های مرتبط (مثلاً پیوست‌ها) با Expand.
  • شمارش و جستجوی مجموعه‌های داده برای دسترسی سریع‌تر.

این قابلیت‌ها از طریق کلاس جدید [ODataQueryBuilder][2] به‌صورت قابل دسترسی و ایمن از نظر نوع هستند.

کامپوننت .NET شما برای ساخت پرس‌و‌جوهای Microsoft Graph در C#

Aspose.Email for .NET یک API قدرتمند برای پردازش ایمیل‌ها است که به توسعه‌دهندگان امکان می‌دهد مستقیماً با داده‌های Microsoft 365، Exchange و Outlook در C# کار کنند. این API از خواندن و نوشتن فرمت‌های محبوب ایمیل مانند MSG، EML، PST و MBOX پشتیبانی می‌کند و با پروتکل‌ها و سرویس‌های مختلف، از جمله Microsoft Graph API، یکپارچه می‌شود.

با استفاده از [ODataQueryBuilder][2] داخلی، می‌توانید پرس‌و‌جوهای پویا و ایمن از نظر نوع OData را در C# بسازید. این کار فیلتر، مرتب‌سازی و بازیابی داده‌های خاص صندوق‌پستی — پیام‌ها، مخاطبین یا رویدادهای تقویم — را بدون نوشتن دستی رشته‌های پرس‌و‌جو پیچیده آسان می‌کند.

با انتقال منطق پرس‌و‌جو به سرور Microsoft Graph، Aspose.Email for .NET به توسعه‌دهندگان کمک می‌کند تا برنامه‌های سریع‌تر، کارآمدتر و مقیاس‌پذیر ایجاد کنند که با داده‌های Microsoft 365 تعامل دارند.

برای شروع، بسته NuGet Aspose.Email را در پروژه .NET خود نصب کنید:

Install-Package Aspose.Email

این بسته شامل تمام کلاس‌های لازم برای برآورده کردن نیازهای شما است.

معرفی کلاس ODataQueryBuilder

کلاس [Aspose.Email.Clients.Graph.ODataQueryBuilder][2] برای ساده‌سازی نحوه نوشتن کوئری‌های Graph ساخته شده است. می‌توانید از آن با چندین متد کلاینت Graph استفاده کنید، از جمله:

  • ListFolders
  • ListMessages
  • ListContacts
  • ListCalendarItems
  • ListAttachments
  • ListCategories
  • ListOverrides
  • ListRules
  • ListTaskLists
  • ListTasks
  • ListNotebooks

هر کدام یک پارامتر اختیاری ODataQueryBuilder را برای فیلتر پیشرفته، مرتب‌سازی، صفحه‌بندی و انتخاب، مستقیماً در درخواست‌های Graph شما پشتیبانی می‌کند.

مثال عملی: فیلتر و مرتب‌سازی داده‌های صندوق پستی

نمونه کد زیر هر دو سناریوی پایه و پیشرفتهٔ پرس‌و‌جو را نشان می‌دهد. این نمونه مرتب‌سازی پوشه‌ها و فیلتر پیشرفتهٔ پیام‌ها را به نمایش می‌گذارد و پارامترهای OData برای ترتیب، معیارها، صفحه‌بندی، فیلدهای انتخابی و گسترش موجودیت‌های مرتبط را توضیح می‌دهد.

var accessParameters = Settings.User1;
var provider = new AzureConfidentialTokenProvider(
    accessParameters.TenantId,
    accessParameters.ClientId,
    accessParameters.ClientSecret);

var client = GraphClient.GetClient(provider, accessParameters.TenantId);
client.Resource = Aspose.Email.Clients.Graph.ResourceType.Users;
client.ResourceId = accessParameters.Username;
client.EndPoint = "https://graph.microsoft.com";

// List folders sorted by name
var builder = new ODataQueryBuilder { OrderBy = "name asc" };
var folders = client.ListFolders(builder);
foreach (var folder in folders)
    Console.WriteLine(folder.DisplayName);

// Advanced message filtering
var folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;
builder = new ODataQueryBuilder {
    Filter = "startswith(name,'A')",
    OrderBy = "name asc",
    Top = 10,
    Skip = 5,
    Select = new[] { "name", "age" },
    Expand = new[] { "children", "parents" },
    Count = true,
    Search = "\"John Doe\"",
    Format = "json"
};
var msgs = client.ListMessages(folderId, builder);
foreach (var msg in msgs)
    Console.WriteLine(msg.Subject);

سناریوهای دنیای واقعی

در برخی موقعیت‌های عملی که می‌توانید از [ODataQueryBuilder][2] برای بهبود کار با داده‌های Microsoft Graph در برنامه‌های .NET خود استفاده کنید، در نظر بگیرید:

1. فهرست‌های پوشه UI
پوشه‌ها را به صورت الفبایی مرتب کنید [OrderBy][3] = "name asc" برای یک رابط کاربری تمیز.

۲. فیلتر سفارشی
از [فیلتر][4] برای یافتن پیام‌ها از ارسال‌کنندگان خاص یا با موضوعات معین استفاده کنید.

3. صفحه‌بندی صندوق‌های پستی بزرگ
[Top][5] و [Skip][6] را ترکیب کنید تا صندوق‌های پستی بزرگ را به نتایج قابل مدیریت تقسیم کنید.

4. انتخاب ویژگی‌های خاص
فقط فیلدهایی را که نیاز دارید با [Select][7] دریافت کنید تا بار داده را به حداقل برسانید و عملکرد را سرعت ببخشید.

5. شامل داده‌های مرتبط
از [Expand][8] برای شامل کردن پیوست‌ها، دسته‌ها یا رشته‌ها در یک پرس‌وجو استفاده کنید.

نکات برای استفاده مؤثر از OData

  • تأیید کنید که GraphClient شما به‌دقت Resource، ResourceId و EndPoint را مشخص می‌کند.
  • یک ارائه‌دهنده احراز هویت مناسب انتخاب کنید، مانند [AzureConfidentialTokenProvider][13].
  • برای بهینه‌سازی پرس‌و‌جوها، [Filter][4]، [Select][7]، [OrderBy][3] و [Top][5] را ترکیب کنید.
  • از [Count][14] برای به‌دست آوردن تعداد کل آیتم‌ها بدون بارگذاری تمام داده‌ها استفاده کنید.
  • منطق صفحه‌بندی را برای مدیریت مؤثر مجموعه‌های داده بزرگ آماده کنید.

نتیجه‌گیری

در این مقاله، نحوه استفاده از کلاس [ODataQueryBuilder][2] کتابخانه Aspose.Email for .NET را برای ساخت و اجرای پرس‌و‌جوهای Microsoft Graph آموختیم. به جای نوشتن دستی سینتکس OData، اکنون می‌توانید پرس‌و‌جوهای ایمن از نظر نوع، پویا و قابل خواندن را مستقیماً در کد C# خود ایجاد کنید. معرفی پشتیبانی از پرس‌و‌جوهای OData در Aspose.Email for .NET به توسعه‌دهندگان امکان می‌دهد برنامه‌های هوشمندتر و کارآمدتری بسازند که با Microsoft Graph تعامل دارند.

آیا آماده‌اید تا برنامه‌های .NET سریع‌تر و کارآمدتر را با Microsoft Graph بسازید؟

  • دانلود آخرین Aspose.Email for .NET
  • کاوش نمونه‌های کد بیشتری در مستندات API
  • دانلود یک مجوز موقت 30 روزه رایگان برای ارزیابی کتابخانه بدون محدودیت.

موارد مرتبط