Cihaz HTTP API’si

Bir cihaz MQTT bağlantısını sürdüremediğinde HTTPS kullanın: uyanıp veri gönderen ve tekrar uykuya geçen pil ile çalışan cihazlar veya MQTT’yi engelleyen ağlar. HTTP mesajları, MQTT mesajlarıyla birebir aynı şekilde işlenir: aynı payload biçimleri, aynı anahtar kuralları, aynı hız sınırları, aynı aylık mesaj sayısı. Bu sayfa, bir cihazın çağırabileceği tüm endpoint’leri listeler.

Temel bilgiler

Token, URL’de token seçeneğini açan profiller dışında asla URL’ye konmaz (aşağıya bakın). HTTP API’sinde istemci sertifikaları kullanılmaz: X.509 ile oturum açan cihazlar MQTT kullanır. Burada listelenmeyen her yol 404 döndürür.

Endpoint’ler

HTTP üzerinden kullanılamaz: öznitelikleri okuma (GET /api/v1/attributes), paylaşılan öznitelik değişikliklerini bekleme, claim penceresini açma ve firmware isteme. Bu yollar 404 döndürür. Bunlara ihtiyaç duyan cihazlar MQTT kullanır.

Telemetri, MQTT ile aynı payload biçimlerini kullanır. Bkz. MQTT topic’leri ve payload referansı. POST /api/v1/telemetry üzerindeki JSON olmayan bir gövde, tek bir raw anahtarı olarak saklanır (profilin raw boyutuna kadar, varsayılan 4 KB).

Endpoint ayrıntıları

{
    "ts": 1759572000000,
    "values": {
        "temperature": 21.5,
        "humidity": 40
    }
}

curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'

{
    "error": "invalid_payload"
}

{
    "error": "payload_too_large"
}

{
    "error": "rate_limited"
}

{
    "current_fw_title": "boiler-fw",
    "current_fw_version": "26.10.2",
    "lan.ip": "192.168.1.1"
}

curl -X POST 'https://<your-host>/api/v1/attributes' \
  -H 'Content-Type: application/json' \
  -d '{"current_fw_title":"boiler-fw","current_fw_version":"26.10.2","lan.ip":"192.168.1.1"}'

{
    "error": "invalid_payload"
}

{
    "error": "rate_limited"
}

curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000'

{
    "id": 42,
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    }
}

{
    "error": "tls_required"
}

{
    "error": "timeout"
}

{
    "error": "poll_in_progress"
}

{
    "ok": true,
    "result": {
        "sent": 3,
        "received": 3,
        "avg_ms": 18.2
    }
}

curl -X POST 'https://<your-host>/api/v1/rpc/{id}' \
  -H 'Content-Type: application/json' \
  -d '{"ok":true,"result":{"sent":3,"received":3,"avg_ms":18.2}}'

{
    "error": "payload_too_large"
}

{
    "method": "app.request",
    "params": {}
}

curl -X POST 'https://<your-host>/api/v1/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"app.request","params":{}}'

{
    "error": "timeout"
}

{
    "deviceName": "boiler-07",
    "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60",
    "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"
}

curl -X POST 'https://<your-host>/api/v1/provision' \
  -H 'Content-Type: application/json' \
  -d '{"deviceName":"boiler-07","provisionDeviceKey":"pk_8f3b2c1e9d4a7b60","provisionDeviceSecret":"ps_1c9e7f2a4b6d8e03"}'

{
    "status": "SUCCESS",
    "credentialsType": "ACCESS_TOKEN",
    "credentialsValue": "aZ3…"
}

{
    "error": "payload_too_large"
}

Örnekler

Sunucu tarafından zaman damgası eklenen tek bir okuma gönderin:

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Tamponlanmış okumaları kendi zamanlarıyla gönderin (1970’ten bu yana milisaniye, UTC):

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"ts":1759572000000,"values":{"temperature":21.5}},{"ts":1759572060000,"values":{"temperature":21.7}}]'

Bir komutu bekleyin ve yanıtlayın:

curl -s "https://<device host>/api/v1/rpc?timeout=30000" -H "Authorization: Bearer <ACCESS_TOKEN>"
# → {"id": 42, "method": "sys.ping", "params": {...}}
curl -X POST "https://<device host>/api/v1/rpc/42" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" \
  -d '{"ok": true, "result": {"sent": 3, "received": 3}}'

Durum kodları

HTTP cihazları için çevrimiçi durumu

HTTP cihazları bağlantı tutmaz; bu nedenle Canlı bağlantı kullanan bir profil onları asla çevrimiçi göstermez. HTTP cihazlarına Son mesaj (son mesaj, beklenen aralık çarpı katsayıdan daha yeniyse çevrimiçi) veya Yalnızca son görülme seçeneğine sahip bir profil verin. Bkz. Bağlantı durumu ve etkinlik.

Başlık gönderemeyen cihazlar

Bazı cihazlar Authorization header’ı ayarlayamaz. Bu cihazlar için profilin Transport & auth sekmesinde Token in the URL seçeneğini açın. Cihazlar bundan sonra şunları kullanabilir:

POST /api/v1/{token}/telemetry
POST /api/v1/{token}/attributes

Düz HTTP üzerinden komutlar

Hermetry’ye TLS üzerinden ulaşmayan bir long poll, yalnızca profilin Commands allowed without TLS altında listelediği komutları alır. Diğer tüm komutlar bir TLS bağlantısını veya süresinin dolmasını bekler. Liste boşsa düz bir poll isteği 403 tls_required yanıtını verir.

İlgili

• Cihazlara komut gönderme
• Cihaz kimlik bilgileri
• Veri ulaşmıyor