Azure IoT Hub Cihaz Sağlama Hizmeti ile özel ayırma ilkelerini anlama

Özel ayırma ilkeleri, cihazların IoT hub'larınıza nasıl atandığı üzerinde daha fazla denetim sağlar. Özel ayırma ilkelerini kullanarak, Cihaz Sağlama Hizmeti (DPS) tarafından sağlanan yerleşik ilkeler senaryonuzun gereksinimlerini karşılamadığında kendi ayırma ilkelerinizi tanımlayabilirsiniz.

Örneğin, sağlama sırasında bir cihazın kullandığı sertifikayı incelemek ve cihazı bir sertifika özelliğine göre bir IoT hub'ına atamak isteyebilirsiniz. Alternatif olarak, cihazlarınız için bir veritabanında depolanan bilgileriniz olabilir ve bir cihazın atanması gereken IoT hub'ını veya cihazın ilk ikizinin nasıl ayarlanması gerektiğini belirlemek için veritabanını sorgulamanız gerekebilir.

Azure İşlevleri'nde barındırılan bir web kancasında özel bir ayırma ilkesi uygularsınız. Daha sonra web kancasını bir veya daha fazla bireysel kayıt ve kayıt grubunda yapılandırabilirsiniz. Bir cihaz yapılandırılmış bir kayıt girdisi aracılığıyla kaydolduğunda, DPS web kancasını çağırır. Bu işlem, cihazı kaydetmek için hangi IoT hub'ının kullanılacağını belirtir ve isteğe bağlı olarak cihaza doğrudan döndürülecek cihazın ilk ikiz ayarlarını ve bilgileri içerir.

Genel bakış

Aşağıdaki adımlar, özel ayırma ilkelerinin nasıl çalıştığını açıklar:

  1. Özelleştirilmiş ayırma politikası geliştiricisi, hedeflenen ayırma politikasını uygulayan bir web kancası geliştirir ve bunu Azure İşlevleri'nde bir HTTP Tetikleyici işlevi olarak dağıtır. Web kancası, DPS kayıt girişi ve cihaz hakkında bilgi alır ve cihazın kaydedilmesi gereken IoT hub'ını ve isteğe bağlı olarak cihazın ilk durumuyla ilgili bilgileri döndürür.

  2. IoT operatörü, özel tahsis için bir veya birden fazla bireysel kayıt ve/veya kayıt grubu yapılandırır ve Azure İşlevleri'nde özel tahsis web kancası için çağrı ayrıntılarını sağlar.

  3. Bir cihaz özel ayırma web kancası için yapılandırılmış bir kayıt girişi aracılığıyla kaydolduğunda, DPS web kancasına, istek gövdesi bir AllocationRequest istek nesnesi olarak ayarlanmış bir POST isteği gönderir. AllocationRequest nesnesi, sağlamaya çalışan cihaz ve sağladığı bireysel kayıt veya kayıt grubu hakkında bilgi içerir. Cihaz bilgileri, kayıt isteğine cihazdan gönderilen isteğe bağlı bir özel yük içerebilir. Daha fazla bilgi için bkz . Özel ayırma ilkesi isteği.

  4. Azure İşlevi başarılı olduğunda bir AllocationResponse nesnesi yürütür ve döndürür. AllocationResponse nesnesi, cihazın sağlanması gereken IoT hub'ını, ilk ikiz durumunu ve cihaza geri dönmek için isteğe bağlı bir özel yükü içerir. Daha fazla bilgi için bkz. Özel ayırma ilkesi yanıtı.

  5. DPS, cihazı yanıtta belirtilen IoT hub'ına atar ve bir ilk ikiz döndürülürse cihazın ilk ikizini buna göre ayarlar. Web kancası tarafından özel bir yük döndürülürse, atanan IoT hub'ı ve kimlik doğrulama ayrıntılarıyla birlikte DPS'den alınan kayıt yanıtında cihaza iletilir.

  6. Cihaz, atanan IoT hub'ına bağlanır ve ilk ikiz durumunu indirir. Kayıt yanıtında özel bir yük döndürülürse, cihaz bunu kendi istemci tarafı mantığına göre kullanır.

Aşağıdaki bölümlerde özel ayırma isteği ve yanıtı, özel yükleri ve ilke uygulaması hakkında daha fazla ayrıntı sağlanır. Özel ayırma ilkesinin tam uçtan uca örneği hakkında daha fazla bilgi için bkz . Öğretici: Cihaz Sağlama Hizmeti (DPS) ile özel ayırma ilkelerini kullanma.

İşlev anahtarlarını yönetme

