پیکربندی
هر گزینهٔ کلاینت، آنچه از محیط میخواند و آنچه رد میکند.
گزینهها
using var http = new HttpClient(); var client = new OpenEmailClient(new OpenEmailOptions{ ApiKey = Environment.GetEnvironmentVariable("OPENEMAIL_API_KEY"), BaseUrl = "https://api.openemail.uk", Timeout = TimeSpan.FromSeconds(30), MaxRetries = 2, HttpClient = http, Headers = { ["X-Team"] = "billing" },}); Console.WriteLine($"{client.Mode} {client.Raw.BaseUrl}");| گزینه | چه میکند |
|---|---|
| ApiKey | کلید API فضای کاری که با oe_live_ یا oe_test_ شروع میشود. |
| AccessToken | یک توکن دسترسی OAuth، برای برنامهای که یک شخص متصل کرده است. یک کلید یا یک توکن بدهید، نه هر دو. |
| AccessTokenProvider | تابعی که توکن دسترسی را برمیگرداند. پیش از هر درخواست اجرا میشود، پس جای تمدید توکن همینجاست. |
| BaseUrl | مبدأ API. به میزبان سادهای مانند localhost:2222 طرح آن افزوده میشود. |
| HttpClient | همان HttpClient که برنامهٔ شما از پیش دارد، مانند یکی از IHttpClientFactory یا یکی با یک هندلر آزمایشی. کلاینت هرگز آن را آزاد نمیکند. |
| Timeout | مدتی که یک تلاش میتواند طول بکشد. پیشفرض 30 ثانیه است، TimeSpan.Zero آن را خاموش میکند، و بارگذاریها دستکم ده دقیقه صبر میکنند. |
| MaxRetries | تعداد دفعاتی که یک درخواست ناموفق دوباره امتحان میشود. پیشفرض 2 است، و 0 یک بار میفرستد. |
| UserAgent | سرآیند User-Agent را جایگزین میکند، که openemail-dotnet/ بههمراه نسخه است. |
| Headers | سرآیندهایی که به هر درخواست افزوده میشوند. |
هر چه را ننویسید از محیط خوانده میشود: OPENEMAIL_API_KEY، سپس OPENEMAIL_ACCESS_TOKEN، و OPENEMAIL_BASE_URL. client.Mode میگوید کلید یک کلید live است یا test.
لغو و مهلتها
هر متد در آخر یک CancellationToken میگیرد. لغو آن فراخوانی را همراه با تلاشهای دوباره بیدرنگ متوقف میکند و OperationCanceledException پرتاب میکند، در حالی که Timeout هر تلاش را محدود میکند.
using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(10)); var thread = await client.Threads.GetAsync("CAHk7pQ2x9LmZ4-mail.example.com", cancellationToken: deadline.Token); Console.WriteLine(thread["messageCount"]);گزینههای یک فراخوانی
پارامترهای پرسوجو و تنظیمهای فراخوانی آرگومانهای نامدار با نامهای API هستند، مانند limit:، cursor: و idempotencyKey:. هر متد apiKey: را میگیرد تا فقط برای همان فراخوانی با کلید دیگری کار کند، پس یک فرایند میتواند با یک کلاینت به چند فضای کاری خدمت بدهد.
var page = await client.Emails.ListAsync( status: new[] { "failed", "bounced" }, limit: 50, apiKey: Environment.GetEnvironmentVariable("OTHER_WORKSPACE_KEY")); Console.WriteLine($"{page.Count} {page.HasMore}");توکنهای دسترسی OAuth
برنامهای که کسی با OAuth وصل کرده بهجای کلید API یک توکن دسترسی دارد. آن را بهعنوان AccessToken بدهید، یا AccessTokenProvider را بدهید و توکن را همانجا وقتی به انقضا نزدیک شد تازه کنید، تا کلاینت هرگز نیاز به بازسازی نداشته باشد.
var current = "token-from-your-oauth-flow"; var client = new OpenEmailClient(new OpenEmailOptions{ AccessTokenProvider = _ => Task.FromResult(current),}); var me = await client.Me.GetAsync(); Console.WriteLine(me["workspaceId"]);ASP.NET Core
برای کل برنامه یک کلاینت ثبت کنید. هیچ اتصالی از خودش ندارد که آزاد شود، پس singleton طول عمر درست است.
using OpenEmail; var builder = WebApplication.CreateBuilder(args); builder.Services.AddSingleton(new OpenEmailClient(new OpenEmailOptions{ ApiKey = builder.Configuration["OpenEmail:ApiKey"],})); var app = builder.Build(); app.MapPost("/invoices/{number}/send", async (string number, OpenEmailClient client, CancellationToken cancellationToken) =>{ var sent = await client.Emails.SendAsync(new Body { ["from"] = "[email protected]", ["to"] = "[email protected]", ["subject"] = $"Invoice {number}", ["text"] = "The invoice is attached.", }, idempotencyKey: $"invoice-{number}", cancellationToken: cancellationToken); return Results.Ok(new { id = (string?)sent["id"] });}); app.Run();آنچه کلاینت رد میکند
- کلیدی که با
oe_live_یاoe_test_شروع نمیشود، و کلیدی همراه با یک توکن دسترسی. - فرستادن اعتبارنامه روی
http:ساده، مگر آنکه سرور روی همین دستگاه درlocalhost، یک نشانی127.x.x.xیا::1باشد. - نشانی پایه روی
0.0.0.0، که نشانیای است که سرور روی آن گوش میدهد. از127.0.0.1با همان درگاه استفاده کنید. - شناسهٔ خالی، یا شناسهای که فقط از نقطه ساخته شده و تجزیهگر URL آن را حذف میکند.
- دنبال کردن تغییر مسیر. کلاینت HTTP که بسته میسازد هرگز هیچ تغییر مسیری را دنبال نمیکند، پس اعتبارنامه هرگز به میزبان دیگری نمیرود.
چاپ یک کلاینت یا یک استثنا هرگز اعتبارنامهای را نشان نمیدهد. ToString() روی کلاینت حالت و نشانی پایهٔ آن را میدهد و هیچ چیز دیگر.
نقطهٔ پایانی بدون متد
client.Raw.RequestAsync() هر مسیری را با اعتبارنامه، نشانی پایه، مهلت و سیاست تلاش دوبارهٔ کلاینت فراخوانی میکند. مسیر باید با یک / تکی شروع شود، و مسیری که از مبدأ نشانی پایه بیرون برود رد میشود.
var label = await client.Raw.RequestAsync("/labels", "POST", body: new Body { ["name"] = "Invoices" }); Console.WriteLine(label?["id"]);