Общие сведения о пользовательских политиках выделения с помощью службы подготовки устройств Центр Интернета вещей Azure

Мақала
03/18/2023

Пользовательские политики выделения обеспечивают больше контроля над назначением устройств центрам Интернета вещей. С помощью пользовательских политик выделения можно определить собственные политики выделения, если встроенные политики, предоставляемые службой подготовки устройств (DPS), не соответствуют требованиям вашего сценария.

Например, вам может понадобиться проверить сертификат, который устройство использует во время подготовки, и назначить устройство в центр Интернета вещей на основе свойства сертификата. Или, возможно, у вас есть сведения, хранящиеся в базе данных для ваших устройств, и необходимо запросить базу данных, чтобы определить, какой центр Интернета вещей следует назначить устройству или как должен быть установлен первоначальный двойник устройства.

Вы реализуете настраиваемую политику выделения в веб-перехватчике, размещенном в Функции Azure. Затем вы можете настроить веб-перехватчик в одной или нескольких отдельных группах регистрации и регистрации. Когда устройство регистрируется с помощью настроенной записи регистрации, DPS вызывает веб-перехватчик, который возвращает Центр Интернета вещей для регистрации устройства и, при необходимости, начальные параметры двойника для устройства и любые сведения, которые будут возвращены непосредственно на устройство.

Обзор

Ниже описано, как работают пользовательские политики выделения.

Разработчик пользовательского выделения разрабатывает веб-перехватчик, который реализует предназначенную политику выделения и развертывает ее в качестве функции триггера HTTP для Функции Azure. Веб-перехватчик принимает сведения о записи регистрации DPS и устройстве и возвращает центр Интернета вещей, в который устройство должно быть зарегистрировано и, при необходимости, сведения о начальном состоянии устройства.
Оператор Интернета вещей настраивает одну или несколько отдельных регистраций и (или) групп регистрации для пользовательского выделения и предоставляет сведения о вызове пользовательского веб-перехватчика выделения в Функции Azure.
Когда устройство регистрируется с помощью записи регистрации, настроенной для пользовательского веб-перехватчика выделения, DPS отправляет запрос POST в веб-перехватчик с текстом запроса в объект запроса AllocationRequest. Объект AllocationRequest содержит сведения о устройстве, пытающегося подготовить, и отдельную группу регистрации или группу регистрации, которую она подготавливает. Сведения об устройстве могут включать необязательные пользовательские полезные данные, отправленные с устройства, в запросе на регистрацию. Дополнительные сведения см. в разделе "Запрос настраиваемой политики выделения".
Функция Azure выполняет и возвращает объект AllocationResponse при успешном выполнении. Объект AllocationResponse содержит центр Интернета вещей, в котором устройство должно быть подготовлено, исходное состояние двойника и необязательные пользовательские полезные данные для возврата на устройство. Дополнительные сведения см . в ответе настраиваемой политики выделения.
DPS назначает устройство центру Интернета вещей, указанному в ответе, и, если исходный двойник возвращается, задает исходный двойник для устройства соответствующим образом. Если пользовательская полезные данные возвращается веб-перехватчиком, он передается на устройство вместе с назначенным центром Интернета вещей и сведениями о проверке подлинности в ответе регистрации от DPS.
Устройство подключается к назначенному Центру Интернета вещей и загружает исходное состояние двойника. Если пользовательская полезные данные возвращаются в ответе на регистрацию, устройство использует его в соответствии с собственной логикой на стороне клиента.

В следующих разделах содержатся дополнительные сведения о пользовательском запросе на выделение и ответе, пользовательских полезных данных и реализации политики. Полный пример пользовательской политики выделения см. в разделе "Использование настраиваемых политик выделения".

Запрос настраиваемой политики выделения

DPS отправляет запрос POST в веб-перехватчик на следующую конечную точку: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Текст запроса — это объект AllocationRequest :

Имя свойства	Description
индивидуальныйenrollment	Отдельная запись регистрации, содержащая свойства, связанные с отдельной регистрацией, из которой был получен запрос на выделение. Если устройство регистрируется через отдельную регистрацию.
enrollmentGroup	Запись группы регистрации, содержащая свойства, связанные с группой регистрации, из которой был получен запрос на выделение. Присутствует, если устройство регистрируется через группу регистрации.
deviceRuntimeContext	Объект, содержащий свойства, связанные с зарегистрированным устройством. Всегда присутствует.
linkedHubs	Массив, содержащий имена узлов центров Интернета вещей, связанных с записью регистрации, из которой был получен запрос на выделение. Устройство может быть назначено любому из этих центров Интернета вещей. Всегда присутствует.

Объект DeviceRuntimeContext имеет следующие свойства:

