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 barındırılan bir web kancasında özel ayırma ilkesi uygularsınız. Daha sonra web kancasını bir veya daha fazla 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, cihazı kaydetmek için IoT hub'ını döndüren web kancasını çağırır ve isteğe bağlı olarak cihazın ilk ikizi ayarları ve doğrudan cihaza döndürülecek tüm bilgiler.

Genel Bakış

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

1. Özel ayırma geliştiricisi, hedeflenen ayırma ilkesini uygulayan ve Azure İşlevleri http tetikleyici işlevi olarak dağıtan bir web kancası geliştirir. 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 işleci, özel ayırma için bir veya daha fazla bireysel kayıt ve/veya kayıt grubu yapılandırıp Azure İşlevleri özel ayırma web kancası için çağrı ayrıntıları 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 istek gövdesi bir AllocationRequest istek nesnesi olarak ayarlanmış bir POST isteğini web kancasına 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 DPS'den kayıt yanıtında kimlik doğrulama ayrıntılarıyla birlikte cihaza geçirilir.

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 uçtan uca eksiksiz bir örneği için bkz . Özel ayırma ilkelerini kullanma.

Özel ayırma ilkesi isteği

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ı	Tanım
individualEnrollment	Ayırma isteğinin kaynaklandığı bireysel kayıtla ilişkili özellikleri içeren tek bir kayıt kaydı. Cihaz tek bir kayıt aracılığıyla kaydediliyorsa sunar.
enrollmentGroup	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 kaydediyorsa sunar.
deviceRuntimeContext	Kayıt olan cihazla ilişkili özellikleri içeren bir nesne. Her zaman var.
linkedHubs	Ayırma isteğinin kaynaklandığı kayıt girdisine 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:

Özellik	Tür	Tanım
registrationId	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.
currentDeviceId	Dize	Cihazın önceki atamasından cihaz kimliği (varsa). Bu bir ilk atamaysa mevcut değildir.
x509	X509DeviceAttestation	X.509 kanıtlama için sertifika ayrıntılarını içerir.
symmetricKey	SymmetricKeyAttestation	Simetrik anahtar kanıtlama için birincil ve ikincil anahtar ayrıntılarını içerir.
tpm	TpmAttestation	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 ayırma ilkesi yanıtı

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

Özellik	Tanım
initialTwin	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ı.
iotHubHostName	Gerekli. Cihazı atanacak 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, yukarıdaki örnek 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 yüklerini kullanma

Cihazlar, DPS tarafından özel ayırma web kancanıza geçirilen özel bir yük gönderebilir ve bu yükü mantığında kullanabilir. Web kancası bu verileri çeşitli yollarla 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 bu yükü özel ayırma web kancasına geçirir ve bu da cihaz modeli bilgilerine göre cihazın hangi IoT hub'ına sağlanacağına karar verir. 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

Cihaz, DPS'ye kaydolmak için yazmaç 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 istek gövdesi aşağıdaki gibi görünür:

{ 
    "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 web kancasına veri yükü 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 gibi görünecektir:

{ 
    "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.

Özel ayırma web kancası DPS'ye veri döndürür

Özel ayırma ilkesi web kancası, web kancası yanıtında AllocationResponse.payload özelliğini kullanarak bir cihaz için hedeflenen verileri JSON nesnesindeki DPS'ye döndürebilir.

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 (yeniden sağlama) aracılığıyla kaydedilmiş bir cihaz için ç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. Diğer ayrıntılar için bkz . Yeniden sağlama.

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 girdisinde hiçbir IoT hub'ı seçilmezse, DPS örneğine bağlı tüm IoT hub'larını içerir. Son olarak, cihaz yeniden sağlanıyorsa ve kayıt girdisinde Hiçbir zaman yeniden sağlama ilkesi ayarlandıysa, yalnızca cihazın şu anda atanmış olduğu IoT hub'ını içerir.

• İlk atamada , initialTwin özelliği web kancası tarafından döndürülürse, DPS atanan IoT hub'ına cihazın ilk ikizini buna göre 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 sağlama sırasında DPS, kayıt girişinde ayarlanan yeniden sağlama ilkesini izler. DPS yanıtta yalnızca geçerli IoT hub'ı değiştirilirse ve kayıt girdisinde ayarlanan yeniden sağlama ilkesi Yeniden sağlama ve ilk yapılandırmaya sıfırlama ise initialTwin özelliğini kullanır. Bu durumda DPS, yeni IoT hub'ında cihazın ilk ikizini önceki madde işaretindeki ilk atama sırasında olduğu gibi ayarlar. Diğer tüm durumlarda, DPS initialTwin özelliğini yoksayar.

• Yanıtta payload özelliği ayarlanırsa, isteğin ilk atama veya yeniden sağlama için olup olmadığına bakılmaksızın 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 ayarlanacak currentIotHubHostName özelliğini içerir.

• İstekteki AllocationRequest.individualEnrollment veya AllocationRequest.enrollmentGroup özelliğinin reprovisionPolicy özelliğini inceleyerek kayıt girdisinde şu anda yeniden sağlama ilkelerinden hangisinin 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'de 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 Azure DPS SDK'ları.

Sonraki adımlar

• Özel ayırma ilkesi kullanan uçtan uca örnek için bkz . Özel ayırma ilkelerini kullanma

• Azure İşlevleri hakkında daha fazla bilgi edinmek için Azure İşlevleri belgelerine bakın