Points de terminaison du hub

Un point de terminaison de hub est l’adresse réseau qu’un client utilise une fois que Thalovant a créé son identité.

Les hubs publics n’exposent que les protocoles activés pour ce hub. WSS est le chemin public par défaut. HTTPS et MQTT sont optionnels.

Une application de navigateur a aussi besoin d’une origine SDK approuvée avant que les appels venant d’un domaine qui vous appartient passent la vérification CORS de l’API.

En un coup d’œil

Type de point de terminaison	Idéal pour
WSS	Les clients en temps réel, les écouteurs d’événements, les flux vocaux et les agents.
HTTPS	Les sessions par interrogation des outils en ligne de commande, des tâches serveur, des vérifications d’état et des tests.
MQTT sur TLS	Le trafic d’appareils, de périphérie ou de réseaux contraints qui passe par un courtier.
Même identité	Tous les transports utilisent la même identité de client et la même politique d’accès.

Python, Node.js, Go et Rust prennent en charge les trois transports hors du navigateur. Kotlin, Swift et .NET prennent en charge WSS; le C embarqué fournit le protocole et l’application s’occupe du transport. Consultez les versions prises en charge avant de choisir un client.

Chaque transport est chiffré et authentifié avant que le trafic applicatif circule. Un socket ouvert, une réponse HTTP ou une connexion au courtier ne constituent pas à eux seuls une session. Conservez les clés enregistrées par le SDK d’un redémarrage à l’autre, comme l’explique Fichiers d’identité.

Champs de point de terminaison de l’identité

Les SDK privilégient les points de terminaison explicites du plan de données quand l’identité les contient.

{
  "data_plane_endpoints": {
    "wss": "wss://jokes.thalovant.io/public",
    "https": "https://jokes.thalovant.io/public",
    "mqtt": "mqtts://mqtt.thalovant.com:8883"
  },
  "protocols": {
    "wss": { "enabled": true },
    "http": { "enabled": true },
    "mqtt": { "enabled": true }
  }
}

Les identités plus anciennes ou minimales peuvent utiliser ces champs :

Champ	Signification
default_master	Hôte du hub ou adresse HTTPS complète.
default_port	Port à utiliser quand l’hôte n’en contient pas déjà un.
default_path	Préfixe de chemin optionnel utilisé par les hubs publics routés.

Quand utiliser WSS

Choisissez d’abord WSS quand le client peut garder une connexion ouverte.

Agent en direct

Un agent garde une session active et réagit aux réponses, aux événements de politique ou aux mises à jour d’affichage.

Flux vocal

Un client vocal envoie des énoncés et écoute les réponses parlées.

Abonné aux événements

Un client écoute les événements du hub et les traduit dans le modèle d’état propre à son application.

Quand utiliser HTTPS

Choisissez HTTPS quand le client a besoin d’une réponse directe, sans socket en direct.

En HTTPS, le SDK se connecte, s’authentifie, envoie des messages chiffrés et interroge le hub pour obtenir les réponses. Il garde pour ce travail une session de hub avec état; un ask représente plus d’une requête HTTP. Laissez le SDK conserver ses témoins de session, gérer l’interrogation et fermer la session une fois le travail terminé.

Utilisez une identité distincte pour chaque client actif de façon indépendante. Si une autre application détient déjà la session HTTP de la même identité, un nouveau /connect peut réussir sans vous donner de session à vous. Arrêtez le client qui la détient ou provisionnez une identité distincte avant de réessayer.

Tâche serveur

Une tâche envoie une requête d’utilisateur, lit la réponse et se termine.

Outil en ligne de commande

Un outil de développement ou de soutien envoie des diagnostics et affiche le résultat.

Client de test

Un test vérifie l’authentification, le routage du point de terminaison et l’analyse des réponses.

Vérifications de l’origine du navigateur

Une origine SDK approuvée permet le CORS d’API sans identifiants pour une seule origine de navigateur exacte. C’est distinct de la prise en charge des protocoles par le hub et de la façon dont le hub gère lui-même les origines et les témoins. Les sessions d’exécution HTTPS directes utilisent des témoins : l’approbation de l’origine auprès de l’API ne garantit donc pas à elle seule qu’une session de hub d’une origine à une autre fonctionnera.

Servez-vous-en pour les applications de navigateur qui doivent appeler Thalovant à partir d’un domaine approuvé. Ne vous en servez pas pour faire passer dans le code du navigateur des fichiers d’identité, des mots de passe du courtier, des liens de configuration, des flux de rafraîchissement ou des secrets de paiement.

Quand utiliser MQTT

Choisissez MQTT quand un courtier simplifie le déploiement par rapport au trafic direct vers le hub.

MQTT utilise TLS et des identifiants propres à chaque client. Une identité de client doit contenir le bloc mqtt avant que les SDK puissent utiliser ce transport.

{
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "<namespace>/<hub-id>/<client-id>",
    "tls": true
  }
}

Attention

Les mots de passe du courtier MQTT sont des secrets de client. Ne réutilisez pas les mêmes identifiants de courtier pour des clients sans lien entre eux.

Si un transport échoue

Symptôme	À vérifier d’abord
WSS fonctionne, mais HTTPS échoue	Confirmez que HTTPS est activé pour le hub.
HTTPS fonctionne, mais WSS échoue	Confirmez que le hub public expose la route WebSocket et le certificat TLS.
MQTT n’est pas pris en charge	Utilisez Python, Node.js côté serveur, Go ou Rust, puis confirmez que le hub et l’identité activent MQTT.
MQTT échoue tout de suite	Vérifiez le bloc MQTT de l’identité, les identifiants du courtier, TLS et les règles d’accès aux sujets.
L’authentification échoue sur tous les transports	Vérifiez le mot de passe et le point de terminaison de l’identité, restaurez l’état persistant du client s’il a été perdu et confirmez toute rotation prévue de la clé du serveur avant de changer les épinglages.
HTTPS se connecte, mais l’authentification expire	Cherchez un autre processus qui utilise la même identité et vérifiez que le client a conservé ses témoins de session.
Les requêtes aboutissent sur la mauvaise route	Vérifiez d’abord data_plane_endpoints, puis default_path.

Attention

Ne mettez pas de clés d’accès, de mots de passe, de clés cryptographiques, de mots de passe du courtier, de liens de configuration ni de fichiers d’identité dans les paquets côté client.