Свойство	Type	Описание
registrationId	строка	Идентификатор регистрации, предоставленный устройством во время выполнения. Всегда присутствует.
currentIotHubHostName	строка	Имя узла Центра Интернета вещей, которому устройство было назначено ранее (при наличии). Не присутствует, если это начальное назначение. Это свойство можно использовать для определения того, является ли это первоначальным назначением для устройства или было ли устройство назначено ранее.
currentDeviceId	строка	Идентификатор устройства из предыдущего назначения устройства (если таковой есть). Не присутствует, если это начальное назначение.
x509	X509DeviceAttestation	Для аттестации X.509 содержит сведения о сертификате.
симметричный ключ	SymmetricKeyAttestation	Для аттестации симметричного ключа содержит сведения о первичном и вторичном ключе.
tpm	TpmAttestation	Для аттестации доверенного платформенного модуля содержит сведения о ключе подтверждения и корневом ключе хранилища.
payload	объект	Содержит свойства, указанные устройством в свойстве полезных данных во время регистрации. Указывает, отправляет ли устройство пользовательскую полезные данные в запросе на регистрацию DPS.

В следующем формате JSON показан объект AllocationRequest , отправляемый DPS для устройства, регистрирующегося через группу регистрации на основе симметричного ключа.

{
   "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"
   ]
}

Так как это начальная регистрация устройства, свойство deviceRuntimeContext содержит только идентификатор регистрации и сведения о проверке подлинности для устройства. В следующем формате JSON показан объект deviceRuntimeContext для последующего вызова для регистрации того же устройства. Обратите внимание, что текущее Центр Интернета вещей имя узла и идентификатор устройства включены в запрос.

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

Ответ настраиваемой политики выделения

Успешный запрос возвращает объект AllocationResponse .

Свойство	Description
initialTwin	Необязательно. Объект, содержащий требуемые свойства и теги, заданные в исходном двойнике в назначенном Центре Интернета вещей. DPS использует свойство initialTwin для задания исходного двойника в назначенном Центре Интернета вещей при первоначальном назначении или при повторной подготовке, если политика миграции записи регистрации настроена для повторной подготовки и сброса в начальную конфигурацию. В обоих случаях, если initialTwin не возвращается или имеет значение NULL, DPS задает двойник в назначенном Центре Интернета вещей начальным параметрам двойника в записи регистрации. DPS игнорирует initialTwin для всех остальных параметров повторной подготовки в записи регистрации. Дополнительные сведения см. в разделе "Сведения о реализации".
iotHubHostName	Обязательный. Имя узла Центра Интернета вещей, назначаемое устройству. Это должен быть один из центров Интернета вещей, переданных в свойстве linkedHubs в запросе.
payload	Необязательно. Объект, содержащий данные, передаваемые на устройство в ответе регистрации. Точные данные будут зависеть от неявного контракта, определенного разработчиком между устройством и пользовательской функцией выделения.

В следующем формате JSON показан объект AllocationResponse , возвращаемый пользовательской функцией выделения в DPS, например, для приведенной выше регистрации.

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

Использование полезных данных устройства в пользовательском выделении

Устройства могут отправлять пользовательские полезные данные, передаваемые DPS в веб-перехватчик пользовательского выделения, который затем может использовать эти данные в своей логике. Веб-перехватчик может использовать эти данные несколькими способами, возможно, чтобы определить, какой центр Интернета вещей назначить устройство или найти информацию во внешней базе данных, которая может использоваться для задания свойств начального двойника. И наоборот, веб-перехватчик может вернуть данные обратно на устройство через DPS, который может использоваться в клиентской логике устройства.

Например, может потребоваться выделить устройства на основе модели устройства. В этом случае устройство можно настроить для отправки сведений о модели в полезные данные запроса при регистрации в DPS. DPS передает эту полезные данные пользовательскому веб-перехватчику выделения, который определяет, какой центр Интернета вещей будет подготовлен для устройства на основе сведений об модели устройства. При необходимости веб-перехватчик может вернуть данные обратно в DPS в качестве объекта JSON в ответе веб-перехватчика, и DPS вернет эти данные на устройство в ответе на регистрацию.

Устройство отправляет полезные данные в службу DPS

Устройство вызывает API регистрации для регистрации в DPS. Запрос можно улучшить с помощью дополнительного свойства полезных данных . Это свойство может содержать любой допустимый объект JSON. Точное содержимое зависит от требований решения.

Для аттестации с TPM текст запроса выглядит следующим образом:

