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

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

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

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

Обзор

Следующие шаги описывают, как работают пользовательские правила распределения ресурсов.

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

2. Оператор Интернета вещей настраивает одну или несколько отдельных регистраций и (или) групп регистрации для пользовательского выделения и предоставляет сведения о вызове пользовательского веб-перехватчика выделения в Функции Azure.

3. Когда устройство регистрируется с помощью записи регистрации, настроенной для пользовательского веб-перехватчика выделения, DPS отправляет запрос POST в веб-перехватчик с текстом запроса в объект запроса AllocationRequest. Объект AllocationRequest содержит сведения об устройстве, которое необходимо подготовить, и индивидуальной регистрации или группе регистрации, через которую оно подготавливается. Сведения об устройстве могут включать необязательные пользовательские полезные данные, отправленные с устройства, в запросе на регистрацию. Дополнительные сведения см. в разделе Запрос настраиваемой политики выделения.

4. Функция Azure выполняет и возвращает объект AllocationResponse при успешном выполнении. Объект AllocationResponse содержит центр Интернета вещей, в котором устройство должно быть подготовлено, исходное состояние двойника и необязательные пользовательские полезные данные для возврата на устройство. Дополнительные сведения см . в ответе настраиваемой политики выделения.

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

6. Устройство подключается к назначенному Центру Интернета вещей и загружает исходное состояние двойника. Если пользовательские полезные данные возвращаются в ответе на регистрацию, устройство использует их в соответствии с собственной логикой на стороне клиента.

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

Управление ключами функций

Пользовательские политики выделения используют ключи функций для проверки подлинности вызовов Функции Azure где задан Functionуровень авторизации. Поведение управления ключами зависит от того, настраивается ли настраиваемая политика выделения с помощью портал Azure или программно.

Ключи функций на портале

При создании регистрации в портал Azure и указании настраиваемой политики выделения портал автоматически обрабатывает извлечение и внедрение ключа функции.

После выбора функции для настраиваемой политики распределения портал извлекает ключ функции. Этот шаг не отображается пользователям через интерфейс портала. Затем ключ функции хранится в составе зашифрованного URL-адреса веб-перехватчика, используемого DPS для вызова функции. Ключ не отображается на портале.

Вы можете убедиться, что ключ внедрен в URL-адрес вебхука, выполнив команду GET для получения сведений о регистрации. В конфигурации регистрации ключ функции включен в поле webhookUrl .

Ключи функций с API

При создании регистрации программным способом с помощью API DPS необходимо вручную указать ключ во время создания регистрации. Если ключ не указан, вызов Функции Azure завершается ошибкой проверки подлинности.

Прежде чем создавать индивидуальную или групповую регистрацию, получите ключ функции из вашего функционала. Дополнительные сведения см. в разделе "Получение ключей доступа к функциям". Затем добавьте ключ функции в поле webhookUrl объекта CustomAllocationDefinition.

Дополнительные сведения см. в разделе "Авторизация ключа доступа".

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

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

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

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

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

Имущество	Тип	Описание
идентификатор регистрации	строка	Идентификатор регистрации, предоставленный устройством в процессе выполнения. Всегда присутствует.
текущее имя хоста IotHub	строка	Имя хоста хаба IoT, которому устройство было назначено ранее (при наличии). Не присутствует, если это начальное назначение. Это свойство можно использовать для определения того, является ли это первым назначением для устройства или было ли устройство уже назначено ранее.
текущий идентификатор устройства	строка	Идентификатор устройства из предыдущего назначения устройства (если таковой есть). Не присутствует, если это начальное назначение.
х509	X509Аттестация устройств	Аттестация X.509 содержит данные о сертификате.
симметричный ключ	Удостоверение симметричного ключа	Для аттестации симметричного ключа содержит сведения о первичном и вторичном ключе.
доверенный платформенный модуль	TpmАттестация	Для аттестации доверенного платформенного модуля содержит сведения о ключе подтверждения и корневом ключе хранилища.
полезная нагрузка	объект	Содержит свойства, указанные устройством в свойстве нагрузки во время регистрации. Присутствует, если устройство отправляет пользовательские данные в запросе на регистрацию в 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 .

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

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

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

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

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

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

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

Устройство вызывает API регистрации DPS для регистрации в DPS. Запрос можно улучшить с помощью дополнительного свойства payload. Это свойство может содержать любой допустимый объект 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 при вызове пользовательского веб-перехватчика выделения.

Для запроса на регистрацию 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}, .. } 
} 

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

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

Веб-перехватчик настраиваемой политики выделения может возвращать в объекте JSON данные, предназначенные для устройства в DPS, с помощью свойства 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"}
   }
}

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

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

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

• Устройство должно быть назначено одному из центров Интернета вещей в свойстве AllocationRequest.linkedHubs . Это свойство содержит список центров Интернета вещей по имени узла, которому можно назначить устройство. Обычно это составляется из концентраторов IoT, выбранных для настройки регистрации. Если в записи о регистрации не выбраны центры Интернета вещей, она содержит все центры Интернета вещей, подключенные к экземпляру DPS. Наконец, если устройство переоборудуется и политика Никогда не переоборудовать установлена в записи регистрации, в нем содержится только центр Интернета вещей, которому в настоящее время назначено устройство.

• При первоначальном назначении, если свойство initialTwin возвращается веб-перехватчиком, DPS задает начальный двойник для устройства в назначенном Центре Интернета вещей соответствующим образом. Если свойство initialTwin опущено или равно null, DPS задает начальный двойник для устройства начальному параметру двойника, указанному в записи регистрации.

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

• Если свойство payload задано в ответе, DPS всегда возвращает его устройству независимо от того, предназначен ли запрос для первоначального назначения или переподготовки.

• Если устройство было ранее передано в IoT узел, свойство AllocationRequest.deviceRuntimeContext содержит свойство currentIotHubHostName, которое устанавливается как имя хоста узла IoT, где устройство в настоящее время назначено.

• Вы можете определить, какая политика повторной подготовки в настоящее время задана в записи регистрации, проверив свойство 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 IoT, доступных для Центра Интернета вещей и Службы подготовки устройств Центра Интернета вещей, см. в разделе Azure IoT Hub SDKs и Microsoft SDKs для службы подготовки устройств Центра Интернета вещей.

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

• Для полного примера использования настраиваемой политики выделения см. Руководство: Использование пользовательских политик выделения с помощью службы подготовки устройств (DPS)

• Дополнительные сведения о Функции Azure см. в документации по Функции Azure