Začínáme se Socket.io

API Socket.io je určené ke streamování telemetrických dat v reálném čase a poskytuje jen živé aktualizace (žádná historická ani absolutní data). Data, která zmeškáte během odpojení, se znovu neposílají — aktuální stav nebo chybějící data po opětovném připojení získáte přes REST API. Tento návod vás provede navázáním spojení v reálném čase mezi Dronetagem a vaší aplikací přes Socket.io.

Parametry spojení

Ke spojení použijte ve svém klientovi Socket.io tyto konfigurační parametry:

Host: https://api.dronetag.app
Path: /v2/airspace/socket.io
Verze klienta: v3 nebo v4

Host a path se liší

Dejte si pozor na konfiguraci — host musí obsahovat jen doménu (https://api.dronetag.app) a path se zadává zvlášť. Záměna těchto dvou parametrů vede k chybám spojení.

Výběr klienta Socket.io

Socket.io podporuje řada knihoven v mnoha programovacích jazycích. Úplný seznam podporovaných klientských implementací najdete zde.

Ověření relace

Relaci Socket.io ověříte stejným přístupovým tokenem, jaký používáte pro požadavky na REST API. Jak přístupový token získat, popisuje návod k přihlašovacím údajům k API.

Pro Socket.io používejte OpenID Connect

Výše odkazovaná stránka o ověřování uvádí dva způsoby ověřování k API: osobní přístupové tokeny (PAT) a OpenID Connect (OIDC). API Socket.io osobní přístupové tokeny nepodporuje, proto pro Socket.io používejte jen tokeny OIDC.

Ověření není povinné. Relace bez tokenu dostává jen veřejně dostupná data, ověřená relace navíc i data, ke kterým má přístup váš účet.

Pokud pošlete neplatný token, server spojení odmítne a váš klient dostane connect_error se zprávou unauthorized.

Nativní ověření v Socket.io

U klientů, které podporují nativní ověřování Socket.io, můžete přístupový token předat přímo v konfigurační volbě auth.

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  auth: "eyJhbGciOiJSUzI1NiIsInR5c...",
});

Více o ověřování v Socket.io najdete v dokumentaci Socket.io.

Bearer token v úvodním požadavku (handshake)

Pokud váš klient volbu auth nepodporuje, můžete přístupový token poslat v hlavičce Authorization úvodního požadavku (handshake):

let socket = io("https://api.dronetag.app", {
  path: "/v2/airspace/socket.io",
  extraHeaders: { Authorization: "Bearer eyJhbGciOiJSUzI1NiIsInR5c..." }
});

Hodnota hlavičky musí mít tvar Bearer <token>, jinak server spojení odmítne se zprávou wrong bearer token format.

Tento postup se hodí i při testování v nástrojích, jako je Postman, které nativní ověřování obvykle nepodporují. Stačí přidat hlavičku Authorization na kartě Headers v Postmanu.

Ověření navázaného spojení

Ověřit můžete i spojení, které už je navázané: pošlete přístupový token v události authenticate. Server ji potvrdí odpovědí {"result": "ok"}. Je-li token neplatný, server odpoví {"result": "not_authenticated"} a spojení zůstane otevřené jako neověřené, takže dostává jen veřejně dostupná data.

Odběr událostí

Po připojení můžete naslouchat těmto událostem:

serverinfo – posílá se jednou, hned po navázání spojení. Obsahuje informace o serveru, například server_version, environment a your_sid (ID vaší relace, jak ho vidí server).
telemetry_ua – telemetrie bezpilotního letadla (UA)
telemetry_operator – telemetrie operátora
telemetry_system – systémová telemetrie
operation – změny operací

Každá událost telemetry_ua, telemetry_operator, telemetry_system a operation nese pole zpráv DUMP, ne jednu zprávu. Telemetrické události jsou omezené na nastavený viewport (viz níže), události operation viewport neomezuje. Událost operation nese zprávy OperationUpdate, které obsahují jen nedávné změny operace, ne její úplný stav.

Nejaktuálnější a úplný seznam dostupných událostí, jejich obsahu a odpovědí najdete v naší dokumentaci AsyncAPI.

Nastavení a aktualizace výřezu (viewport)

Stejně jako u REST API musíte zadat geografickou oblast, o kterou se vaše aplikace zajímá.

