Pub/sub - API - REST

Lecture prérequise : Architecture Pub/sub.

Vue d'ensemble

Avant d'utiliser l'API REST pub/sub, un [endpoint] REST(../details/endpoint/index.md) doit être créé. Vous pouvez également vous familiariser avec cette fonctionnalité en utilisant le compte de démonstration intégré, décrit à la fin de ce chapitre.

L'intégration REST avec publish/subscribe s'articule autour de quatre opérations fondamentales:

Opération REST
Publication POST /zato/pubsub/topic/{topic_name}
Récupation les messages des files d'attente PATCH /zato/pubsub/topic/{topic_name}
Abonnement POST /zato/pubsub/subscribe/topic/{topic_name}
Désabonnement DELETE /zato/pubsub/subscribe/topic/{topic_name}

Les appels REST qui fournissent les informations d'identification HTTP Basic Auth sont en mesure de publier des messages vers des sujets, à condition que l'appelant dispose des autorisations de publication appropriées pour les sujets auxquels les messages sont envoyés.

Chaque endpoint pub/sub est en mesure de créer un abonnement à condition que l'appelant utilise les informations d'identification HTTP Basic Auth et que des autorisations d'accès suffisantes soient en place pour permettre au endpoint de s'abonner à un sujet de son choix. Une clé d'abonnement est créée en interne par les serveurs. Un endpoint ne peut pas s'abonner au même sujet plus d'une fois.

À tout moment, les points d'extrémité déjà abonnés peuvent recevoir les messages les plus récents en attente dans leurs files d'attente. Il s'agit d'une opération qui modifie l'état du serveur, c'est pourquoi la méthode PATCH est utilisée à la place de la méthode GET.

Les applications qui créent des abonnements à l'aide de cette API sont censées recevoir périodiquement leurs messages (style pull). En revanche, si des abonnements REST sont créés par les administrateurs de Zato à l'aide de web-admin, Zato pourra délivrer lui-même les nouveaux messages aux destinataires (style notify).

Si un abonnement n'est plus nécessaire, un endpoint REST peut se désabonner, ce qui invalidera et supprimera la clé d'abonnement du endpoint.

Publication des messages

Le nom du sujet doit être fourni dans le chemin de l'URL. Les autres paramètres sont fournis sous forme de données utiles JSON.

S'il n'y a pas d'abonnés au sujet au moment de la publication du message, le message sera conservé dans le sujet. Lorsque les abonnés arrivent, le message sera déplacé vers leurs files d'attente en arrière-plan dès qu'ils auront créé leurs abonnements.

Le type MIME est lu à partir de l'en-tête HTTP Content-Type et est transformé en text/json s'il est égal à application/x-www-form-urlencoded. Tous les autres paramètres sont envoyés dans des requêtes JSON.

Verbe URL
POST /zato/pubsub/topic/{topic_name}

Request

Paramètre Type de données Requis Notes
data any Yes Données réelles du message qui est publié. Elles peuvent être de n'importe quel type, par exemple une chaîne ou un objet JSON incorporé.
priority integer --- Priorité du message de 1 à 9 (1=min). La valeur par défaut est 5 si elle n'est pas indiquée.
expiration integer --- Expiration en secondes, il n'y a pas de valeur par défaut.
correl_id string --- ID de corrélation. Si le message appartient à une série de messages, il peut être utilisé pour les corréler.
in_reply_to string --- Si le message est une réponse à un message précédent, il s'agit du champ contenant la valeur de l'ID du message précédent.
ext_client_id string --- Une chaîne arbitraire identifiant de manière unique l'application appelante ou son instance - utilisée à des fins de journalisation et d'audit.
has_gd bool --- Indique si le message qui est publié doit être régi par la garantie de livraison (si True) ou non. La valeur par défaut est False.

Réponse

Paramètre Type de données Requis Notes
msg_id string Yes ID unique attribué au message d'entrée

Samples

OK, données envoyées et ID du message renvoyé :

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/topic//zato/demo/sample \
  -d '{"data" : "hello", "priority":2}''
{"msg_id" : "zpsm1a150dbfb8ab3cb676a471b5"}
$

Erreur, aucune donnée envoyée en entrée :

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/topic//zato/demo/sample
{
  "result":"Error",
  "cid":"aea73f42fb12382b278e9a3a",
  "details":"Invalid input"}
$

Récupérer les messages des files d'attente

Le nom du sujet est fourni dans le chemin de l'URL. Si un abonnement pour ce sujet existe, tous les messages sont retournés.

Verbe URL
PATCH /zato/pubsub/topic/{topic_name}

Samples

OK, les messages sont renvoyés. Notez que les messages sont toujours triés dans l'ordre "Last-In-First-Out" (LIFO), c'est-à-dire du plus récemment publié au plus ancien. Notez également que la clé d'abonnement actuelle, celle qui a été retournée lorsque le client s'est abonné, est également produite parmi d'autres détails de chaque message.

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/topic//zato/demo/sample
  {
      "data": "This is a sample message #2",
      "delivery_count": 0,
      "expiration": 998877,
      "expiration_time_iso": "2022-07-04T17:32:46.224820",
      "ext_client_id": "CLIENT-EXT-2",
      "has_gd": true,
      "mime_type": "text/plain",
      "priority": 5,
      "pub_time_iso": "2022-07-04T17:16:07.347820",
      "size": 27,
      "sub_key": "zpsk.rest.ca023c8",
      "topic_name": "/zato/demo/sample"
  },
  {
      "data": "This is a sample message #1",
      "delivery_count": 0,
      "expiration": 998877,
      "expiration_time_iso": "2022-07-17:31:31.043810",
      "ext_client_id": "CLIENT-EXT-1",
      "has_gd": true,
      "mime_type": "text/plain",
      "priority": 5,
      "pub_time_iso": "2022-07-04T17:15:49.809810",
      "size": 27,
      "sub_key": "zpsk.rest.ca023c8",
      "topic_name": "/zato/demo/sample"
  },
