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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для получения дополнительной информации см. Авторизация с помощью ключа доступа > HTTP-триггер функций Azure.

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

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

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

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

В следующем формате 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 для последующего вызова для регистрации того же устройства. Обратите внимание, что текущие имя хоста IoT Hub и идентификатор устройства включены в запрос.

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

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

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

В следующем формате 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. Запрос можно улучшить с помощью дополнительного свойства 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"}
   }
}

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

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

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

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

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

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

• Если в ответе задано свойство payload, 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 IoT Hub и службы подготовки устройств Azure IoT Hub см. на страницах Azure IoT Hub SDKs и Azure DPS SDKs.

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

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

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