Zum Inhalt

REST-Referenz

Alle Queue-Methoden liegen unter /Queue. Jede Antwort enthält success und bei Fehlern errorMessage (siehe Fehler). Antworten der Queue-Methoden enthalten außerdem einen hashCode, der für Long Polling verwendet werden kann.

Methode Route Rolle Beschreibung
GET /Info read Version der API
PUT /Queue/enqueue/{id} write Nachrichten in eine Queue legen
POST /Queue/dequeue/{idPattern} write Nachrichten aus einer oder mehreren Queues abholen
POST /Queue/confirmdequeue/{id} write Verarbeitete Nachricht bestätigen
GET /Queue/all/{idPattern} read Nachrichten lesen, ohne sie zu entfernen
GET /Queue/length/{idPattern} read Anzahl der Nachrichten
PUT /Queue/register/{idPattern} write/admin Queue anlegen oder ihre Eigenschaften ändern
GET /Queue/properties/{idPattern} read Eigenschaften und Zustand von Queues
GET /Queue/queuenames read Namen aller Queues
DELETE /Queue/remove/{idPattern} write/admin Queues oder ihre Nachrichten entfernen
DELETE /Queue/deletemessage/{id} admin Einzelne Nachricht löschen

Methoden mit idPattern brauchen die Rolle admin, wenn das Muster mehr als eine Queue trifft (register, remove). Siehe Rollen.

Queue-Namen

Eine Queue wird über einen eindeutigen Namen (id) angesprochen. Namen dürfen Kleinbuchstaben, Ziffern, _, - und . enthalten:

  • ein Name beginnt mit einem Kleinbuchstaben oder einer Ziffer,
  • auf einen Punkt muss ein Buchstabe, eine Ziffer, _ oder - folgen (kein .., kein Punkt am Ende),
  • ein Name hat höchstens 128 Zeichen.

Gültig: queue1, test.queue, appname.main.in, my_queue-123. Ungültig: ., .., a..b, queue., _queue.

Muster

Methoden mit idPattern arbeiten auf mehreren Queues gleichzeitig. Ein Muster ist eine kommagetrennte Liste aus Namen und Platzhalter-Ausdrücken:

Muster Trifft
queue1,queue2 queue1 und queue2
test.* alle Queues, die mit test. beginnen
queue1,test.* queue1 und alle Queues, die mit test. beginnen

Info

GET /Info liefert die Version der API.

GET /Info
curl -u admin-client:secret http://localhost:9091/Info
var info = await client.ApiInfoAsync();
Console.WriteLine(info.Version);
Antwort
{
  "success": true,
  "version": {
    "major": 4,
    "minor": 0,
    "build": 0,
    "revision": 0,
    "majorRevision": 0,
    "minorRevision": 0
  }
}

Enqueue

PUT /Queue/enqueue/{id} legt Nachrichten in eine Queue. Der Body ist ein JSON-Array aus Strings. Eine fehlende Queue wird angelegt.

Enqueue gilt ganz oder gar nicht: Kann eine Nachricht nicht gespeichert werden, wird keine Nachricht eingereiht.

PUT /Queue/enqueue/test.queue1
Content-Type: application/json

["Hello World", "Test Message"]
curl -u worker:secret -X PUT http://localhost:9091/Queue/enqueue/test.queue1 \
     -H "Content-Type: application/json" \
     -d '["Hello World", "Test Message"]'
await client.EnqueueAsync(["Hello World", "Test Message"]);
mqnet http://localhost:9091 -q test.queue1 -c enqueue -m "Hello World"
Antwort
{ "success": true }

Dequeue

POST /Queue/dequeue/{idPattern} holt Nachrichten aus einer oder mehreren Queues ab. Die Nachrichten werden entfernt und stehen anderen Consumern nicht mehr zur Verfügung.

Parameter In Standard Beschreibung
idPattern Pfad Queue-Name oder Muster
count Query 1 Anzahl der Nachrichten (begrenzt durch MaxDequeueCount)
register Query false Ohne Wirkung, aus Kompatibilitätsgründen vorhanden

Existiert eine Queue nicht, wird sie angelegt und [] zurückgegeben. Andere Prozesse sehen dann über queuenames, dass jemand diese Queue abarbeitet.

Bestätigung

Hat die Queue confirmationPeriodSeconds > 0, trägt die Nachricht requireConfirmation: true. Sie muss innerhalb dieser Zeit mit confirmdequeue bestätigt werden, sonst kommt sie zurück in die Queue.

POST /Queue/dequeue/test.*?count=10
curl -u worker:secret -X POST "http://localhost:9091/Queue/dequeue/test.*?count=10"
var result = await client.DequeueAsync(count: 10);

foreach (var message in result.Messages ?? [])
{
    Console.WriteLine($"{message.Queue}: {message.Value}");
}
mqnet http://localhost:9091 -q test.queue1 -c dequeue
Antwort
{
  "success": true,
  "hashCode": 1234567,
  "messages": [
    {
      "queue": "test.queue1",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "value": "Hello World",
      "creationDateUTC": "2025-11-03T15:01:02.123Z",
      "requireConfirmation": true,
      "confirmationPeriod": 60
    }
  ]
}

Dequeue bestätigen

POST /Queue/confirmdequeue/{id}?messageId={messageId} bestätigt, dass eine Nachricht verarbeitet wurde. Erst dann wird die Nachricht endgültig aus der Queue entfernt.

Mit aktivierter Authentifizierung kann nur der Client eine Nachricht bestätigen, der sie abgeholt hat.