{ 
    "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 отправляет полезные данные в веб-перехватчик пользовательского выделения

Если устройство содержит полезные данные в запросе на регистрацию, DPS передает полезные данные в свойстве AllocationRequest.deviceRuntimeContext.payload при вызове пользовательского веб-перехватчика выделения.

Для запроса на регистрацию доверенного платформенного модуля в предыдущем разделе контекст среды выполнения устройства будет выглядеть следующим образом:

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

Если это не начальная регистрация устройства, контекст среды выполнения также будет содержать свойства currentIoTHubHost и currentDeviceId .

Настраиваемый веб-перехватчик выделения возвращает данные в DPS

Веб-перехватчик настраиваемой политики выделения может возвращать данные, предназначенные для устройства в DPS в объекте JSON с помощью свойства AllocationResponse.payload в ответе веб-перехватчика.

В следующем формате JSON показан ответ веб-перехватчика, содержащий полезные данные:

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

DPS отправляет полезные данные на устройство

Если DPS получает полезные данные в ответе веб-перехватчика, он передает эти данные обратно на устройство в свойстве RegistrationOperationStatus.registrationState.payload в ответе на успешную регистрацию. Свойство registrationState имеет тип DeviceRegistrationResult.

В следующем формате JSON показан успешный ответ регистрации для устройства TPM, включающего свойство полезных данных :

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

Сведения о реализации

Пользовательский веб-перехватчик выделения можно вызвать для устройства, которое ранее не зарегистрировано через DPS (начальное назначение) или для устройства, которое ранее зарегистрировано через DPS (повторное создание). DPS поддерживает следующие политики повторной подготовки: повторное создание и перенос данных, повторная подготовка и сброс на начальную конфигурацию и никогда не повторное создание. Эти политики применяются всякий раз, когда ранее подготовленное устройство назначается новому центру Интернета вещей. Дополнительные сведения см. в разделе "Повторная подготовка".

В следующих пунктах описаны требования, которые веб-перехватчик пользовательского выделения должен учитывать и поведение при разработке веб-перехватчика.

Устройство должно быть назначено одному из центров Интернета вещей в свойстве AllocationRequest.linkedHubs . Это свойство содержит список центров Интернета вещей по имени узла, которому можно назначить устройство. Обычно это состоит из центров Интернета вещей, выбранных для записи регистрации. Если в записи регистрации не выбраны центры Интернета вещей, они будут содержать все центры Интернета вещей, связанные с экземпляром DPS. Наконец, если устройство перепроиздается и политика повторной подготовки не задана в записи регистрации, она будет содержать только центр Интернета вещей, которому в настоящее время назначено устройство.
При первоначальном назначении, если свойство initialTwin возвращается веб-перехватчиком, DPS установит исходный двойник для устройства в назначенном Центре Интернета вещей соответствующим образом. Если свойство initialTwin опущено или равно null, DPS задает начальный двойник для устройства начальному параметру двойника, указанному в записи регистрации.
При повторной подготовке DPS следует политике повторной подготовки в записи регистрации. DPS использует только свойство initialTwin в ответе, если текущий центр Интернета вещей изменен, а политика повторной подготовки для записи регистрации выполняется повторно и сбрасывается до начальной конфигурации. В этом случае DPS задает начальный двойник для устройства в новом центре Интернета вещей точно так же, как и во время первоначального назначения в предыдущем маркере. Во всех остальных случаях DPS игнорирует свойство initialTwin .
Если свойство полезных данных задано в ответе, DPS всегда возвращает его на устройство независимо от того, является ли запрос для первоначального назначения или повторной подготовки.
Если устройство было подготовлено к центру Интернета вещей, свойство AllocationRequest.deviceRuntimeContext будет содержать свойство currentIotHubHostName , которое будет присвоено имени узла центра Интернета вещей, на котором устройство назначено.
Вы можете определить, какие из политик повторной подготовки в данный момент заданы в записи регистрации, проверив свойство reprovisionPolicy объекта AllocationRequest.individualEnrollment или свойство AllocationRequest.enrollmentGroup в запросе. В следующем формате JSON показаны параметры для политики повторной подготовки и переноса данных :
```
       "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }
```

Поддержка пакета SDK

Пакеты SDK для устройств DPS предоставляют API в C, C#, Java и Node.js для регистрации устройств с помощью DPS. Пакеты SDK Центр Интернета вещей и ПАКЕТЫ SDK DPS предоставляют классы, представляющие артефакты устройств и служб, такие как двойники устройств и записи регистрации, которые могут оказаться полезными при разработке пользовательских веб-перехватчиков выделения. Дополнительные сведения о пакетах SDK Для Интернета вещей Azure, доступных для Центр Интернета вещей и службы подготовки устройств Центр Интернета вещей, см. в Центр Интернета вещей Azure пакетах SDK и пакетах SDK для Azure DPS.

Следующие шаги

Полный пример использования пользовательской политики выделения см. в разделе "Использование пользовательских политик выделения"
Дополнительные сведения о Функции Azure см. в документации по Функции Azure

Бөлісу құралы: