CloudTAK REST API -integraatio: ulkoisten järjestelmien yhdistäminen taktiseen verkkoon

Kirjoittaja: Corvus Intelligence Engineering Team · Tietoja tiimistä →

29. toukokuuta 2026 12 min lukuaika

CloudTAK:n REST API muuttaa TAK-palvelimen passiivisesta reitittimestä aktiiviseksi integraatiohubiksi. Sen sijaan että vaatisi jokaisen tietolähteen puhuvan natiivista CoT:a TCP/TLS:n kautta — ainoa polku vanhaan TAK Serveriin — CloudTAK tarjoaa täydellisen HTTP- ja WebSocket-pinnan, jota mikä tahansa moderni järjestelmä voi kutsua: sensoriarraysit, logistiikka-alustat, AI-päättelypipelineset, SIGINT-syötteet ja mukautetut koontinäytöt. Tämä opas kattaa yksityiskohtaisesti kaikki tärkeimmät API-pinnat: autentikointi, CoT-injektio, reaaliaikainen track-suoratoisto, tehtävienhallinta, datapakettien lataus, ryhmähallinto, webhookit ja TAKpilot AI-kopilotti integraatioesimerkkinä. Jos sinun täytyy ensin käynnistää CloudTAK-palvelin, katso oppaamme CloudTAK-palvelimen käyttöönotosta.

Autentikointi: JWT-tokenit, API-avaimet ja laajuudet

CloudTAK REST API pakottaa autentikoinnin jokaiseen päätepisteeseen paitsi terveystarkistukseen (GET /api/health). Tuetaan kahta tunnistetietotyyppiä, molemmat välitetään HTTP-otsikkona Authorization: Bearer <token>.

JWT-tokenit

JWT-tokenit ovat lyhytikäisiä ja myönnetään käyttäjäkohtaisesti. Hanki yksi lähettämällä tunnisteet kirjautumispäätepisteeseen:

curl -s -X POST https://tak.yourdomain.com:8443/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "operator01", "password": "s3cur3p@ss"}' \
  | jq -r '.token'

Oletuselinaika on 86400 sekuntia (24 tuntia); konfiguroitavissa CLOUDTAK_JWT_TTL:n kautta. JWT-tokenit sisältävät käyttäjän roolin ja ryhmäjäsenyydet claims-tietoina.

API-avaimet

API-avaimet ovat pitkäikäisiä tokeneita, jotka sopivat automaattisiin palvelu-palvelu-integraatioihin. Luo ne admin-API:n kautta:

curl -s -X POST https://tak.yourdomain.com:8443/api/token \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sensor-array-east",
    "scopes": ["cot:write"],
    "rateLimit": 500
  }' | jq -r '.token'

Tuetut laajuudet ja mitä ne avaavat:

Laajuus	Antaa pääsyn
`cot:write`	CoT-tapahtumien injektio POST /api/cot:n kautta
`cot:read`	Historiallisten trackien kysely GET /api/cot:n kautta
`events:subscribe`	Yhteys WebSocket-virtaan /api/ws:ssä
`mission:write`	Tehtävien luominen, päivittäminen ja poistaminen
`package:write`	Datapakettien ja liitteiden lataaminen
`group:write`	Ryhmien luominen ja jäsenyyksien hallinta
`admin`	Kaikki laajuudet sekä käyttäjähallinta ja palvelinkonfiguraatio

Peruuta avain milloin tahansa: DELETE /api/token/{id}. Listaa aktiiviset avaimet: GET /api/token.

Perus-URL ja nopeusrajoitukset

Kaikki REST-päätepisteet tarjotaan osoitteessa https://<host>:8443/api/. Oletusnopeusrajoitus on 100 pyyntöä sekunnissa per API-avain. HTTP 429 -vastaukset sisältävät Retry-After-otsikon. OpenAPI-spesifikaatio on saatavilla osoitteessa GET /api/docs.

CoT-injektio: POST /api/cot

CoT-injektiopäätepiste on ensisijainen polku sijaintiraporttien, kontaktimarkkereiden, hälytysten ja minkä tahansa muiden CoT-tapahtumien syöttämiseen taktiseen kuvaan ulkoisista järjestelmistä.

XML-hyötykuorma

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<event version="2.0"
       uid="sensor-east-001"
       type="a-f-G-U-C"
       how="m-g"
       time="2026-05-29T14:32:00Z"
       start="2026-05-29T14:32:00Z"
       stale="2026-05-29T14:37:00Z">
  <point lat="50.4501" lon="30.5234" hae="145.0" ce="10.0" le="5.0"/>
  <detail>
    <contact callsign="SENSOR-EAST-01"/>
    <remarks>Maatutka-kontakti, nopeus 12 km/h, suunta 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

