Bu sayfa, lisanslı yönlendiricileri, ağ geçitlerini ve denetleyicileri kendi araçlarından, örneğin bir kurulum uygulamasından veya devreye alma betiğinden bir kuruluşa ekleyen entegratörler içindir. Uygulamadaki adımlar Cihaz ekleme ve sahiplenme sayfasında; sahiplenmenin nasıl korunduğu ise Cihaz kimliği ve sahiplenme güvenliği sayfasındadır.
Yollar https://<your host>/tenant/<tenantId> altındadır. Kurallar REST API temelleri sayfasındadır.
Çağrıdan önce
Lisanslı bir cihaz yalnızca biri başındayken sahiplenilebilir:
- Cihaz, bulut bağlantısı açık olarak internete bağlıdır.
- Biri, cihazın kendi Cloud sayfasındaki sahiplenme penceresini açar. Pencere en fazla 15 dakika açık kalır ve bir başarılı sahiplenmeden sonra kapanır.
- Programınız, pencere açıkken cihazın seri numarasını ve sahiplenme kodunu gönderir.
Sahiplenme penceresini açacak bir yol yoktur: pencere yalnızca cihazda açılır.
Yollar
| Yöntem | Yol | İzin | İşlevi |
|---|---|---|---|
| POST | /api/iot/claim | iot_provisioning.claim | Bir cihazı sahiplenir veya kuru çalıştırmayla kontrol eder |
| GET | /api/iot/devices/{deviceId}/ownership | iot_provisioning.claim | Cihazın kaynağını, sertifikasını ve sürüm bırakma ayarını gösterir |
| PATCH | /api/iot/devices/{deviceId}/ownership | iot_provisioning.release | Cihazın kendi sayfasından bırakmaya izin verir veya bırakmayı durdurur |
| POST | /api/iot/claim/release/{deviceId} | iot_provisioning.release | Bir cihazı fabrika havuzuna geri bırakır |
Dördü de varsayılan olarak Yönetici izinleridir. Sahiplenilen cihazı aynı çağrıda bir saha veya varlığa yerleştirmek için anahtarda ayrıca iot_asset.relations.manage gerekir.
Bir cihazı sahiplenme
POST /api/iot/claim
| Alan | Kural |
|---|---|
serial | Zorunlu. 6 ile 32 harf, rakam ve tire; büyük-küçük harf farkı yoktur |
secret | Zorunlu. Cihazın Cloud sayfasındaki 20 karakterlik sahiplenme kodu. Tireler, boşluklar ve büyük-küçük harf yok sayılır; O 0 olarak, I ve L ise 1 olarak okunur |
name | İsteğe bağlı, 1 ile 128 karakter. Varsayılan: seri numarası |
iotAssetId | İsteğe bağlı. Cihazın yerleştirileceği saha veya varlık |
dryRun | İsteğe bağlı. true her şeyi kontrol eder, hiçbir şeyi sahiplenmez |
Gövde katıdır: bilinmeyen bir alan 400 döndürür. Sahiplenme kodu geri gönderilmez.
curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
-H 'Authorization: Bearer sk_live_…' \
-H 'Content-Type: application/json' \
-d '{"serial":"RT420-2610-000123","secret":"7KQ2-M9XH-D4TB-6WRA-1NZC","name":"Pump house router","iotAssetId":"8d0e…"}'
{
"status": "claimed",
"serial": "RT420-2610-000123",
"deviceId": "6f1c…",
"model": "…",
"profileId": "a1b2…",
"name": "Pump house router",
"renamed": false,
"placement": "placed"
}
Yanıtlar
| Durum | status | Anlamı |
|---|---|---|
| 201 | claimed | Cihaz artık sizin |
| 200 | claimed ve alreadyOwned: true | Kuruluşunuz cihaza zaten sahip; hiçbir şey değişmedi |
| 200 | claimable | Kuru çalıştırma geçti; yanıtta serial, model, type ve hw bulunur |
| 200 | in_progress | Bu cihazın bir sahiplenmesi şu anda çalışıyor; birazdan cihaz listesini okuyun |
Sahiplenmenin diğer alanları:
| Alan | Anlamı |
|---|---|
name, renamed | Cihazın adı. Aynı adda bir cihaz varsa sonuna bir numara eklenir (Pump house router (2)) ve renamed değeri true olur |
recreated | Kuruluşunuz cihaza sahipti ama cihaz kaydı silinmişse true olur; kayıt yeniden oluşturulmuştur |
placement | Yalnızca iotAssetId gönderdiyseniz: placed, not_permitted (anahtarda iot_asset.relations.manage yok), unavailable (sahalar ve varlıklar kapalı) veya failed. Her durumda sahiplenme geçerlidir |
Sahiplenilen cihaz, model cihaz profilinin bir kopyasını ve fabrika sertifikasını X.509 kimlik bilgisi olarak alır; saniyeler içinde kuruluşunuza yeniden bağlanır. Bir iot.device.claimed webhook olayı gönderilir (bkz. Webhook olay başvurusu).
Reddedilmeler
Her red, details.reason içinde beş koddan birini taşır. Mesaja değil, bu koda göre dallanın.
details.reason | Durum | code | Mesaj | Yapılacak |
|---|---|---|---|---|
not_claimable | 409 | CONFLICT | Bu cihaz eklenemez. Seri numarasını kontrol edin; doğruysa cihaz başka bir hesaba aittir: satıcıdan cihazı bırakmasını isteyin. | Seri numarasını kontrol edin. Bilinmeyen bir seri numarası, emekli edilmiş bir cihaz ve başka bir kuruluşun cihazı bu yanıtı verir; sahip hiçbir zaman adıyla belirtilmez |
press_claim_button | 409 | CONFLICT | Cihazın Cloud sayfasında sahiplenme penceresini açın (15 dakika açık kalır), sonra yeniden deneyin. | Cihazda pencereyi açıp yeniden deneyin |
bad_secret | 400 | VALIDATION_ERROR | Seri numarası veya sahiplenme kodu doğru değil. | Kodu Cloud sayfasından yeniden okuyun |
rate_limited | 429 | RATE_LIMIT_EXCEEDED | Çok fazla deneme. Daha sonra tekrar deneyin. | Bekleyin; aşağıdaki deneme sınırlarına bakın |
device_limit | 403 | FEATURE_NOT_AVAILABLE | Bu hesabın cihaz sınırına ulaşıldı. | Bir cihazı kaldırın veya planı değiştirin |
Sahiplenme penceresi kapalıyken sahiplenme kodu hiç kontrol edilmez; bu yüzden kapalı bir pencere, bir kodun doğru olup olmadığını asla söylemez. Cihaz sınırı en son, hiçbir şey oluşturulmadan önce kontrol edilir.
Deneme sınırları
Başarısız denemeler (bilinmeyen bir seri numarası, kapalı bir sahiplenme penceresi, yanlış bir kod) kayan bir saatlik süre içinde sayılır. Bunlardan biri dolduğunda, kapsadığı denemeler rate_limited yanıtı verir:
| Sayım ölçütü | Saatlik sınır |
|---|---|
| Seri numarası | 5 yanlış sahiplenme kodu |
| Üye | 20 başarısız deneme (bir anahtar için: anahtarın sahibi) |
| Çağıran adres | 30 başarısız deneme |
Kuru çalıştırma aynı kontrolleri yapar ve başarısız bir kuru çalıştırma, başarısız bir sahiplenme gibi sayılır. Kodları döngüyle denemeyin: beş yanlış kod seri numarasını bir saat kilitler.
Sahiplik
GET /api/iot/devices/{deviceId}/ownership yanıtı { ownership, capabilities } biçimindedir. Sahiplenilmiş bir cihaz için ownership içinde fromPool: true, serial, model, claimedAt, claimedByUserId, certificate (status, notAfter), allowDeviceRelease ve blockers (cihaza hâlâ referans veren öğeler) bulunur. Kuruluşunuzda oluşturulmuş bir cihaz fromPool: false yanıtı verir. Sahiplenenin adı (claimedBy) anahtarların hiç sahip olmadığı bir üye izni gerektirir, bu yüzden anahtar yalnızca kimliği alır.
PATCH ile { "allowDeviceRelease": false } göndermek, cihazın kendi Cloud sayfasındaki düğmeyle kimsenin cihazı bırakmasını engeller. Varsayılan değer true‘dur.
Bir cihazı bırakma
POST /api/iot/claim/release/{deviceId} ile { "confirmSerial": "RT420-2610-000123", "reason": "Returned to supplier" } (reason en fazla 500 karakter) cihazı fabrika havuzuna geri gönderir. Yanıt 200 { serial, unitStatus, certificateKept } biçimindedir. Verileri kuruluşunuzda kalır; bir sonraki sahibin sahiplenmek için cihazın başında olması gerekir. Bir iot.device.released webhook olayı gönderilir.
| Durum | details.reason | Anlamı |
|---|---|---|
| 400 | confirm_mismatch | “Onaylamak için cihaz seri numarasını tam olarak yazın.” |
| 404 | not_from_pool | “Bu cihaz fabrika havuzundan eklenmedi.” |
| 409 | still_referenced | Cihaza hâlâ bir şey referans veriyor, örneğin yerleştirildiği bir saha veya varlık; details.moduleId ve details.count neyin olduğunu belirtir. Önce bunu kaldırın |