Özel ayırma ilkeleri, yetkilendirme düzeyinin olarak ayarlandığı Azure İşlevleri çağrılarının kimliğini doğrulamak için Functionişlev anahtarlarını kullanır. Anahtar yönetiminin davranışı, özel ayırma ilkesini Azure portalı üzerinden mi yoksa program aracılığıyla mı yapılandırdığınıza göre farklılık gösterir.

Portaldaki işlev anahtarları

Azure portalında bir kayıt oluşturduğunuzda ve özel bir ayırma ilkesi belirttiğinizde, portal işlev anahtarını alma ve ekleme işlemlerini otomatik olarak işler.

Özel ayırma ilkesi için işlevi seçtikten sonra portal işlev anahtarını alır. Bu adım portal arabirimi üzerinden kullanıcılara görünmez. Ardından işlev anahtarı, DPS tarafından işlevi çağırmak için kullanılan şifrelenmiş web kancası URL'sinin bir parçası olarak depolanır. Anahtar portalda görüntülenmez.

Kayıt ayrıntılarını almak için get komutunu çalıştırarak anahtarın web kancası URL'sine eklendiğini doğrulayabilirsiniz. Kayıt yapılandırmasında işlev anahtarı webhookUrl alanına eklenir.

API'leri olan işlev tuşları

DPS API'sini kullanarak program aracılığıyla bir kayıt oluşturduğunuzda, kaydı oluştururken anahtarı el ile sağlamanız gerekir. Anahtar sağlanmazsa, Azure İşlevleri çağrısı kimlik doğrulaması başarısız olur.

Bireysel kaydı veya grup kaydını oluşturmadan önce işlevinizden işlev anahtarını alın. Daha fazla bilgi için bkz . İşlev erişim anahtarlarınızı alma. Ardından, CustomAllocationDefinition'ın web kancasıUrl alanına işlev anahtarını ekleyin.

Daha fazla bilgi için bkz . Erişim anahtarı yetkilendirmesi.

Özel tahsis politika talebi

DPS, aşağıdaki uç noktada web kancanıza bir POST isteği gönderir: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

İstek gövdesi bir AllocationRequest nesnesidir:

Özellik adı Açıklama
bireysel kayıt Ayırma isteğinin kaynaklandığı bireysel kayıtla ilişkili özellikleri içeren tek bir kayıt kaydı. Cihaz bireysel kayıt aracılığıyla kaydediliyorsa mevcut.
kayıt grubu Ayırma isteğinin kaynaklandığı kayıt grubuyla ilişkili özellikleri içeren bir kayıt grubu kaydı. Cihaz bir kayıt grubu aracılığıyla kaydediliyorsa mevcuttur.
deviceRuntimeContext Kayıt olan cihazla ilişkili özellikleri içeren bir nesne. Her zaman var.
bağlantılı Hub'lar Kayıt girdisinden kaynaklanan tahsis isteğine bağlı IoT hub'larının konak adlarını içeren bir dizi. Cihaz bu IoT hub'larından herhangi birine atanabilir. Her zaman var.

DeviceRuntimeContext nesnesi aşağıdaki özelliklere sahiptir:

Mülk Türü Açıklama
KayıtKimliği Dize Cihaz tarafından çalışma zamanında sağlanan kayıt kimliği. Her zaman var.
currentIotHubHostName Dize Cihazın daha önce atandığı IoT hub'ının ana bilgisayar adı (varsa). Bu bir ilk atamaysa mevcut değildir. Bunun cihaz için ilk atama olup olmadığını veya cihazın daha önce atanıp atanmadığını belirlemek için bu özelliği kullanabilirsiniz.
mevcutCihazId Dize Cihazın önceki atamasından cihaz kimliği (varsa). Bu bir ilk atamaysa mevcut değildir.
x509 X509 Cihaz Doğrulaması X.509 doğrulama için sertifika ayrıntılarını içerir.
simetrik anahtar Simetrik Anahtar Doğrulaması Simetrik anahtar kanıtlama için birincil ve ikincil anahtar ayrıntılarını içerir.
Tpm Tpm Doğrulama TPM kanıtlaması için onay anahtarı ve depolama kök anahtarı ayrıntılarını içerir.
yük nesne Kayıt sırasında yük özelliğinde cihaz tarafından belirtilen özellikleri içerir. Cihaz DPS kayıt isteğinde özel bir yük gönderiyorsa sunar.

Aşağıdaki JSON, simetrik anahtar tabanlı kayıt grubu aracılığıyla kaydolan bir cihaz için DPS tarafından gönderilen AllocationRequest nesnesini gösterir.

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