JSON-hyötykuorma

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "logistics-truck-07",
    "type": "a-f-G-U-C",
    "callsign": "LOG-07",
    "lat": 50.4610,
    "lon": 30.5190,
    "hae": 138.0,
    "ce": 5.0,
    "le": 3.0,
    "staleSeconds": 300,
    "remarks": "Huoltokuljetus, arvioitu saapumisaika tarkistuspisteelle 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK sarjalistaa tämän JSON:n täydelliseksi CoT XML -kirjekuoreksi sisäisesti. Onnistunut injektio palauttaa HTTP 201. Tapahtuma leviää välittömästi kaikille tilatuille asiakkaille ja WebSocket-virralle.

Track-suoratoisto: WebSocket /api/ws

Taktisen kuvan reaaliaikaiseen kulutukseen WebSocket-päätepiste tarjoaa jatkuvan, pienen viiveen CoT-tapahtumavirran.

Yhdistäminen ja tilaaminen

// Node.js-esimerkki 'ws'-kirjastolla
const WebSocket = require('ws');

const ws = new WebSocket('wss://tak.yourdomain.com:8443/api/ws', {
  headers: { 'Authorization': `Bearer ${process.env.CLOUDTAK_API_KEY}` }
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    filter: {
      groups: ['Surveillance', 'Logistics'],
      bbox: [29.5, 50.0, 31.5, 51.0],
      types: ['a-f-G', 'a-h-G', 'a-u-G']
    }
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'cot') {
    console.log(`Track: ${event.payload.uid} sijainnissa ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Palvelin lähettää ping-viestin 30 sekunnin välein. Asiakkaiden on vastattava pong-viestillä 10 sekunnin kuluessa tai yhteys suljetaan.

Tehtävä-API: luominen, päivittäminen, poistaminen ja määrittäminen

Tehtävät CloudTAK:ssa ovat nimettyjä operatiivisia konteksteja, jotka ryhmittelevät trackejä, datapaketteja ja käyttäjiä. Tehtävä-API mahdollistaa ulkoisten järjestelmien ohjelmallisen tehtävien luomisen.

Tehtävän luominen

curl -s -X POST https://tak.yourdomain.com:8443/api/mission \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPERAATIO CLEARWATER",
    "description": "Tarkistuspisteen valtaus, Vaihe 1",
    "classification": "UNCLASSIFIED",
    "bbox": [30.10, 50.35, 30.25, 50.45],
    "groups": ["Alpha-Company", "ISR-Detachment"]
  }' | jq '{uid: .uid, name: .name}'

Vastaus sisältää tehtävän uid:n (UUID). Päivitä metatiedot: PATCH /api/mission/{uid}. Poista: DELETE /api/mission/{uid}.

Datapaketti-API: MBTiles, KMZ, GeoJSON ja versiointi

# MBTiles-kerroksen lataaminen offline-karttakattavuutta varten
curl -s -X POST \
  https://tak.yourdomain.com:8443/api/mission/${MISSION_UID}/attachment \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/data/aoi-sector-north.mbtiles" \
  -F "name=Pohjoisektori peruskartta" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

Itsenäiset karttakerrokset ladataan POST /api/layer:n kautta. Offline-käyttöönottoa varten: MBTiles ja PMTiles offline-kartoille.

Ryhmät ja kanavat: näkyvyyden suodatus ja track-kulunvalvonta

CloudTAK-ryhmät toteuttavat track-näkyvyyden erottelun. Ryhmätagilla varustettu track on näkyvissä vain kyseisen ryhmän jäseninä oleville yhdistetyille asiakkaille. Tämä mahdollistaa tarvittavan tietämyksen mukaisen erottelun jaetulla TAK-palvelimella.

Ryhmän luominen ja käyttäjien määrittäminen

# Luo ryhmä
curl -s -X POST https://tak.yourdomain.com:8443/api/group \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ISR-Detachment", "description": "Tiedustelu-, Valvonta-, Tunnustelu-solu"}' \
  | jq '.id'

# Lisää käyttäjä ryhmään
curl -s -X POST https://tak.yourdomain.com:8443/api/group/ISR-Detachment/user \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "isr-analyst-01"}'

Asiakas voi kuulua useisiin ryhmiin samanaikaisesti. Trackit ilman ryhmätagia ovat näkyvissä kaikille palvelimen käyttäjille.

TAKpilot integraatioesimerkkinä

TAKpilot on Corvus Intelligencen AI-kopilotti TAK-pohjaisille operaatioille. Se on konkreettinen esimerkki syvästä CloudTAK API -integraatiosta: TAKpilot tilaa WebSocket-trackivirran, käsittelee luonnollisen kielen komentoja operaattoreilta ja suorittaa ne CloudTAK API -kutsuina.

Luonnollisen kielen komento kuten "merkitse ruudukko 38T YQ 45123 67890 viholliskontaktiksi, liitä Alpha-Company-tehtävään" käynnistää seuraavan API-sekvenssin TAKpilotissa:

Muunna MGRS 38T YQ 45123 67890 desimaaliasteiksi (sisäinen muunnos, ei API-kutsua).
POST /api/cot tyypillä a-h-G (vihamielinen maalla) ja muunnetuilla koordinaateilla.
GET /api/mission?name=Alpha-Company tehtävän UID:n selvittämiseksi.
POST /api/mission/{uid}/cot injektoidun CoT-tapahtuman UID:n liittämiseksi tehtävään.
Vastaus operaattorille TAKpilot-chat-rajapinnan kautta vahvistaen toiminnon.

Webhookit: tapahtumien tilaaminen ja edelleenlähetys ulkoisiin järjestelmiin

Webhookit mahdollistavat CloudTAK:n työntää tapahtumia ulkoisiin järjestelmiin sen sijaan että vaatisi niitä kyselemään REST API:a tai ylläpitämään pysyvää WebSocket-yhteyttä.

Webhookin rekisteröinti

curl -s -X POST https://tak.yourdomain.com:8443/api/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "kafka-bridge",
    "url": "https://integration.yourdomain.com/cloudtak-events",
    "events": ["new_track", "mission_update", "user_join"],
    "secret": "hmac_signing_secret_32chars_min",
    "active": true
  }' | jq '{id: .id, status: .status}'

CloudTAK allekirjoittaa jokaisen webhook-toimituksen HMAC-SHA256-allekirjoituksella X-CloudTAK-Signature-otsikossa. Tarkista allekirjoitus vastaanottopäässä:

// Express.js webhook-vastaanotin allekirjoitustarkistuksella
const crypto = require('crypto');

app.post('/cloudtak-events', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-cloudtak-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Allekirjoitus ei täsmää');
  }

  const event = JSON.parse(req.body);
  // Lähetä Kafkaan, Slackiin, SIEM:iin jne.
  kafkaProducer.send({ topic: 'tak-events', messages: [{ value: req.body }] });
  res.status(200).send('OK');
});

Toimitusvirheet käynnistävät uudelleenyritykset eksponentiaalisella peräytymisellä: 1, 2, 4, 8, 16 sekuntia. Katso toimitushistoria: GET /api/webhook/{id}/deliveries.

Tuetut webhook-tapahtumatyypit

new_track — uusi UID ilmestyy kuvaan ensimmäistä kertaa.
track_stale — trackin vanhentumisaikaleima on ohitettu ilman päivitystä.
mission_update — tehtävä luotiin, muutettiin, arkistoitiin tai poistettiin.
user_join — uusi asiakas yhdistyi ja autentikoitui.
user_leave — asiakas katkesi tai istunto vanhentui.
cot_alert — CoT-tapahtuma, jolla on tyyppiprefiksi b-a (hälytys) vastaanotettiin.

Yhdistä järjestelmäsi TAK-ekosysteemiin

Rakennamme CloudTAK API -integraatioita sensorverkoille, logistiikka-alustoille, AI-päättelypipeline-ratkaisuille ja mukautetuille C2-koontinäytöille — ja tehostamme niitä TAKpilotilla, taktiikkatoimintojen AI-kopilotillamme.

TAKpilot AI-kopilotti → Varaa briefing

Tämän analyysin ovat valmistelleet Corvus Intelligencen insinöörit, jotka rakentavat kriittistä ohjelmistoa puolustus- ja valtiollisille organisaatioille. Lue lisää tiimistämme →

Usein kysytyt kysymykset

Mitä autentikointimenetelmiä CloudTAK REST API tukee?

CloudTAK REST API tukee kahta autentikointimenetelmää: JWT bearer -tokeneita ja staattisia API-avaimia. JWT-tokenit myönnetään POST /api/login -kutsujen kautta ja vanhentuvat konfiguroitavan TTL:n jälkeen (oletus 24 tuntia). API-avaimet ovat pitkäikäisiä tokeneita palvelu-palvelu-integraatioihin.

Mikä on oikea Content-Type CoT-injektioon REST API:n kautta?

CloudTAK CoT-injektiopäätepiste (POST /api/cot) hyväksyy kaksi sisältötyyppiä: application/xml raa'oille CoT XML -hyötykuormille ja application/json JSON-käärille, jonka CloudTAK muuntaa sisäisesti CoT XML:ksi. Sisällytä aina Content-Type-otsikko eksplisiittisesti.

Miten suodatan WebSocket-trackivirran tiettyyn ryhmään tai aluerajaukseen?

CloudTAK WebSocket-päätepiste (/api/ws) hyväksyy tilauksen suodatusobjektin yhteydenmuodostushetkellä. Suodatin tukee kolmea kenttää: groups (ryhmänimijoukko), bbox (GeoJSON-rajoituslaatikko [minLon, minLat, maxLon, maxLat]) ja types (CoT-tyyppimerkkijoukkotaulukko). Voit päivittää suodattimia aktiivisella yhteydellä.

Mikä on nopeusrajoitus CoT-injektiopäätepisteellä?

CloudTAK:n oletusnopeusrajoitus on 100 CoT-tapahtumaa sekunnissa per API-avain. Konfiguroitavissa CLOUDTAK_COT_RATE_LIMIT-ympäristömuuttujan kautta. Jos integraatio ylittää rajoituksen, API palauttaa HTTP 429 Too Many Requests Retry-After-otsikon kanssa.

Miten luon tehtävän ja liitän siihen datapaketteja API:n kautta?

Tehtävän luominen on kaksivaiheinen prosessi: ensin POST /api/mission -kutsu nimellä, kuvauksella ja valinnaisella ryhmämäärittelyllä tehtävän UID:n saamiseksi. Sitten POST /api/mission/{uid}/attachment -kutsu multipart/form-data-rungolla, joka sisältää datapakettitiedoston (MBTiles, KMZ tai GeoJSON).

Voinko ladata MBTiles-karttakerroksia CloudTAK API:n kautta?

Kyllä. POST /api/layer -kutsu multipart/form-data-rungolla, joka sisältää MBTiles-tiedoston ja metatiedot (name, minZoom, maxZoom, bounds). CloudTAK validoi MBTiles-muodon ja tekee kerroksen kaikkien yhdistetyjen asiakkaiden käyttöön. PMTiles on myös tuettu saman päätepisteen kautta.

Miten webhookit toimivat CloudTAK:ssa?

CloudTAK webhookit rekisteröidään POST /api/webhook -kutsulla kohde-URL:lla, tapahtumatyypeillä ja valinnaisella HMAC-salaisuudella. Toimitusvirheissä CloudTAK yrittää uudelleen eksponentiaalisella peräytymisellä enintään 5 kertaa.

Miten TAKpilot käyttää CloudTAK API:a luonnollisen kielen komentojen suorittamiseen?

TAKpilot vastaanottaa luonnollisen kielen komentoja operaattoreilta ja hajoittaa ne CloudTAK API -kutsuiksi. Komento sijainnin merkitsemiseksi muuttuu POST /api/cot -kutsuksi sopivalla CoT-tyypillä. TAKpilot ylläpitää istuntokontekstia ja kuluttaa myös WebSocket-virtaa reaktiivisesti.

Mitä tapahtumatyyppejä voin tilata CloudTAK WebSocketin kautta?

CloudTAK WebSocket-virta lähettää viisi tapahtumatyyppiä: cot (CoT XML -tapahtuma), track_update (olemassa olevan trackin sijaintimuutos), mission_update (tehtävä luotiin, muutettiin tai poistettiin), user_event (asiakas yhdistyi, katkesi tai vaihtoi kutsumerkkiä) ja system_event (palvelinpuolen tapahtumat). Tilaa valikoivasti types-suodatinkentän avulla.

Miten versioin tehtäviin liitettyjä datapaketteja?

CloudTAK ylläpitää versiohistoriaa jokaiselle datapakettiliitteelle. Jokainen lataus /api/mission/{uid}/attachment -osoitteeseen luo uuden version. Nykyinen (uusin) versio tarjotaan oletuksena. Tietyn version hakemiseksi lisää version-kyselyparametri: GET /api/mission/{uid}/attachment/{attachmentId}?version=2.