Руководство: использование обогащений сообщений в Azure IoT Hub

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

В первой части этого руководства вы узнали, как создавать пользовательские конечные точки и маршрутизировать сообщения в другие службы Azure. В этом руководстве вы увидите, как создать и настроить дополнительные ресурсы, необходимые для тестирования обогащений сообщений в центре Интернета вещей. Ресурсы включают второй контейнер хранилища для существующей учетной записи хранения (созданной в первой части руководства), в котором будут размещаться обогащенные сообщения, и маршрут отправки сообщений. После создания конфигураций для маршрутизации и обогащения сообщений вы воспользуетесь приложением для отправки сообщений в центр Интернета вещей. Центр затем перенаправит их в оба контейнера хранения. Обогащаются только те сообщения, которые отправляются в конечную точку для контейнера enriched хранения.

В этом руководстве вы выполните следующие задачи:

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

Предварительные условия

• У вас должна быть подписка Azure. Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

• Необходимо пройти обучение Учебное пособие: Отправка данных устройства в хранилище Azure с помощью маршрутизации сообщений IoT Hub и сохранить созданные для этого ресурсы.

• Убедитесь, что в брандмауэре открыт порт 8883. Пример устройства в этом руководстве использует протокол MQTT, который передает данные через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

Портал Azure

Для портала Azure нет других предварительных требований.

Azure CLI

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Создание второго контейнера в учетной записи хранения

В первой части этого руководства вы создали учетную запись хранения и контейнер для перенаправленных сообщений. Теперь необходимо создать второй контейнер для обогащенных сообщений.

Портал Azure

1. На портале Azure найдите раздел Учетные записи хранения.

2. Выберите учетную запись, созданную ранее.

3. В меню учетной записи хранения выберите Контейнеры в разделе Хранилище данных.

4. Выберите Контейнер, чтобы создать контейнер.

   

5. Присвойте контейнеру enrichedимя и нажмите кнопку "Создать".

Azure CLI

Совет

Многие команды CLI, используемые в этом руководстве, используют одни и те же параметры. Для удобства мы определяем локальные переменные, которые можно вызывать по мере необходимости. Не забудьте запустить все команды в одном сеансе, иначе будет необходимо переопределить переменные.

Значения этих переменных должны совпадать с ресурсами, которые использовались в первой части этого руководства.

1. Определите переменные для центра Интернета вещей, учетной записи хранения и контейнера.

   GROUP_NAME. Замените этот заполнитель именем группы ресурсов, содержащей Центр Интернета вещей.

   IOTHUB_NAME: Замените заполнитель именем центра Интернета вещей.

   DEVICE_ID. Замените этот заполнитель идентификатором устройства.

   STORAGE_NAME. Замените этот заполнитель именем учетной записи хранения.

   В этом руководстве значение переменной containerName должно быть расширено.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. Используйте команду az storage container create, чтобы добавить контейнер в учетную запись хранения.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Маршрутизация сообщений во вторую конечную точку

Создайте вторую конечную точку и маршрут для обогащенных сообщений.

Внимание

В этой статье содержатся шаги по подключению к службе с помощью подписанного URL-адреса. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности в службе с помощью идентификатора Microsoft Entra или управляемых удостоверений является более безопасным подходом. Дополнительные сведения см. в рекомендациях по безопасности решений > Интернета вещей Cloud Security.

Портал Azure

1. Найдите нужный Центр Интернета вещей на портале Azure.

2. В меню ресурсов в разделе "Параметры Центра" выберите маршрутизацию сообщений и нажмите кнопку "Добавить".

   

3. На вкладке "Конечная точка" создайте конечную точку хранилища, указав следующие сведения:

   Параметр	Значение
   Тип конечной точки	Выберите Хранилище.
   Имя конечной точки	Введите ContosoStorageEndpointEnriched.
   Контейнер хранилища Azure	Щелкните Выберите контейнер. Следуйте инструкциям, чтобы выбрать учетную запись хранения и обогащенный контейнер, созданный в предыдущем разделе.
   Кодирование	Выберите JSON. Если это поле неактивно, регион вашей учетной записи хранения не поддерживает JSON. В этом случае продолжайте использовать AVRO по умолчанию.

   

4. Примите значения по умолчанию для остальных параметров и нажмите кнопку "Создать+ далее".

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

   Параметр	Значение
   Имя	ContosoStorageRouteEnriched (КонтосоХранилищеМаршрутОбогащенный)
   Источник данных	Убедитесь, что в раскрывающемся списке выбраны Сообщения телеметрии устройства.
   Включить маршрут	Убедитесь в том, что для этого поля задано значение enabled.
   Маршрутизация запроса	Введите level="storage" как строку запроса.

   

6. Выберите Создать и добавить обогащения.

Azure CLI

1. Настройте переменные для конечных точек и команд маршрутов, чтобы в них использовались значения ContosoStorageEndpointEnriched и ContosoStorageRouteEnriched.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Используйте команду az iot hub message-endpoint create, чтобы создать пользовательскую конечную точку, которая указывает на контейнер хранилища, сделанный в предыдущем разделе.

   az iot hub message-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Используйте команду az iot hub message-route create, чтобы создать маршрут, который передает любое сообщение в level=storage конечную точку контейнера хранилища.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Добавление обогащения сообщений в новый конечный пункт

Создайте три обогащения сообщений, которые будут перенаправлены в контейнер хранилища enriched.

Портал Azure

