rustedf.cloud
Menu

Gerar milhares de PDFs em C#: ritmo, 429 e novas tentativas seguras

Publicado em 3 min de leitura

Faturas de fim de mês, um certificado para cada participante, um extrato para cada cliente: mais cedo ou mais tarde você precisa de milhares de PDFs, não de um. O código óbvio, uma lista de tarefas e Task.WhenAll, envia todas as requisições de uma vez, e o serviço responde 429 para a maioria delas. Este guia monta um executor de lotes que respeita a taxa do seu plano, repete o que é seguro repetir e pode ser parado e retomado sem refazer o mesmo trabalho. Ele usa o estilo de cliente tipado do guia de C# e ASP.NET Core.

Conheça os limites primeiro

  • A taxa de requisições pertence à conta. O seu plano define quantas requisições por minuto a conta pode fazer, e todas as chaves a compartilham. Uma segunda chave não aumenta o limite; só divide a mesma cota. Os números estão na página de planos.
  • Uma renderização custa um crédito, e uma que falha não custa nada. Um crédito é tomado quando a renderização começa e devolvido se ela falha, então repetir uma falha é seguro.
  • Sem créditos, vem um 402. Nada foi renderizado, e qualquer outra requisição falharia do mesmo jeito, então o lote inteiro deve parar.

Confira o saldo antes de começar. GET /v1/me devolve o seu plano e os seus créditos:

public sealed record Me(string Plan, long Credits);
var me = await http.GetFromJsonAsync<Me>("v1/me", cancellationToken);
if (me!.Credits < jobs.Count)
throw new InvalidOperationException($"{me.Credits} créditos para {jobs.Count} documentos.");

Controle o ritmo das chamadas

Um token bucket deixa passar uma requisição de tempos em tempos, seja qual for o número de workers. O .NET tem um em System.Threading.RateLimiting:

using System.Threading.RateLimiting;
var limiter = new TokenBucketRateLimiter(new TokenBucketRateLimiterOptions
{
TokenLimit = 1,
TokensPerPeriod = 1,
ReplenishmentPeriod = TimeSpan.FromSeconds(60.0 / requestsPerMinute),
QueueLimit = int.MaxValue,
QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
AutoReplenishment = true,
});

Defina requestsPerMinute um pouco abaixo da taxa do seu plano, para que outras chamadas da mesma conta ainda caibam. Cada worker pega um token antes de enviar uma requisição.

O executor

using System.Collections.Concurrent;
using System.Net;
using System.Net.Http.Json;
public sealed record Job(string Number, string TemplateId, string Locale, Dictionary<string, object?> Data);
public sealed class OutOfCreditsException : Exception;
public sealed class BatchRenderer(HttpClient http, TokenBucketRateLimiter limiter, int workers)
{
public async Task<IReadOnlyList<string>> RunAsync(
IEnumerable<Job> jobs, string folder, CancellationToken cancellationToken)
{
var failed = new ConcurrentBag<string>();
var options = new ParallelOptions
{
MaxDegreeOfParallelism = workers,
CancellationToken = cancellationToken,
};
await Parallel.ForEachAsync(jobs, options, async (job, token) =>
{
var path = Path.Combine(folder, $"{job.Number}.pdf");
if (File.Exists(path)) return; // feito em uma execução anterior
try
{
var pdf = await RenderAsync(job, token);
await File.WriteAllBytesAsync(path + ".part", pdf, token);
File.Move(path + ".part", path, overwrite: true);
}
catch (OutOfCreditsException) { throw; } // para o lote inteiro
catch (Exception) when (!token.IsCancellationRequested)
{
failed.Add(job.Number); // um documento ruim não para os outros
}
});
return failed.ToArray();
}
}

Três hábitos estão nesse código:

  • Grave em um nome temporário e depois mova. Uma execução interrompida no meio nunca deixa meio arquivo com cara de pronto.
  • Pule o que já existe. Inicie o mesmo lote de novo e ele só faz os documentos que faltam, então retomar uma execução parada não custa nada.
  • Guarde as falhas. O método devolve os números que falharam, para você olhá-los, corrigir os dados e rodar de novo.

Repita só o que é seguro

Este método pertence à classe BatchRenderer:

private async Task<byte[]> RenderAsync(Job job, CancellationToken cancellationToken)
{
for (var attempt = 1; ; attempt++)
{
using var lease = await limiter.AcquireAsync(1, cancellationToken);
using var response = await http.PostAsJsonAsync(
"v1/render",
new { template_id = job.TemplateId, data = job.Data, locale = job.Locale },
cancellationToken);
if (response.IsSuccessStatusCode)
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
if (response.StatusCode == HttpStatusCode.PaymentRequired)
throw new OutOfCreditsException();
var retry = response.StatusCode is HttpStatusCode.TooManyRequests
or HttpStatusCode.ServiceUnavailable
|| (int)response.StatusCode >= 500;
if (!retry || attempt == 5)
throw new InvalidOperationException($"{job.Number}: {(int)response.StatusCode}");
var wait = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(Math.Pow(2, attempt));
await Task.Delay(wait + TimeSpan.FromMilliseconds(Random.Shared.Next(0, 500)), cancellationToken);
}
}
Status O que o executor faz
200 Devolve o PDF.
402 Para o lote inteiro: sem créditos, nada foi renderizado.
429, 503, 5xx Espera o Retry-After, ou recua, e tenta de novo, até cinco vezes. Uma renderização que falha não consome crédito.
Outros 4xx Não repete. A requisição está errada; o documento é registrado como falha.

Um pequeno atraso aleatório é somado a cada espera, para que workers que foram desacelerados juntos não voltem no mesmo instante.

Um caso a evitar

Se o serviço termina uma renderização mas o seu lado nunca recebe a resposta, por exemplo por um tempo limite de rede, e você envia a requisição de novo, é uma renderização nova e custa outro crédito. Mantenha o tempo limite do HttpClient acima do limite de tempo do seu plano, para que um documento lento não seja abandonado cedo demais, e leia o X-Render-Id de cada resposta para o seu log, para distinguir os documentos que foram feitos dos que não foram.

Mantenha cada requisição pequena

Envie um template salvo e só os dados, como neste guia, e não o HTML inteiro a cada vez. O tamanho de uma entrada é limitado pelo seu plano; uma requisição grande demais responde 413. Veja Gerar com um template salvo.

Leia Erros e limites e Gerar um PDF. Para uma versão da mesma ideia baseada em fila, veja Gerar PDF no Azure Functions.

  • Código e integrações

    Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs

    Transforme uma view Razor em PDF no ASP.NET Core com uma chamada de API: renderizador de views, view pronta para impressão, action MVC e handler do Razor Pages.

    3 min de leitura

  • Código e integrações

    Converter página web em PDF em C# sem navegador headless

    Busque uma página com HttpClient e transforme o HTML em PDF com uma chamada de API em C#. Quais páginas isso atende, quais não e como conferir antes de depender.

    3 min de leitura

  • Código e integrações

    Gerador de relatório PDF em C#: tabela paginada com totais

    Monte um relatório em PDF em C# a partir de uma lista de objetos: tabela com cabeçalho repetido em cada página, total, número de página e contagem de páginas.

    3 min de leitura

← Todos os posts