Massen-Provisionierung von Lizenzen über die Keyright-Admin-API
Ein Enterprise-Deal mit 2000 Plätzen per POST nacheinander einzurichten ist langsam und lässt dich raten, wenn ein Stapel auf halbem Weg stirbt. So provisionierst du in Masse und führst gefahrlos erneut aus.
Ein einzelner POST /v1/admin/licenses pro Kunde ist die richtige Form für die alltägliche Abwicklung: Eine Zahlung geht ein, dein Webhook-Handler stellt eine Lizenz aus, fertig. Sie ist nicht mehr die richtige Form an dem Tag, an dem ein Vertriebsteam einen Enterprise-Vertrag mit 2000 Plätzen abschließt und jemand jeden dieser Plätze vor dem Kickoff-Termin provisionieren muss — oder wenn du einen Reseller einrichtest, dessen Katalog auf einen Schlag einige Hundert Lizenzen aussät.
Führe das als Schleife von 2000 einzelnen POSTs aus, und zwei Probleme treten sofort auf. Es ist langsam: ein paar Hundert Millisekunden Hin-und-Rückweg je Aufruf, seriell, ergeben Minuten an realer Zeit und viel Verbindungs-Verschleiß. Schlimmer noch, es ist mittendrin fragil: Stirbt der Job bei Element 1742 — ein Netzwerkaussetzer, ein Prozessneustart, ein Deployment — bleibt dir nur zu raten, welche Lizenzen existieren und welche nicht, und ein naiver Neustart riskiert, 1741 Duplikate zu prägen. Die Lösung ist der Stapelendpunkt der Admin-API, der viele Lizenzen in einer Anfrage ausstellt, für jedes Element ein Ergebnis meldet und gefahrlos erneut ausführbar ist.
Kernaussage: Provisioniere in Masse mit POST /v1/admin/licenses:batch statt einer POST-pro-Lizenz-Schleife. Gib der Anfrage einen Idempotency-Key auf Stapelebene und jedem Element seine eigene idempotencyKey (abgeleitet aus deiner Datensatz-ID) plus eine externalId für die Rückverknüpfung. Der Endpunkt verarbeitet die Elemente unabhängig und gibt ein Ergebnis pro Element zurück — created, duplicate oder failed — sodass ein fehlerhafter Datensatz nie die guten rückgängig macht und du nur die Fehler wiederholst. Für Tausende Elemente verwende die asynchrone Form: Der POST gibt dir eine Job-ID, du fragst den Job bis completed ab und liest dann dieselben Ergebnisse pro Element.
Warum die naive Schleife wehtut
Die Schleife sieht in einem Skript gut aus und bricht in der Produktion zusammen:
// ANTIMUSTER: ein POST pro Kunde, ohne Idempotenz, ohne Plan für Teilausfälle.
foreach (var seat in enterpriseDeal.Seats) // 2.000 Iterationen
{
var resp = await http.PostAsJsonAsync("/v1/admin/licenses", new {
product = "acme-suite", edition = "pro", customer = seat.CustomerId });
resp.EnsureSuccessStatusCode(); // wirft → die Schleife stirbt mittendrin
}
EnsureSuccessStatusCode() verwandelt den ersten transienten 503 in eine Ausnahme, die die Schleife abbricht, und da nichts festhält, welche Plätze bereits erfolgreich waren, ist dein einziger Ausweg, von vorn zu beginnen — und für jeden bislang verarbeiteten Kunden Lizenzen erneut auszustellen. Du kannst dieser Schleife Idempotenz pro Element aufpfropfen (und solltest es, wenn eine Schleife alles ist, was du hast), aber du zahlst weiterhin 2000 serielle Hin-und-Rückwege und erhältst 2000 unabhängige Erfolgs-/Fehlersignale, die du selbst zusammennähen musst.
Der Stapelendpunkt
Eine Anfrage trägt ein Array von Elementen. Die Anfrage erhält einen Idempotency-Key auf Stapelebene; jedes Element erhält seine eigene idempotencyKey und eine externalId, die es mit deinem Datensatz verknüpft.
POST /v1/admin/licenses:batch HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15
Content-Type: application/json
{
"defaults": { "product": "acme-suite", "edition": "pro", "seats": 1 },
"items": [
{ "externalId": "crm:row_8831", "licensee": "ana@acme.example",
"entitlements": { "export": "true" }, "idempotencyKey": "crm:row_8831" },
{ "externalId": "crm:row_8832", "licensee": "ben@acme.example",
"idempotencyKey": "crm:row_8832" }
]
}
defaults gilt für jedes Element, damit du product und edition nicht 2000-mal wiederholst; jedes an einem Element gesetzte Feld überschreibt den Standardwert. Die Antwort ist ein Multi-Status: ein übergreifender 207, mit einem Ergebnisobjekt pro Element in derselben Reihenfolge, in der du sie gesendet hast.
HTTP/1.1 207 Multi-Status
Content-Type: application/json
{
"created": 1,
"duplicate": 1,
"failed": 0,
"results": [
{ "externalId": "crm:row_8831", "status": "created",
"licenseId": "lic_7f3a9c2e" },
{ "externalId": "crm:row_8832", "status": "duplicate",
"licenseId": "lic_41b0d8a7" }
]
}
Drei Ergebnisse pro Element, und die Unterscheidung ist der ganze Zweck:
created— eine neue Lizenz wurde geprägt;licenseIdgehört dir zum Persistieren.duplicate— ein Element mit dieseridempotencyKeywurde bereits ausgestellt; die bestehende Lizenz-ID wird zurückgegeben und nichts Neues geprägt. Das macht einen Neustart sicher.failed— das Element wurde abgelehnt (ein fehlendes Pflichtfeld, ein fehlerhafteslicensee); einreasonund eincodesagen, warum. Die übrigen Elemente bleiben unberührt.
Ein Provisionierungs-Client, der sich gefahrlos erneut ausführen lässt
Der Helfer auf Anbieterseite erledigt vier Dinge: Er zerteilt deine Datensätze in Stapel, sendet jeden Stapel, sammelt die Ergebnisse pro Element und schreibt die Lizenz-IDs in dein Führungssystem zurück. Das Zerteilen ist wichtig: Eine einzelne Anfrage mit 2000 Elementen ist viel, um sie offen zu halten, und ein paar Hundert pro Stapel halten jede Anfrage schnell und reduzieren die Hin-und-Rückwege dennoch um zwei Größenordnungen.
public sealed class LicenseProvisioner(HttpClient http)
{
const int ChunkSize = 200;
public async Task<ProvisionReport> ProvisionAsync(
IReadOnlyList<SeatRecord> seats, CancellationToken ct)
{
var report = new ProvisionReport();
foreach (var chunk in seats.Chunk(ChunkSize))
{
var body = new BatchRequest
{
Defaults = new() { Product = "acme-suite", Edition = "pro", Seats = 1 },
Items = chunk.Select(s => new BatchItem
{
ExternalId = s.CrmRowId, // Verknüpfungsschlüssel zurück zu deinem CRM
Licensee = s.Email,
IdempotencyKey = s.CrmRowId, // derselbe Schlüssel macht Neustarts sicher
}).ToArray(),
};
using var req = new HttpRequestMessage(HttpMethod.Post, "/v1/admin/licenses:batch");
req.Headers.Add("Idempotency-Key", $"deal-{DealId}-{chunk[0].CrmRowId}");
req.Content = JsonContent.Create(body);
// Den ganzen Stapel zu wiederholen ist sicher: erstellte Elemente kommen als `duplicate` zurück.
var resp = await Resilience.Pipeline.ExecuteAsync(
async t => await http.SendAsync(req, t), ct);
var batch = await resp.Content.ReadFromJsonAsync<BatchResponse>(ct);
foreach (var r in batch!.Results)
report.Record(r); // licenseId persistieren oder Fehler protokollieren
}
return report;
}
}
Da jedes Element eine aus einer stabilen Datensatz-ID abgeleitete idempotencyKey trägt, dupliziert ein erneutes Ausführen des gesamten ProvisionAsync-Aufrufs — nach einem Absturz, einem halb fertigen Stapel oder einfach weil ein nächtlicher Abgleich erneut läuft — niemals. Bereits ausgestellte Elemente kommen als duplicate mit ihrer ursprünglichen Lizenz-ID zurück; nur wirklich neue Datensätze sind created. Die fehlgeschlagene Teilmenge erhältst du direkt aus report und kannst nur diese erneut senden, sobald der zugrunde liegende Datensatz korrigiert ist.
Große Mengen: der asynchrone Job
Oberhalb von einigen Hundert Elementen bevorzuge die asynchrone Form, um nicht eine einzelne HTTP-Anfrage offen zu halten, während Tausende Lizenzen geprägt werden. Füge "mode": "async" hinzu, und der Endpunkt gibt eine Job-ID statt Inline-Ergebnissen zurück:
POST /v1/admin/licenses:batch HTTP/1.1
Authorization: Bearer {admin_token}
Idempotency-Key: deal-ACME-2026-11-15
{ "mode": "async", "defaults": { "product": "acme-suite", "edition": "pro" },
"items": [ /* 2.000 Elemente */ ] }
HTTP/1.1 202 Accepted
{ "jobId": "job_b914f27c", "status": "pending", "total": 2000 }
Frage den Job ab, bis er sich stabilisiert, und lies dann dieselben results pro Element, die du synchron erhalten hättest:
BatchResponse job;
do
{
await Task.Delay(TimeSpan.FromSeconds(2), ct);
job = await http.GetFromJsonAsync<BatchResponse>(
$"/v1/admin/jobs/{jobId}", ct);
}
while (job!.Status is "pending" or "running");
foreach (var r in job.Results) report.Record(r); // created / duplicate / failed, wie zuvor
Der Job ist über seine ID adressierbar, sodass das Abfragen einen Neustart deines Provisionierungsprozesses überlebt: Du persistierst die jobId, und stirbt dein Worker, nimmst du das Abfragen desselben Jobs wieder auf, statt erneut auszustellen. Der Idempotency-Key auf Stapelebene garantiert, dass selbst ein zweimaliges Einreichen desselben Stapels denselben Job zurückgibt, statt einen zweiten zu starten.
Die Kundenseite: nichts Besonderes
All das Obige erzeugt gewöhnliche Lizenzen: Die Massenausstellung ist eine Bequemlichkeit für den Anbieter, kein anderer Lizenztyp. Jeder provisionierte Platz wird über das SDK genauso validiert wie ein einzeln ausgestellter — offline gegen den eingebetteten öffentlichen Schlüssel:
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = Embedded.PublicKey, // steckt in deinem Binary; kein Geheimnis
ServiceUrl = "https://licensing.example.com",
});
LicenseInfo info = client.Validate(); // offline, wirft nie
if (!info.IsValid || !info.IsEnabled("acme.export"))
return Gate.Deny("Der Export erfordert eine aktive Lizenz.");
Der Endnutzer erfährt nie, ob sein Platz einer von zweien oder einer von zweitausend war. Diese Trennung — Masse auf der Ausstellungsseite, identische Prüfung auf der Clientseite — ist das, was es dir erlaubt, einen Enterprise-Deal in einer einzigen abstimmbaren Operation einzurichten, ohne eine Zeile des Kontrollcodes zu ändern, den deine Kunden ausführen.
Durchsatz, kurz gefasst
Zwei praktische Grenzen prägen, wie du einen großen Rollout taktest. Halte die Teilstapel im niedrigen Hunderterbereich, damit jede Anfrage schnell bleibt und das Ergebnis-Array pro Element handhabbar bleibt. Und treibe die Stapel mit einer kleinen begrenzten Nebenläufigkeit statt tausend parallelen Anfragen an: Eine kurze Warteschlange von zwei oder drei Stapeln in Flucht genügt, um den Durchsatz des Ausstellungsdienstes auszulasten, ohne seine Ratenbegrenzungen auszulösen. Kommt ein Stapel ratenbegrenzt zurück, erledigt das das Wiederholen-mit-Jitter deiner Resilienz-Pipeline, und da der Stapel idempotent ist, ist die Wiederholung frei von Duplikaten.
Das ist die ganze Form der richtig gemachten Massen-Provisionierung: ein idempotenter Stapelaufruf pro Teilstapel, ein Ergebnis pro Element, das du über externalId mit deinen Datensätzen abstimmen kannst, ein asynchroner Job für die großen Rollouts und ein Neustart, der immer sicher ist, weil jedes Element seine eigene Identität kennt. Der Deal mit 2000 Plätzen wird zu einer Operation, die du ausführen, prüfen und erneut ausführen kannst — keine fragile Schleife, von der du hoffst, dass sie fertig wird.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.