設定
クライアントのすべてのオプション、環境から読むもの、拒否するもの。
オプション
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 | 1 回の試行にかけられる時間です。既定値は 30 秒で、TimeSpan.Zero にすると無効になり、アップロードは少なくとも 10 分待ちます。 |
| MaxRetries | 失敗したリクエストを再試行する回数です。既定値は 2 で、0 にすると 1 回だけ送信します。 |
| UserAgent | User-Agent ヘッダーを置き換えます。既定では openemail-dotnet/ にバージョンを続けたものです。 |
| Headers | すべてのリクエストに追加されるヘッダー。 |
省略したものはすべて環境から読み取られます。OPENEMAIL_API_KEY、次に OPENEMAIL_ACCESS_TOKEN、そして OPENEMAIL_BASE_URL です。client.Mode は、キーが live キーか test キーかを示します。
キャンセルとタイムアウト
すべてのメソッドは最後に CancellationToken を受け取ります。キャンセルすると再試行を含めて呼び出しはすぐに止まり、OperationCanceledException がスローされます。Timeout は 1 回ごとの試行を制限します。
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: を受け取り、その呼び出しに限って別のキーで動作します。そのため 1 つのプロセスが 1 つのクライアントで複数のワークスペースを扱えます。
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
アプリケーション全体で 1 つのクライアントを登録してください。破棄すべき独自の接続を持たないため、シングルトンが適切なライフタイムです。
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、タイムアウト、再試行ポリシーを使って任意のパスを呼び出します。パスは 1 つの / で始まる必要があり、ベース URL のオリジンから外れるパスは拒否されます。
var label = await client.Raw.RequestAsync("/labels", "POST", body: new Body { ["name"] = "Invoices" }); Console.WriteLine(label?["id"]);