POST /Queue/confirmdequeue/test.queue1?messageId=d290f1ee-6c54-4b01-90e6-d701748f0851
curl -u worker:secret -X POST \
     "http://localhost:9091/Queue/confirmdequeue/test.queue1?messageId=d290f1ee-6c54-4b01-90e6-d701748f0851"
await client.ConfirmDequeueAsync(message.Id);
Antwort
{ "success": true }

Alle Nachrichten

GET /Queue/all/{idPattern} liefert die Nachrichten von Queues, ohne sie zu verändern.

Parameter In Standard Beschreibung
max Query 0 Maximale Anzahl an Nachrichten (0: alle)
unconfirmedOnly Query false Nur Nachrichten, die abgeholt, aber noch nicht bestätigt wurden (nur Queues mit confirmationPeriodSeconds > 0)
GET /Queue/all/test.*?max=100
curl -u dashboard:secret "http://localhost:9091/Queue/all/test.*?max=100"
var result = await client.AllMessagesAsync(max: 100);

Die Antwort hat dasselbe Format wie bei Dequeue.

Länge

GET /Queue/length/{idPattern} liefert die Anzahl der Nachrichten pro Queue.

GET /Queue/length/test.*
curl -u dashboard:secret http://localhost:9091/Queue/length/test.*
var result = await client.LengthAsync();
Antwort
{
  "success": true,
  "queues": {
    "test.queue1": { "queueLength": 1, "unconfirmedItems": 0 }
  }
}

Register

PUT /Queue/register/{idPattern} legt eine Queue an (falls sie nicht existiert) oder ändert die Eigenschaften bestehender Queues. Alle Parameter sind optionale Query-Parameter; weggelassene Parameter behalten ihren aktuellen Wert.

Eigenschaft Typ Beschreibung
lifetimeSeconds int Die Queue wird gelöscht, nachdem sie so lange leer und unbenutzt war. 0: nie.
itemLifetimeSeconds int Nachrichten, die in dieser Zeit nicht abgeholt werden, werden gelöscht. 0: nie.
confirmationPeriodSeconds int Abgeholte Nachrichten müssen in dieser Zeit bestätigt werden, sonst kommen sie zurück in die Queue. 0: keine Bestätigung.
maxUnconfirmedItems int Maximale Anzahl abgeholter, aber unbestätigter Nachrichten. Ist sie erreicht, liefert dequeue nichts, bis Nachrichten bestätigt werden.
maxUnconfirmedItemsStrategy int 0 Absolute: das Maximum gilt für die Queue. 1 PerClient: das Maximum gilt pro Client.
suspendEnqueue bool true: es können keine Nachrichten hinzugefügt werden.
suspendDequeue bool true: es können keine Nachrichten abgeholt werden. Die Nachrichten bleiben erhalten.
PUT /Queue/register/orders?lifetimeSeconds=3600&confirmationPeriodSeconds=60
curl -u worker:secret -X PUT \
     "http://localhost:9091/Queue/register/orders?lifetimeSeconds=3600&confirmationPeriodSeconds=60"
await client.RegisterAsync(lifetimeSeconds: 3600, confirmationPeriodSeconds: 60);
>> orders register

Die Antwort hat dasselbe Format wie bei Properties.

Properties

GET /Queue/properties/{idPattern} liefert die Eigenschaften und den Zustand von Queues. Anfragen mit dem Header X-MQ-SilentAccess: true aktualisieren lastAccessUTC nicht (wird vom Dashboard verwendet).

GET /Queue/properties/orders
curl -u dashboard:secret http://localhost:9091/Queue/properties/orders
var result = await client.PropertiesAsync();
Antwort
{
  "success": true,
  "hashCode": 1234567,
  "queues": {
    "orders": {
      "lastAccessUTC": "2025-11-03T15:01:02.123Z",
      "lastModifiedUTC": "2025-11-03T15:01:02.123Z",
      "length": 0,
      "unconfirmedItems": 0,
      "dequeuingClientsCount": 0,
      "dequeuingClients": {},
      "lifetimeSeconds": 3600,
      "itemLifetimeSeconds": 0,
      "confirmationPeriodSeconds": 60,
      "maxUnconfirmedItems": null,
      "maxUnconfirmedItemsStrategy": 0,
      "suspendEnqueue": false,
      "suspendDequeue": false
    }
  }
}

Queue-Namen (Liste)

GET /Queue/queuenames liefert die Namen aller Queues.

GET /Queue/queuenames
curl -u dashboard:secret http://localhost:9091/Queue/queuenames
var result = await client.QueueNamesAsync();
Antwort
{ "success": true, "queueNames": [ "orders", "test.queue1" ] }

Remove

DELETE /Queue/remove/{idPattern}?removeType={removeType} entfernt Queues oder ihre Nachrichten.

removeType Beschreibung
0 (Standard) Queue entfernen
1 Alle Nachrichten entfernen
2 Die unbestätigten Nachrichten entfernen
DELETE /Queue/remove/test.*?removeType=0
curl -u admin-client:secret -X DELETE "http://localhost:9091/Queue/remove/test.*?removeType=0"
await client.RemoveAsync(RemoveType.Queue);
Antwort
{ "success": true }

Nachricht löschen

DELETE /Queue/deletemessage/{id}?messageId={messageId} löscht eine einzelne Nachricht aus einer Queue.

DELETE /Queue/deletemessage/test.queue1?messageId=d290f1ee-6c54-4b01-90e6-d701748f0851
curl -u admin-client:secret -X DELETE \
     "http://localhost:9091/Queue/deletemessage/test.queue1?messageId=d290f1ee-6c54-4b01-90e6-d701748f0851"
await client.DeleteMessage(message.Id);
Antwort
{ "success": true }