Nextriv → Twój broker
Połączenie wychodzące z Nextriv do publicznego FQDN brokera organizacji.
Dla deweloperów
MQTT outbound
Eksportuj pomiary Nextriv w czasie rzeczywistym do publicznego brokera MQTT swojej organizacji. Poniżej znajdziesz wymagania połączenia, zamrożony kontrakt wiadomości v1 i zasady niezawodnego konsumenta.
Kontrakt w skrócie
Integracja jest jednokierunkowym eksportem pomiarów. Nextriv łączy się z brokerem klienta; nie przyjmuje komend MQTT i nie udostępnia wewnętrznego brokera.
MQTT 3.1.1 + TLS
TLS 1.2 lub nowszy z pełną weryfikacją certyfikatu i nazwy hosta.
QoS 1
Dostawa co najmniej raz, retain=false; konsument deduplikuje po event_id.
Tylko pomiary
v1 publikuje zdarzenia pomiarowe, nie alarmy, ACK, komendy ani statusy urządzeń.
Konfiguracja krok po kroku
Konfiguracją zarządza administrator organizacji w sekcji Ustawienia → Integracje → MQTT; operacje są zablokowane w trybie pomocy zdalnej. Hasło brokera i pełny PEM własnego CA są write-only; panel może pokazać użytkownika brokera oraz metadane CA, takie jak fingerprint, subject i termin ważności.
- 1
Potwierdź dostęp
Organizacja potrzebuje aktywnego planu PRO, a konfigurację wykonuje jej administrator.
- 2
Przygotuj broker
Utwórz dedykowanego użytkownika z prawem CONNECT i PUBLISH wyłącznie do topików integracji.
- 3
Dodaj konfigurację
Podaj nazwę, FQDN, port, główny topic (topic_root), użytkownika brokera, hasło i opcjonalny pakiet CA. Nowa konfiguracja pozostaje wyłączona.
- 4
Uruchom test
Potwierdź operację hasłem konta. Nextriv połączy się, opublikuje wiadomość testową i zaczeka na PUBACK. Limit wynosi 10 prób w ciągu 600 sekund dla danej integracji i administratora.
- 5
Włącz wysyłkę
Włączenie jest dostępne dopiero po poprawnym teście dokładnie bieżącej konfiguracji.
Zmiana hosta, portu, danych logowania, trybu CA lub głównego topiku unieważnia test. Przed ponownym włączeniem przetestuj nową rewizję.
Wymagania brokera i TLS
Walidacja celu działa w trybie fail-closed. Broker musi być osiągalny w Internecie przez publiczny rekord IPv4 i przedstawiać certyfikat pasujący do FQDN.
| Element | Wymaganie |
|---|---|
| Protokół | MQTT 3.1.1 przez TLS 1.2 lub nowszy; bez połączeń plaintext. |
| Host | Publiczny FQDN z publicznym rekordem A. Literalny adres IP, adres prywatny i host IPv6-only są odrzucane. |
| Port | 1024–65535; typowa wartość to 8883. |
| Uwierzytelnienie | Dedykowany użytkownik brokera do 256 B i hasło do 4 KiB. Anonimowe logowanie i mTLS nie są obsługiwane w v1. |
| Autoryzacja | CONNECT oraz PUBLISH do topików integracji. Nextriv nie potrzebuje SUBSCRIBE. |
| CA systemowy | Publiczny łańcuch zaufania rozpoznawany przez systemowy trust store. |
| Własny CA | Pełny pakiet PEM do 64 KiB i 32 certyfikatów CA; bez kluczy prywatnych i bez wygasłych certyfikatów. |
Jeśli broker filtruje adres źródłowy, dodaj do allowlisty stały adres IPv4 wyjścia Nextriv: 23.88.47.92. Zmiana adresu zostanie zapowiedziana przed przełączeniem.
Poza zakresem v1
- broker w prywatnej sieci, VPN albo tunel zestawiany przez Nextriv
- połączenie bez TLS, tryb skip-verify, literalny adres IP lub broker IPv6-only
- certyfikat klienta mTLS, anonimowe logowanie i komendy przychodzące
- dwukierunkowy bridge albo dostęp do wewnętrznej infrastruktury MQTT Nextriv
Topiki
Każda integracja dostaje niezmienny stream_id. device_id jest tym samym publicznym identyfikatorem, którego używa External API.
Zdarzenia pomiarowe
<topic_root>/<stream_id>/v1/measurements/<device_id>Wiadomość testowa
<topic_root>/<stream_id>/v1/testReguły topic root
- od 1 do 128 bajtów UTF-8; końcowy topik pomiarowy ma maksymalnie 221 bajtów
- segmenty ASCII A–Z, a–z, 0–9, kropka, podkreślenie i myślnik, rozdzielone pojedynczym /
- bez początkowego i końcowego /, pustych segmentów, wildcardów + i # oraz segmentów . i ..
- pierwszy segment nie może być równy $SYS
- stream_id nie zmienia się przy edycji integracji; nowy powstaje dopiero dla nowej integracji
Payload pomiaru v1
Jedna wiadomość reprezentuje jedno zdarzenie pomiarowe i zawiera całą jego mapę values. Nie powstaje osobny PUBLISH dla każdej metryki.
Przykładowa wiadomość JSON
{
"schema": "nextriv.measurement.v1",
"event_id": "evt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"change_seq": 12001,
"id": "measurement_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"device_id": "dev_0123456789abcdef0123456789abcdef",
"measured_at": "2026-07-10T10:00:00Z",
"received_at": "2026-07-10T10:00:02Z",
"published_at": "2026-07-10T10:00:03Z",
"source": "live",
"values": {
"temperature": {
"value": 3.4,
"unit": "°C"
}
}
}Pola kontraktu
Daty są zapisane jako RFC 3339/ISO 8601 w UTC. Wartość metryki jest liczbą lub stanem logicznym, a jednostka należy do publicznego katalogu metryk.
| Pole | Znaczenie |
|---|---|
| schema | Stała nextriv.measurement.v1. |
| event_id | Stabilny identyfikator zdarzenia i klucz deduplikacji. |
| change_seq | Numer pomocny przy diagnostyce kolejności i luk; nie jest globalnym ciągłym licznikiem. |
| id | Publiczny identyfikator pomiaru. |
| device_id | Publiczny identyfikator urządzenia, wspólny z External API. |
| measured_at | Czas wykonania pomiaru u źródła. |
| received_at | Czas przyjęcia pomiaru przez Nextriv. |
| published_at | Czas tej próby publikacji do brokera. |
| source | live, device_history, replay albo virtual. |
| values | Co najmniej jedna metryka jako { value, unit }; zestaw zależy od urządzenia i źródła. |
Nazwę i lokalizację urządzenia pobierz po device_id przez External API. MQTT celowo nie wysyła lokalizacji, współrzędnych, jakości sygnału, surowych ramek ani wewnętrznych identyfikatorów. Zobacz endpoint urządzenia w External API.
Konsument powinien ignorować nieznane pola najwyższego poziomu. Usunięcie pola albo zmiana jego typu lub semantyki wymaga nowego schematu i topiku v2.
Payload testowy
Test używa osobnego schematu i topiku, dlatego można odseparować go od produkcyjnego przetwarzania pomiarów.
Wiadomość nextriv.test.v1
{
"schema": "nextriv.test.v1",
"test_id": "test_0123456789abcdef0123456789abcdef",
"sent_at": "2026-07-10T10:40:00Z",
"stream_id": "stream_0123456789abcdef0123456789abcdef"
}Udany test potwierdza wyłącznie połączenie, autoryzację PUBLISH i odebranie PUBACK przez Nextriv. Nie potwierdza subskrypcji ani przetworzenia po stronie systemu klienta.
Dostawa, duplikaty i kolejność
QoS 1 oznacza semantykę co najmniej raz. Projekt konsumenta musi zakładać ponowienia, przerwy i niezależne strumienie urządzeń.
Deduplikuj po event_id
Awaria po PUBACK, ale przed zapisem sukcesu przez Nextriv może spowodować ponowną publikację tego samego zdarzenia.
Nie zakładaj globalnej kolejności
Nie ma wspólnego porządku między urządzeniami. change_seq służy do diagnostyki, nie do wyliczania kompletności danych całej organizacji.
Toleruj ponowienia
Błędy przejściowe są ponawiane. Wadliwa wiadomość nie blokuje następnych, a dostawa wymagająca uwagi może zostać ponowiona ręcznie.
Traktuj published_at jako czas próby
Przy duplikacie pola zdarzenia i topik pozostają stabilne, ale published_at może się zmienić.
Zakres zaległości
- Kolejka eksportowa obejmuje zdarzenia przyjęte po pierwszym włączeniu integracji.
- Zaległości mogą zostać odtworzone wyłącznie w 30-dniowym oknie retencji.
- Historia sprzed pierwszego włączenia nie jest publikowana automatycznie.
- Zmiana celu nie przekierowuje cicho zaległości starej rewizji do nowego brokera.
Zmiany konfiguracji i bezpieczne operacje
Operacje w panelu wymagają bieżącego hasła administratora. Hasło brokera i pełny PEM własnego CA nie są później zwracane do przeglądarki; użytkownik brokera i bezpieczne metadane CA pozostają widoczne.
Edycja unieważnia test
Po zmianie celu, danych logowania, CA lub głównego topiku uruchom test ponownie przed włączeniem.
Zaległości wymagają decyzji
Po zmianie rewizji administrator jawnie wybiera ponowne przypisanie oczekujących dostaw albo ich odrzucenie.
Utrata planu zatrzymuje wysyłkę
Konfiguracja pozostaje zachowana. Po powrocie do PRO administrator wybiera Wznów ręcznie; nowy test jest potrzebny tylko wtedy, gdy konfiguracja lub poprzedni test nie są już bieżące.
Wyłączenie nie usuwa konfiguracji
Ręczne Wyłącz zachowuje konfigurację, ale unieważnia autoryzację testu — przed kolejnym Włącz uruchom nowy test. Usunięcie jawnie odrzuca pozostający backlog.
Najważniejsze statusy panelu
| Status | Znaczenie |
|---|---|
| Aktywna | Pomiary są przekazywane do skonfigurowanego brokera. |
| Wyłączona | Konfiguracja jest zachowana, ale wysyłka pozostaje wyłączona. |
| Wymaga testu | Przetestuj dokładnie bieżącą konfigurację przed włączeniem. |
| Zaległości | Co najmniej część pomiarów oczekuje na dostarczenie. |
| Wymaga uwagi | Dostawa wyczerpała automatyczne próby; administrator może sprawdzić kolejkę i ręcznie ponowić dostawę. |
| Błąd połączenia | Wysyłka jest czasowo wstrzymana po serii błędów brokera. |
| Wstrzymana przez plan | Wysyłka zatrzymuje się natychmiast, a konfiguracja i kolejka pozostają zachowane. |
| Wymaga ręcznego wznowienia | Po powrocie do PRO wybierz Wznów ręcznie. Test powtórz tylko wtedy, gdy panel oznacza go jako nieaktualny. |
Diagnostyka
Panel pokazuje bezpieczny kod błędu i identyfikator żądania. Nie zapisuj danych logowania ani pełnego CA w zgłoszeniu pomocy.
| Kod | Znaczenie i działanie |
|---|---|
| unsafe_target | Podaj publiczny FQDN; po rozwiązaniu nie może wskazywać adresu prywatnego ani zarezerwowanego. |
| dns_failed | Sprawdź publiczny rekord A, delegację DNS i brak zależności od split-DNS. |
| unsupported_address_family | Broker musi być dostępny przez publiczny IPv4; host IPv6-only nie jest obsługiwany. |
| tcp_timeout / tcp_connect_failed | Sprawdź port, firewall, routing i nasłuch brokera. |
| connack_timeout / connection_rejected | Sprawdź MQTT 3.1.1, limit połączeń i politykę CONNECT. |
| tls_verify_failed | Sprawdź pełny łańcuch certyfikatu, ważność oraz komplet własnego CA. |
| tls_hostname_mismatch | Certyfikat musi zawierać SAN pasujący do skonfigurowanego FQDN. |
| tls_certificate_expired | Odnów certyfikat serwera lub wygasły certyfikat w łańcuchu. |
| auth_rejected | Sprawdź dedykowanego użytkownika brokera i aktualne hasło; anonimowe logowanie nie jest obsługiwane. |
| puback_timeout | Sprawdź działanie brokera, prawo PUBLISH do obu wzorców topików integracji i czy QoS 1 kończy się odpowiedzią PUBACK. |
| rate_limit_exceeded | Odczekaj i ponów próbę. Limit wynosi 10 testów w ciągu 600 sekund dla danej integracji i administratora. |
| test_authorization_expired | Odśwież panel, potwierdź operację hasłem i uruchom nowy test. |
Zasady bezpieczeństwa konsumenta
- Użyj osobnego użytkownika brokera i minimalnych praw ACL dla każdej integracji.
- Przechowuj payload jako dane organizacji; kontroluj dostęp, retencję i rejestrowanie zdarzeń (logi) po swojej stronie.
- Nie umieszczaj hasła, własnego CA ani identyfikatorów wiadomości w publicznych logach.
- Monitoruj duplikaty po event_id oraz luki diagnostyczne, ale nie traktuj MQTT jako kanału exactly-once.
Chcesz uruchomić integrację MQTT?
Opisz broker, politykę TLS/ACL i planowany wolumen. Pomożemy bezpiecznie przygotować konfigurację i konsumenta.