Was ist pixi Messaging?
pixi Messaging ermöglicht es Anwendungen zu vernetzen und entsprechend zu skalieren. Es kann sich entweder als bestimmte Komponente eines größeren Systems nutzen lassen oder ermöglicht die Verbindung zu externen Geräten oder Daten.
In pixi Messaging wird für Benachrichtigungen und den Datenaustausch zwischen Anwendungen in (nahezu) Echtzeit verwendet.
Der Message-Broker RabbitMQ wird für die pixi MQ-Infrastruktur benötigt. Er nutzt das Advanced Message Queuing Protocol (AMQP).
Bitte schauen Sie sich grundlegende Informationen zu diesem Protokoll auf dieser Seite an: AMQP concepts
Kosten und Einrichtung
Sofern sich Ihre Datenbank in unserem Rechenzentrum (Descartes Rechenzentrum) befindet, müssen Sie für die Aktivierung von pixi Messaging keine weitere Kosten für die Einrichtung einplanen. Sofern Sie bereits für die pixi API zahlen, sind alle Kosten bereits abgegolten bzw. inkludiert.
Sofern sich Ihre Datenbank auf Ihrem On-Premises Server befindet und Sie pixi Messaging gerne einsetzen möchte, wenden Sie sich zunächst an die Kollegen vom Account Management servicedesk@descartes.com.
Die Einrichtung und Aktivierung von pixi Messaging ist in diesem Fall ein kostenpflichtiger Service.
Die Aktivierung und Einrichtung wird in beiden Fällen durch die Kollegen vom Support übernommen.
Es wird hierfür ein Messaging Server verwendet, der von der Descartes Systems (Germany) GmbH gehostet wird, dieser erfordert das Öffnen der ausgehenden Ports 5671 & 5672 in Ihrer Firewall-Konfiguration.
Seit pixi 18.07 können Administratoren (User mit der Rolle pixi Administrator) die Messaging Events selbstständig (de)aktivieren. pixi Control Center - Messaging Events
Datenbanken mit der Version pixi 24.05 oder höher müssen die Datenbankeinstellung Messaging - Web Management aktivieren einschalten, wenn sie administrative Änderungen vornehmen wollen (standardmäßig deaktiviert).
Terminologie
Die folgenden Fachbegriffe werden verwendet:
Begriff |
Bedeutung |
pixi MQ |
pixi MQ steht für „pixi Message Queuing“. Hierbei sind Message Brokers, VHosts, Exchanges, Nutzer, Shovels, spezielle SQL und C#-Skripte und Jobs für den Austausch zwischen verschiedenen Applikationen definiert. |
MQS |
MQS steht für „Message Queue Server“ oder die „Message Broker“-Installation. Möglicherweise wird auch die Bezeichnung „Rabbit“ oder „Rabbit MQ“ verwendet, die ebenso die Technologie für den Message Broker impliziert. |
local MQ or |
LocalMQ/S ist der RabbitMQ Message Broker auf dem pixi Datenbank-Server. |
cloud MQ or |
CloudMQ/S ist die von RabbitMQ gehostete Instanz in der Amazon Cloud, in der alle VHosts, Exchanges und Nutzer sowie ihre Rechte hinterlegt sind, die die Infrastruktur pixiMQ Infrastruktur ausmachen. |
MQexchange |
MQexchanges sind Entitäten des Advanced Message Queuing Protocol (AMQP), mit denen Messages gesendet werden. Die Exchange leitet eine Message an eine oder mehr Queues. Der Algorithmus dahinter hängt von Exhange Types und Regeln ab - den sogenannten „Bindings“. Im pixi MQ starten lokale oder cloud-basierte Exchanges mit pixiEX. Beispiel: Die MQexchange für das Erstellen einer Rechnung lautet pixiEXinvoiceCreated.
Weitere Informationen zu den verschiedenen Exchange Types finden SIe hier AMQP concepts. Für pixi sind derzeit fanout und topic relevant. |
Shovel |
Shovel ist ein Plugin für rabbitMQ. Es wird für den Austausch von Messages zwischen lokalen MQexchanges und cloud-basiertes MQexchanges verwendet. pixi MQ nutzt das Plugin, um Messages vom lokalen zu cloud-basierten MQexchanges zu leiten, um sie auch an möglicherweise tieferliegende Queues zu senden. Weitere Informationen finden Sie hier: Rabbit MQ - Shovel plugin |
Queue |
Queues sind Container, die Messages enthalten, welche wiederum von Applikationen verarbeitet werden. Mehrere Queues können zum selben MQexchange gehören und dennoch unterschiedlich verarbeitet werden. Die Queues werden nach dem Rundlauf-Verfahren (Round-Robin) verarbeitet. Das bedeutet, dass eine Messages nach (!) der Verarbeitung gelöscht wird. Wenn mehrere Applikationen die gleiche Queue verwenden, ist das für die Lastenverteilung vorteilhaft. |
Consumer |
Consumers sind Applikationen, die von Queues Messages erhalten und verarbeiten. |
Producer |
Producer sind Applikationen, die Messages versenden. |
Welcher Prozess steckt dahinter?
Producer von Events (Messages, Benachrichtigungen) - z. B. pixi Datenbank, pixi Web- oder Dekstop-Applikationen - können eine oder mehr MQexchanges beginnend mit pixiEX.. (z. B. pixiEXinvoiceCreated) zum lokalen MQ senden.
Messages von MQexchange auf dem lokalen MQ werden so schnell wie möglich zum cloud-basierten MQ weitergeleitet.
In diesem MQ muss eine neue Queue (oder mehere Queues) erstellt und dem korrekten MQexchange zugeordnet werden (abhängig vom Message Type topic oder fanout).
Sie müssen Ihre Applikation(en) dahingehend konfigurieren, dass die eingehenden Messages der Queues verarbeitet werden können.
Hinweise:
- Wenn Queues nicht mehr benötigt werden, müssen sie von Nutzern manuell gelöscht werden.
- Die CLR (Common Language Runtime) und der Web-Service für das posten von Messages befinden sich auf der Seite des Producers.
Übersicht Messaging Events
Eine vollständige Liste aller Messaging Events (MQexchanges) und den Inhalt der Messages finden Sie hier: Übersicht Messaging Events
Beispiel Message
Im folgenden Beispiel wird ein Event für RequestPackageLabel zu pixiEXRequestPackageLabel gesendet. Gesendet wird im JSON-Format (JavaScript Object Notation).
Hinweis: Bitte beachten Sie, dass die Feldstruktur unter Umständen mehrere Einträge für verschiedene Events in einer Message zusammen enthält, wie beispielsweise bei ItemStockChanged.
{
"data":[
{
"invoiceKey": 361,
"invoiceNr": "PIX0000003",
"shippingAddress":{
"company": "pixi Software GmbH",
"firstName": "John",
"lastName": "Doe",
"street": "Ivory Avenue",
"houseNr": "1",
"city": "Detroit",
"zip": "12345",
"state": "",
"country": "GB", "eMail": "max.mustermann@email.com",
"phone": ""
},
"shopAddress":{
"name": "PIX",
"address": "Walter-Gropius-Str. 15",
"city": "Munich",
"zip": "80807",
"state": "",
"country": "DE",
"eMail": "pixi@pixi.eu",
"phone": ""
},
"packageInformation":{
"packageId": 14,
"grossWeight": 1.8,
"amount": 30.92,
"currency": "EUR",
"cashOnDelivery": 1
},
"shipVendor": "DPD"
}
]
}Verbindung herstellen
Parameter für die Verbindung
Um sich mit dem pixi Messaging Server zu verbinden, können Sie Ihre SOAP API-Anmeldeinformationen verwenden:
Name |
Example |
Description |
Messaging Server |
mq.pixi.eu |
Der Server mit dem Sie sich verbinden müssen |
Virtual Host (VHost) |
pixi_dem |
"pixi_" + Name der Kundendatenbank |
Username |
pixidem |
Ihr SOAP API-Benutzername |
Password |
******** |
Ihr SOAP API-Passwort |
Exchange Name |
pixiEXOrderCreated |
"pixiEX" + Name des Events; Liste list of MQ exchanges |
Wichtig: VHost und Username, müssen kleingeschrieben werden!
RabbitMQ Management
RabbitMQ Management bietet eine grafische Benutzeroberfläche für Messages und Channels und dient der Einrichtung von Exchanges und Queues. Bitte beachten Sie, dass Sie die Einstellung Messaging - Web Management aktivieren im Control Center aktivieren müssen, wenn Sie das Webinterface nutzen möchten.
Verbindungstest
Nachdem Sie eine neue Queue erstellt haben, empfehlen wir einen Verbindungstest. Das folgende Beispiel greift eine benannte Queue mit der Debian library amqp-tools ab:
amqp-get --url='amqp://Username:Password@MessagingServer:5672/VHost' -q QueueNameIn diesem Beispiel sind Parameter angegeben:
amqp-get --url='amqp://pixidem:********@mq.pixi.eu:5672/pixi_dem' -q TestQueueBeispiele für das Binding
Die folgenden beiden Beispiele zeigen, wie Sie Ihre Applikation für Python und PHP für Exchanges vorbereiten:
Python
#!/usr/bin/env python
import pika
# use the same credidentials as for standard pixi SOAP API
credentials = pika.credentials.PlainCredentials("pixidev", "pixidevpassword", erase_on_connect=True)
connection = pika.BlockingConnection(pika.ConnectionParameters(host='mq.pixi.eu',
virtual_host="pixi_dev", credentials=credentials))
channel = connection.channel()
result = channel.queue_declare(exclusive=True)
queue_name = result.method.queue
channel.queue_bind(exchange='pixiEXInvoiceCreated', queue=queue_name)
print(' [*] Waiting for new invoices. To exit press CTRL+C')
def callback(ch, method, properties, body):
print(" [x] %r" % body)
# Add your actions here
channel.basic_consume(callback,
queue=queue_name,
no_ack=True)
channel.start_consuming()
Weitere Informationen zu RabbitMQ Exchanges mit Python finden Sie hier: RabbitMQ - Python
PHP
Im folgenden Beispiel wird PHP mit der AMQP library for PHP (amqplib) verwendet:
<?php
require_once __DIR__ . '/vendor/autoload.php';
use PhpAmqpLib\Connection\AMQPStreamConnection;
$connection = new AMQPStreamConnection('mq.pixi.eu', 5672, 'pixidev', 'pixidevpassword','pixi_dev');
$channel = $connection->channel();
list($queue_name, ,) = $channel->queue_declare("", false, false, true, false);
$channel->queue_bind($queue_name, 'pixiEXInvoiceCreated');
echo ' [*] Waiting for new invoices. To exit press CTRL+C', "\n";
$callback = function($msg){
echo ' [x] ', $msg->body, "\n";
// Add your actions here
};
$channel->basic_consume($queue_name, '', false, true, false, false, $callback);
while(count($channel->callbacks)) {
$channel->wait();
}
$channel->close();
$connection->close();
Weitere Informationen zu RabbitMQ Exchanges mit PHP finden Sie hier: RabbitMQ - PHP
Vorteile gegenüber dem API "Pull"
In diesem Abschnitt haben wir einige Vorteile von pixi Messaging im Vergleich zur gewöhnlichen API-Abfrage aufgeführt.
Queues
Informationen, die mit pixi Messaging versendet werden, gehen nicht „verloren“. Messages bestehen so lange, bis sie verarbeitet werden.
Falls eine Ziel-Applikation nicht erreichbar ist, wird die Message verarbeitet, sobald die Applikation wieder verfügbar ist.
Push Messages
Informationen (z. B. Bestelldatum, Rechnungserstellung oder Aktualisierung einer Rechnung) werden aktiv zur Queue geleitet. Applikation müssen lediglich an die Queues angebunden sein, um neue Messages zu erhalten. Es ist also nicht erforderlich, dass Applikationen von sich aus einen Abruf von Messages starten. pixi Messaging sendet die Messages automatisch durch das Push-Model.
Szenarien
Shipcloud - Drucken von Versandlabels
ShipCloud ist ein externer Anbieter für Versandlabels verschiedenster Dienstleister (z. B. DHL, DPD, UPS, GLS etc.).
Um ein Versandlabel zu erstellen und zurück zu pixi zu senden, muss die Message RequestPackageLabel aktiviert sein, damit die Informationen zu einer neu erstellen Rechnung zu ShipCloud gesendet werden.
Ein Versandlabel wird dann bei ShipCloud im PDF-Format in Echtzeit erstellt und die URL zum Label wird über die API zurück zur pixi Datenbank gesendet.
Für 1-Scan-Shipping™ ist es noch wichtiger, dass dieser Prozess in Echtzeit abläuft, da der Versand unmittelbar nach der Rechnungserstellung erfolgt.
Bestandsexport in Echtzeit
pixi exportiert den Lagerbestand über viele verschiedene Kanäle mit unterschiedlichen Regeln. Daraus resultieren Performance-Probleme durch die Arbeitslast, die entsteht, wenn der Server exportierte Daten an URLs senden muss. Dabei ist der Prozessablauf so gestaltet, dass der erste Channel möglicherweise länger braucht, so dass nachfolgende Daten warten müssen. Das kann dazu führen, dass die Bestände in den Consumer-Applikationen und der Datenbank für einen kurzen Zeitraum nicht synchron sind.
Die Lösung hierfür wären MQExchanges (Notifications). Eine MQExchange könnte vom Typ topic sein, wobei topic die LagerplatzID beinhaltet, an dem sich der Bestand geändert hat. Jedes Mal, wenn pixi Daten auf die übliche Art und Weise exportiert und auf das Ende des Prozesses wartet, würde gleichzeitig eine Notification zum MQexchange gesendet, so dass an die an MQexchange gebundenen Queues Messages über Bestandsänderungen nahezu in Echtzeit erhalten.
Das Senden an MQexchange ist äußerst schnell und beeinflusst den Datenbank-Server nicht in dem Maße, in dem es der alte Export tut. Wenn Consumer (Export Channel wie Afterbuy, TB.One oder Online-Shops) eine andere Art der Verarbeitung benötigen, kann die topic-Herangehensweise verwendet werden. Dann hängt von der Geschäftslogik der Consumer-Applikationen ab, welche Bestände eingelesen werden (nach Lagerplatz und insgesamt).
Es kann auch eine zusätzliche MQexchange kann erstellt werden, die Lagebestände in Batches (Chunks) weitergibt. Somit müssen Consumer nicht immer Webhooks nutzen, um Daten von Queues abzufragen. Sie können die Daten aus der Queue verarbeiten, sobald sie vom Webhook benachrichtigt werden.