Bu cihaz için ilk kayıt olduğundan deviceRuntimeContext özelliği yalnızca kayıt kimliğini ve cihazın kimlik doğrulama ayrıntılarını içerir. Aşağıdaki JSON, aynı cihazı kaydetmek için sonraki bir çağrı için deviceRuntimeContext değerini gösterir. Geçerli IoT hub ana bilgisayar adının ve cihaz kimliğinin isteğe dahil olduğuna dikkat edin.

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

Özel tahsis politikası yanıtı

Başarılı bir istek bir AllocationResponse nesnesi döndürür.

Mülk Açıklama
ilkİkiz isteğe bağlı. Atanan IoT hub'ında ilk ikizde ayarlanacağı istenen özellikleri ve etiketleri içeren nesne. DPS, atanan IoT hub'ına ilk ikizi ilk atamada veya kayıt girdisinin geçiş ilkesi Yeniden sağlama ve ilk yapılandırmaya sıfırlama olarak ayarlanmışsa yeniden sağlama sırasında ilk ikizi ayarlamak için initialTwin özelliğini kullanır. Her iki durumda da initialTwin döndürülmezse veya null olarak ayarlanırsa DPS, atanan IoT hub'ında ikizini kayıt girdisindeki ilk ikiz ayarlarına ayarlar. DPS, kayıt girdisindeki diğer tüm yeniden sağlama ayarları için initialTwin'i yoksayar. Daha fazla bilgi edinmek için bkz . Uygulama ayrıntıları.
iotHubAna Bilgisayar Adı Gerekli. Cihazın atanacağı IoT hub'ının ana bilgisayar adı. Bu, istekteki linkedHubs özelliğine geçirilen IoT hub'larından biri olmalıdır.
yük isteğe bağlı. Kayıt yanıtında cihaza geri geçirilecek verileri içeren bir nesne. Tam veriler, cihaz ve özel ayırma işlevi arasında geliştirici tarafından tanımlanan örtük sözleşmeye bağlıdır.

Aşağıdaki JSON, önceki örnekteki kayıt için DPS'ye özel ayırma işlevi tarafından döndürülen AllocationResponse nesnesini gösterir.

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

Özel ayırmada cihaz veri yüklerini kullanma

Cihazlar, DPS tarafından özel ayırma web kancanıza iletilen özel bir yük gönderebilir. Bu web kancası, bu verileri kendi mantığında kullanabilir. Web kancası bu verileri birçok şekilde kullanabilir; belki de cihazı hangi IoT hub'ına atayacağını belirlemek veya ilk ikizde özellikleri ayarlamak için kullanılabilecek bir dış veritabanında bilgi aramak için. Buna karşılık, web kancanız DPS aracılığıyla verileri cihaza geri döndürebilir ve bu da cihazın istemci tarafı mantığında kullanılabilir.

Örneğin, cihazları cihaz modeline göre ayırmak isteyebilirsiniz. Bu durumda, cihazı, DPS'ye kaydolduğunda istek yükünde model bilgilerini bildirecek şekilde yapılandırabilirsiniz. DPS, cihaz modeli bilgilerine göre cihazın hangi IoT hub'a atandığını belirleyen özel tahsis web kancasına bu yükü geçirir. Gerekirse, web kancası verileri web kancası yanıtında JSON nesnesi olarak DPS'ye geri döndürebilir ve DPS bu verileri kayıt yanıtında cihazınıza döndürür.

Cihaz DPS'ye veri yükü gönderiyor

Bir cihaz , DPS'ye kaydolmak için DPS kayıt API'sini çağırır. İstek, isteğe bağlı yük özelliğiyle geliştirilebilir. Bu özellik geçerli herhangi bir JSON nesnesi içerebilir. Tam içerik, çözümünüzün gereksinimlerine bağlıdır.

TPM ile kanıtlama için talep gövdesi aşağıdaki örneğe benzer:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

DPS özel ayırma webhook aracılığıyla veri paketi gönderir

Cihaz kayıt isteğinde bir yük içeriyorsa, DPS özel ayırma web kancasını çağırdığında yükü AllocationRequest.deviceRuntimeContext.payload özelliğinde geçirir.

Önceki bölümdeki TPM kayıt isteği için cihaz çalışma zamanı bağlamı aşağıdaki örneğe benzer:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

Cihaz için ilk kayıt bu değilse, çalışma zamanı bağlamı currentIoTHubHostname ve currentDeviceId özelliklerini de içerir.

Özelleştirilmiş ayırma web kancası DPS'ye veri döndürür

Özel ayırma politikası web kancası, AllocationResponse.payload özelliğini kullanarak bir cihaz için hedeflenen verileri JSON nesnesi olarak DPS'ye gönderebilir.

Aşağıdaki JSON, yük içeren bir web kancası yanıtını gösterir:

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

DPS cihaza veri yükü gönderir

