कॉन्फ़िगरेशन
क्लाइंट का हर विकल्प, वह एनवायरनमेंट से क्या पढ़ता है, और क्या अस्वीकार करता है।
विकल्प
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 के नामों वाले named आर्ग्युमेंट हैं, जैसे 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पर बेस URL, जो वह पता है जिस पर सर्वर सुनता है। उसी पोर्ट के साथ127.0.0.1इस्तेमाल करें।- खाली id, या सिर्फ़ बिंदुओं से बना id, जिसे URL पार्सर हटा देगा।
- रीडायरेक्ट का पालन करना। पैकेज जो HTTP क्लाइंट बनाता है वह कभी किसी रीडायरेक्ट का पालन नहीं करता, इसलिए क्रेडेंशियल कभी किसी दूसरे होस्ट तक नहीं जाता।
किसी क्लाइंट या एक्सेप्शन को प्रिंट करने पर कभी कोई क्रेडेंशियल नहीं दिखता। क्लाइंट पर ToString() उसका मोड और बेस URL देता है, और कुछ नहीं।
बिना मेथड वाला एंडपॉइंट
client.Raw.RequestAsync() क्लाइंट के क्रेडेंशियल, बेस URL, टाइमआउट और रीट्राई नीति के साथ किसी भी पाथ को कॉल करता है। पाथ एक ही / से शुरू होना चाहिए, और जो पाथ बेस URL के ओरिजिन से बाहर जाता है वह अस्वीकार कर दिया जाता है।
var label = await client.Raw.RequestAsync("/labels", "POST", body: new Body { ["name"] = "Invoices" }); Console.WriteLine(label?["id"]);