$

OK, aucun message disponible:

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/topic//zato/demo/sample
[]
$

Erreur, cet abonnement n'existe pas. Dans ce cas, l'appelant reçoit toujours une liste vide en réponse ..

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/topic//zato/demo/sample
[]
$

... mais en même temps, une entrée sera écrite dans server.log indiquant qu'une souscription pour cet abonné n'existe pas dans le cluster auquel l'appelant accède.

INFO - Could not find sub by input `{'cluster_id': 1, 'sub_key': 'invalid'}`

Abonnement

Le nom de la rubrique doit être fourni dans l'URL, il n'y a pas d'autres paramètres de requête en JSON.

En réponse, un dictionnaire JSON rempli, décrit ci-dessous, est renvoyé si l'appel a réussi et des détails d'erreur sinon.

Ce n'est pas une erreur d'appeler ce endpoint même si le client est déjà abonné. Si c'est le cas, au lieu de la clé d'abonnement et de la profondeur de la file d'attente actuelle, un message JSON vide sera retourné et un message d'information sera écrit dans server.log, indiquant qu'un tel abonnement existe déjà, mais qu'un autre ne sera pas créé.

Verbe URL
POST /zato/pubsub/subscribe/topic/{topic_name}

Requête

n/a

Réponse

Paramètre Type de données Requis Notes
sub_key string --- Une clé d'abonnement unique générée pour ce client. Elle doit être traitée comme un secret et gardée en conséquence.
queue_depth integer --- Combien de messages ont déjà été mis en file d'attente pour le client appelant dans cette rubrique

Samples

OK, l'abonnement a été créé et une réponse vide a été renvoyée comme prévu:

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/subscribe/topic//zato/demo/sample
{}
$

Erreur, l'abonnement à la rubrique d'entrée existe déjà pour ce client:

$ curl -XPOST http://user:pass@localhost:17010/zato/pubsub/subscribe/topic//zato/demo/sample
{
 "result":"Error",
 "cid":"7cbc0c1906efd9a1ab932ba1",
 "details":"Subscription to topic `/zato/demo/sample` already exists"
}
$

Désabonnement

Le nom de la rubrique doit être fourni dans le chemin URL. Si l'appel réussit, la clé d'abonnement de l'appelant sera supprimée et le client devra se réabonner avant de pouvoir à nouveau recevoir des messages.

Ce n'est pas une erreur d'appeler ce endpoint même si le client n'est pas abonné. Cependant, s'il ne l'est pas, un message d'information sera écrit dans server.log, indiquant qu'un tel abonnement n'existe pas.

Verbe URL
DELETE /zato/pubsub/subscribe/topic/{topic_name}

Samples

OK, désabonnement réussi:

$ curl -XDELETE http://user:pass@localhost:17010/zato/pubsub/subscribe/topic//zato/demo/sample
{}
$

Erreur - informations d'identification invalides (les détails sont dans server.log):

$ curl -XDELETE http://pubsub:abc@localhost:17010/zato/pubsub/subscribe/topic//zato/demo/sample
{
 "result":"Error",
 "cid":"2c6a0f7f4e75e949d26b5439",
 "details":"You are not allowed to access this resource"
}

Format des données

  • Toutes les demandes et réponses sont toujours en JSON.
  • L'authentification se fait toujours par HTTP Basic Auth.
  • En réponse, soit des données commerciales sont renvoyées si l'appel a réussi, soit des informations de base sur les erreurs sont renvoyées et tous les détails des erreurs sont dans server.log.

    {"sub_key": "zpsk.rest.be946f", "queue_depth": 35}
    
  • Une erreur s'est produite:

    {
     "result":"Error",
     "cid":"ca3898ee8cbffeaff4086826",
     "details":"You are not allowed to access this resource"
    }
    

Logging

  • Tous les messages d'erreur sont accompagnés d'un CID dans la réponse JSON - il s'agit d'un ID de corrélation attribué de manière unique à une requête HTTP particulière.
  • Les CID sont également toujours retournés dans l'en-tête de réponse X-Zato-CID, qu'il y ait eu une erreur ou non.
  • Les CIDs peuvent être trouvés dans les fichiers http_access.log du serveur qui a traité une invocation particulière.
  • En cas d'erreur, le fichier server.log du serveur où elle s'est produite, contient des détails, y compris une trace complète.

Données de démonstration

  • Tous les clusters Zato sont livrés avec un ensemble d'objets de démonstration :

  • Sujet /zato/demo/sample.

  • Endpoint zato.pubsub.demo.endpoint avec des permissions pour les publications et les abonnements aux sujets correspondant au motif /zato/demo/*.

  • L'endpoint par défaut n'a pas de mot de passe prédéfini - il est généré aléatoirement (UUID4) dans chaque environnement.

  • Pour utiliser l'endpoint, modifiez le mot de passe de sa définition HTTP Basic Auth dans Dashboard (nom d'utilisateur zato.pubsub.demo.secdef).

  • Ensuite, l'endpoint peut être utilisé à des fins de démonstration en utilisant les appels REST décrits dans ce chapitre.

Sujets connexes