DPS, web kancası yanıtında bir yük alırsa, bu verileri başarılı bir kayıttaki yanıttaki RegistrationOperationStatus.registrationState.payload özelliğindeki cihaza geri geçirir. registrationState özelliği DeviceRegistrationResult türündedir.

Aşağıdaki JSON, yük özelliğini içeren bir TPM cihazı için başarılı bir kayıt yanıtı gösterir:

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

Uygulama ayrıntıları

Özel ayırma web kancası, daha önce DPS aracılığıyla kaydedilmemiş bir cihaz (ilk atama) veya daha önce DPS aracılığıyla kaydedilmiş bir cihaz için (yeniden tahsis) çağrılabilir. DPS aşağıdaki yeniden sağlama ilkelerini destekler: Verileri yeniden sağlama ve geçirme, Yeniden sağlama ve ilk yapılandırmaya sıfırlama ve Hiçbir zaman yeniden sağlama. Bu ilkeler, önceden sağlanan bir cihaz yeni bir IoT hub'ına atandığında uygulanır. Daha fazla bilgi için bkz. IoT Hub'daki cihazın yeniden sağlanması kavramları.

Aşağıdaki noktalar, özel ayırma web kancanızın gözlemlemesi gereken gereksinimleri ve web kancanızı tasarlarken bilmeniz gereken davranışı açıklar:

  • Cihaz, AllocationRequest.linkedHubs özelliğindeki IoT hub'larından birine atanmalıdır. Bu özellik, cihazın atanabileceği konak adına göre IoT hub'larının listesini içerir. Bu genellikle kayıt girişi için seçilen IoT hub'larından oluşur. Kayıt girişinde hiçbir IoT hub'ı seçilmediyse, DPS örneğine bağlı tüm IoT hub'larını içerir. Son olarak, cihaz yeniden yapılandırılıyorsa ve kayıt girdisinde Hiçbir zaman yeniden sağlama ilkesi ayarlandıysa, yalnızca şu anda atanmış olduğu IoT hub’ı içerir.

  • İlk atamada, initialTwin özelliği web kancası tarafından döndürülürse DPS, cihazın IoT hub üzerinde ilk ikizini uygun şekilde ayarlar. initialTwin özelliği atlanırsa veya null ise, DPS cihazın ilk ikizini kayıt girişinde belirtilen ilk ikiz ayarına ayarlar.

  • Yeniden yapılandırma sırasında, DPS, kayıt girdisinde belirlenen yeniden yapılandırma politikasını izler. DPS, yalnızca mevcut IoT hub'ı değiştiyse ve kayıt girişinde yeniden sağlama ilkesi Yeniden Sağlama ve Başlangıç Yapılandırmasına Sıfırlama olarak ayarlanmışsa, yanıt içinde initialTwin özelliğini kullanır. Bu durumda, DPS, yeni IoT hub'ında cihazın ilk ikizini, önceki madde işaretinde olduğu gibi başlangıç atanması sırasında ayarlar. Diğer tüm durumlarda, DPS initialTwin özelliğini yoksayar.

  • Yanıtta payload özelliği ayarlanırsa, isteğin ilk atama veya yeniden atanma için yapılıp yapılmadığı fark etmeksizin DPS bunu her zaman cihaza döndürür.

  • Bir cihaz daha önce bir IoT hub'ına sağlanmışsa AllocationRequest.deviceRuntimeContext , cihazın şu anda atanmış olduğu IoT hub'ının ana bilgisayar adına ayarlanmış currentIotHubHostName özelliğini içerir.

  • İsteğin AllocationRequest.individualEnrollment veya AllocationRequest.enrollmentGroup özelliğinin reprovisionPolicy özelliğini inceleyerek, kayıt girdisinde şu anda hangi yeniden sağlama ilkesinin ayarlandığını belirleyebilirsiniz. Aşağıdaki JSON, Verileri yeniden sağlama ve geçirme ilkesinin ayarlarını gösterir:

           "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }

SDK desteği

DPS cihaz SDK'ları, cihazları DPS'ye kaydetmenize yardımcı olmak için C, C#, Java ve Node.js API'ler sağlar. Hem IoT Hub SDK'ları hem de DPS SDK'ları, özel ayırma web kancaları geliştirirken yararlı olabilecek cihaz ve hizmet yapıtlarını (cihaz ikizleri ve kayıt girişleri gibi) temsil eden sınıflar sağlar. IoT Hub ve IoT Hub Cihazı Sağlama Hizmeti için kullanılabilen Azure IoT SDK'ları hakkında daha fazla bilgi edinmek için bkz. Azure IoT Hub SDK'ları ve IoT Hub Cihazı Sağlama Hizmeti için Microsoft SDK'ları.

Sonraki adımlar

  • Last updated on