Po připojení musí váš klient poslat úvodní událost viewport, která určí sledovanou geografickou oblast. Kdykoli se oblast zájmu změní, musí klient oblast aktualizovat novou událostí viewport. Každá událost viewport nahradí dříve nastavený viewport. Pokud viewport nenastavíte, relace nedostane telemetrii z žádné oblasti.

Viewport platí jen pro jedno spojení. Při každém připojení i opětovném připojení ho klient musí poslat znovu.

Viewport je řetězec ve tvaru lon_min,lat_min,lon_max,lat_max — zeměpisná délka a šířka ve stupních, oddělené čárkami bez mezer. Viewport nastavený například na Prahu může vypadat takto: emit("viewport", "14,49.9,15,50.3").

V aplikacích Dronetagu se například mapa dynamicky posouvá podle toho, co uživatel dělá. Po navázání spojení pošle aplikace úvodní viewport a při posouvání mapy ho aktualizuje. Doporučujeme tyto aktualizace tlumit (debounce), aby klient neposílal nový viewport při každém drobném posunu mapy.

Viewport vždy nastavujte uvážlivě. Musí pokrýt celou oblast vašeho zájmu, ale zároveň nesmí být zbytečně velký — dostávali byste data, která nechcete, a mohly by nastat problémy s výkonem. Doporučujeme přidat na každé straně dostatečnou rezervu několika kilometrů. Největší podporovaná plocha viewportu je zhruba 6 milionů km², takovým extrémním hodnotám se ale raději vyhněte.

Server každou událost viewport potvrdí jednou z těchto odpovědí:

{"result": "ok"} – viewport je nastavený.
{"result": "invalid-param", "messages": [...]} – viewport nemá očekávaný tvar nebo jsou jeho hodnoty mimo povolený rozsah.
{"result": "bbox_area_too_large", "messages": [...]} – plocha viewportu přesahuje největší podporovanou plochu. Dál platí dříve nastavený viewport.

Odpověď přečtete tak, že při odeslání události předáte callback pro potvrzení (acknowledgement), například socket.emit("viewport", "14,49.9,15,50.3", (response) => console.log(response)).

Řazení telemetrie

Ve výchozím stavu je telemetrie v každé události seřazená vzestupně podle času. Řazení můžete pro každou telemetrickou událost změnit událostí ordering. Jejím obsahem musí být řetězec v kódování JSON, který názvům událostí přiřadí jednu z těchto hodnot:

time – vzestupně (výchozí)
-time – sestupně

socket.emit("ordering", JSON.stringify({
  telemetry_ua: "-time",
  telemetry_operator: "time",
  telemetry_system: "time",
}));

Server událost potvrdí odpovědí {"result": "ok"}, nebo {"result": "invalid-param", "messages": [...]}, pokud obsah není platný. Stejně jako viewport platí i řazení jen pro jedno spojení.

Ukázky kódu

Níže je několik krátkých ukázek, které vám se Socket.io pomohou začít v různých programovacích jazycích:

Připojení v Node.js
Připojení v Pythonu

const { io } = require('socket.io-client');

const socket = io('https://api.dronetag.app', {
  path: '/v2/airspace/socket.io',
  auth: 'eyJhbGciOiJSUzI1NiIsInR5c...'
});

socket.on('connect', () => {
  // The viewport must be sent after every (re)connect
  socket.emit('viewport', '14,49.9,15,50.3', (response) => {
    console.log('Viewport response:', response);
  });
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

socket.on('telemetry_ua', (batch) => {
  for (const telemetry of batch) {
    console.log('UA telemetry received:', telemetry);
  }
});

import socketio

sio = socketio.Client()

@sio.event
def connect():
    # The viewport must be sent after every (re)connect
    sio.emit(
        'viewport',
        '14,49.9,15,50.3',
        callback=lambda response: print(f'Viewport response: {response}'),
    )

@sio.event
def connect_error(data):
    print(f'Connection error: {data}')

@sio.event
def telemetry_ua(batch):
    for telemetry in batch:
        print(f'UA telemetry received: {telemetry}')

sio.connect(
    'https://api.dronetag.app',
    socketio_path='/v2/airspace/socket.io',
    auth='eyJhbGciOiJSUzI1NiIsInR5c...'
)

sio.wait()

Parametry spojení​

Výběr klienta Socket.io​

Ověření relace​

Nativní ověření v Socket.io​

Bearer token v úvodním požadavku (handshake)​

Ověření navázaného spojení​

Odběr událostí​

Nastavení a aktualizace výřezu (viewport)​

Řazení telemetrie​

Ukázky kódu​