1. На вкладке «Обогащение» мастера добавления маршрута добавьте три обогащения для сообщений, поступающих в конечную точку для контейнера хранилища, который называется enriched.

   Добавьте эти значения в качестве обогащения сообщений для конечной точки ContosoStorageEndpointEnriched:

   Имя.	Значение
   myIotHub	$hubname
   Расположение устройства	$twin.tags.location (предполагается, что двойник устройства снабжен тегом местоположение)
   идентификатор клиента	6ce345b8-1e4a-411e-9398-d34587459a3a

   Когда вы закончите, ваши улучшения должны выглядеть примерно так, как на этом изображении:

   

2. Нажмите кнопку "Добавить ", чтобы добавить обогащения сообщений.

Azure CLI

Выполните три вызова команды az iot hub message-enrichment create, чтобы добавить обогащения сообщений в маршрут, идущий к созданной ранее конечной точке.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

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

Добавление тега location к двойнику устройства

Одно из обогащенных сообщений, настроенных в центре Интернета вещей, позволяет указать ключ DeviceLocation, значение которого определяется следующим путем двойника устройства: $twin.tags.location. Если у двойника устройства нет тега расположения, путь к двойнику $twin.tags.location будет помечен как строка для ключа DeviceLocation в обогащениях сообщений.

Выполните указанные ниже действия, чтобы добавить тег расположения для двойника устройства:

Портал Azure

1. Перейдите в Центр Интернета вещей на портале Azure.

2. Выберите устройства в меню навигации центра Интернета вещей, а затем выберите свое устройство.

3. Откройте вкладку Двойник устройства в верхней части страницы устройства и добавьте указанную ниже строку непосредственно перед закрывающей фигурной скобкой в нижней части двойника. Затем выберите Сохранить.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

Используйте команду az iot hub device-twin update, чтобы изменить двойник устройства, указав ключ и значение нового тега.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Совет

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

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

Тестирование обогащений сообщений

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

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

• Сообщения, направляемые в конечную точку службы хранилища ContosoStorageEndpointEnriched, будут обогащаться и будут сохраняться в контейнере enriched учетной записи хранения.

Если вы еще не запустили консольное приложение SimulatedDevice из первой части этого руководства, запустите его:

Совет

Если вы выполняете действия Azure CLI для этого руководства, запустите пример кода в отдельном сеансе. Таким образом, вы можете разрешить примеру кода продолжать работу, пока вы выполняете остальные действия интерфейса командной строки.

1. В папке примера перейдите к папке /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Определения переменных, которые вы обновили ранее, по-прежнему должны быть допустимыми. Если это не так, измените их в файле Program.cs:

   1. Найдите определения переменных в верхней части класса Программы. Обновите следующие переменные с помощью собственных данных:

      • s_myDeviceId. Идентификатор устройства, назначенный при регистрации устройства в центре Интернета вещей.
      • s_iotHubUri: имя узла центра Интернета вещей, которое принимает формат IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: первичный ключ устройства, указанный в сведениях об удостоверении устройства.

   2. Сохранить и закрыть файл.

3. Запустите пример кода:

   dotnet run
   

Дайте консольному приложению поработать несколько минут и просмотрите данные:

1. Войдите в свою учетную запись хранения на портале Azure.

2. Выберите Обозреватель хранилища в меню навигации. Выберите контейнеры Blob, чтобы просмотреть два контейнера, созданные в ходе этих руководств.

   

Сообщения в контейнере с именем enriched содержат обогащения, включенные в сообщения. Сообщения в контейнере, созданном ранее, представляют собой необработанные сообщения без обогащений. Раскройте содержимое контейнера enriched до нижнего уровня и откройте последний файл сообщения. Затем сделайте то же самое для другого контейнера, чтобы убедиться, что один из них обогащён, а другой — нет.

Если вы просматриваете обогащенные сообщения, вы должны увидеть "myIotHub" с именем хаба, местоположением и идентификатором клиента, например, следующим образом:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Очистка ресурсов

Чтобы удалить все ресурсы, которые были созданы в обоих частях этого руководства, удалите группу ресурсов. При этом будут также удалены все ресурсы, содержащиеся в группе. Если вы не хотите удалять всю группу ресурсов, можно выбрать отдельные ресурсы для удаления.

Портал Azure

1. В портале Azure перейдите к группе ресурсов, содержащей Центр Интернета вещей и учетную запись хранения для этого руководства.
2. Просмотрите все ресурсы, которые находятся в группе ресурсов, чтобы определить, какие ресурсы необходимо очистить.
   • Если вы хотите удалить ресурс, щелкните Удалить группу ресурсов.
   • Если требуется удалить только определенный ресурс, установите флажки рядом с каждым именем ресурса, чтобы выбрать те, которые требуется удалить. Затем выберите Удалить.

Azure CLI

1. Используйте команду az resource list, чтобы просмотреть все ресурсы в вашей группе ресурсов.

   az resource list --resource-group $resourceGroup --output table
   

2. Просмотрите все ресурсы, которые находятся в группе ресурсов, чтобы определить, какие ресурсы необходимо очистить.

   • Если вы хотите удалить все ресурсы, используйте команду az group delete.

     az group delete --name $resourceGroup
     

   • Если вы хотите удалить только определенные ресурсы, используйте команду az resource delete. Например:

     az resource delete --resource-group $resourceGroup --name $storageName
     

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

При работе с этим руководством вы настроили и проверили обогащение сообщений Центра Интернета вещей по мере их маршрутизации в конечную точку.

Дополнительные сведения об обогащении сообщений см. в статье Обзор обогащений сообщений.

Чтобы получить дополнительные сведения о Центре Интернета вещей, перейдите к следующему руководству.

Руководство. Настройка и использование метрик и журналов в Центре Интернета вещей