Поток интеграции с партнером датчика

Статья
05/23/2024

В этом документе рассказывается о действиях по подключению, которые партнер должен принять для интеграции с Data Manager для сельского хозяйства. В нем представлен обзор API, используемых для создания моделей и датчика списка, формата телеметрии для отправки данных и, наконец, приема данных на основе IOTHub.

Переход

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

Снимок экрана: поток партнеров датчика.

На приведенном выше рисунке блоки, выделенные белым цветом, — это шаги, выполняемые партнером, и те, которые выделены черным цветом, выполняются клиентами.

Поток партнеров: этап 1

Ниже приведен набор шагов, необходимых партнеру для интеграции с Диспетчером данных для сельского хозяйства. Это одноразовая интеграция. В конце этапа 1 партнеры устанавливают свое удостоверение в Диспетчере данных для сельского хозяйства.

Создание приложения

Партнерам необходимо пройти проверку подлинности и авторизоваться для доступа к API уровня данных диспетчера данных для сельского хозяйства. Доступ к этим API позволяет партнерам создавать модели датчиков, датчики и объекты устройств в экземпляре Диспетчера данных клиентов для сельского хозяйства. Сведения об объекте датчика (созданные партнером) — это то, что используется диспетчером данных для сельского хозяйства для создания соответствующих устройств (датчиков) в IOTHub.

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

Создайте учетную запись Azure (если у вас еще нет созданной учетной записи .)
Создайте мультитенантное приложение Microsoft Entra — мультитенантное приложение Microsoft Entra в качестве имени, имеет доступ к нескольким клиентам клиентов, если клиенты дали явное согласие на партнерское приложение (описано на шаге назначения ролей).

Партнеры могут получить доступ к API в клиенте клиента с помощью мультитенантного приложения Microsoft Entra App, зарегистрированного в идентификаторе Microsoft Entra. Регистрация приложений выполняется на портал Azure, чтобы платформа удостоверений Майкрософт могли предоставлять службы проверки подлинности и авторизации для приложения, которое, в свою очередь, обращается к Диспетчеру данных для сельского хозяйства.

Выполните действия, указанные в разделе "Регистрация приложений", пока шаг 8 не создаст следующие сведения:

Application (client) ID (Идентификатор приложения (клиент))
Идентификатор каталога (клиент)
Имя приложения

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

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

Выполните действия, описанные в разделе "Добавление секрета клиента" для создания секрета клиента и копирования созданного секрета клиента.

Регистрация

После успешного создания мультитенантного приложения Microsoft Entra партнеры вручную совместно используют идентификатор приложения и идентификатор партнера с помощью диспетчера данных для сельского хозяйства, создав запрос в службу поддержки. С помощью этого диспетчера данных для сельского хозяйства проверяет, является ли он подлинным партнером и создает удостоверение партнера (sensorPartnerId) с помощью внутренних API. В рамках процесса регистрации партнеры могут использовать свой идентификатор партнера (sensorPartnerId) при создании объекта датчика и устройств, а также в составе данных датчика, которые они отправляют.

Получение идентификатора партнера помечает завершение интеграции partner-Data Manager для сельского хозяйства. Теперь партнер ожидает ввода от любого из своих клиентов датчика, чтобы инициировать прием данных в Диспетчер данных для сельского хозяйства.

Поток клиента

Клиенты, использующие Data Manager для сельского хозяйства, будут знать обо всех поддерживаемых партнерах датчика и их соответствующих идентификаторах ПРИЛОЖЕНИй. Эта информация доступна в общедоступной документации для всех наших клиентов. На основе датчиков, используемых клиентами и идентификатором приложения соответствующего партнера датчика, клиент должен предоставить доступ к партнеру (идентификатору ПРИЛОЖЕНИЯ), чтобы начать отправку данных датчика в свой экземпляр Data Manager для сельского хозяйства. Ниже приведены необходимые действия.

Назначение ролей

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

Согласие . Так как приложение партнера находится в другом клиенте, и клиент хочет, чтобы партнер получить доступ к определенным API в своем экземпляре Data Manager для сельского хозяйства, клиенты должны вызвать определенную конечную точку https://login.microsoft.com/common/adminconsent/clientId=[client_id] и заменить [client_id] идентификатором приложения партнеров. Это позволяет клиентам удостоверять этот идентификатор приложения, когда они используют его для назначения ролей.
Управление доступом к удостоверениям (IAM) — в рамках управления доступом к удостоверениям клиенты создают новое назначение роли для указанного выше идентификатора приложения, который был предоставлен согласие. Диспетчер данных для сельского хозяйства создает новую роль с именем "Партнер датчика" (помимо существующих ролей администратора, участника, читателя). Клиенты выбирают роль партнера датчика и добавляют идентификатор приложения партнера и предоставляют доступ.

Запуск

Клиент сделал Data Manager для сельского хозяйства осведомлен о том, что им нужно получить данные датчика от конкретного партнера. Тем не менее, партнер пока не знает, для какого клиента они должны отправлять данные датчика. Таким образом, в качестве следующего шага клиент будет вызывать API интеграции в Диспетчере данных для сельского хозяйства, чтобы создать связь интеграции. После получения ссылки интеграции клиенты будут совместно использовать приведенные ниже сведения в последовательности, либо вручную предоставлять общий доступ или использовать портал партнера.

Ссылка на согласие и идентификатор клиента. На этом шаге клиент предоставляет ссылку согласия и идентификатор клиента. Ссылка на интеграцию выглядит так, как показано в примере:

fb-resource-name.farmbeats.com/sensor-partners/partnerId/integrations/IntegrationId/:check-consent?key=jgtHTFGDR?api-version=2021-07-31-preview

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

Партнеры проверяют ссылку согласия, выполняя вызов GET для API ссылки проверки согласия. Так как ссылка полностью заполнена URI запроса, как ожидалось, Диспетчер данных для сельского хозяйства. В рамках вызова GET партнеры проверяют код ответа 200 OK и IntegrationId, передаваемый в ответе.

После получения допустимого ответа партнерам необходимо сохранить два набора сведений.
- Конечная точка API (можно извлечь из первой части ссылки интеграции)
- IntegrationId (возвращается в рамках ответа на вызов GET)
После проверки и хранения этих точек данных партнер может позволить клиентам добавлять датчики, для которых данные должны быть отправлены в Диспетчер данных для сельского хозяйства.
Добавьте датчики и устройства . Теперь партнер знает, для какого клиента (конечная точка API) им нужно интегрироваться, однако они по-прежнему не знают, для каких всех датчиков они должны отправлять данные. Поэтому партнеры собирают сведения об датчике или устройстве, для которых необходимо отправить данные. Эти данные можно собирать вручную или с помощью пользовательского интерфейса портала.

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

Поток партнеров: этап 2

Теперь у партнера есть информация для вызова определенной конечной точки API (плоскости данных клиентов), но у них по-прежнему нет информации о том, где они должны отправлять данные телеметрии датчика?

Интеграция

В рамках интеграции партнеры должны использовать собственный идентификатор приложения, секрет приложения и идентификатор клиента, полученный на этапе регистрации приложения, чтобы создать маркер доступа с помощью API OAuth Майкрософт. Ниже приведена команда curl для создания маркера доступа

curl --location --request GET 'https://login.microsoftonline.com/<customer’s tenant ID> /oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_secret=<Your app secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<Your app ID>' \
--data-urlencode 'scope=https://farmbeats.azure.net/.default'

Результат должен выглядеть следующим образом:

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in": "3599",
  "expires_on": "1622530779",
  "not_before": "1622526879",
  "resource": "https://farmbeats.azure.net",
  "access_token": "eyJ0eXAiOiJKV1QiLC......tpZCI6InZhcF9"
}

С помощью созданной access_token партнеры вызывают конечную точку плоскости данных клиентов для создания модели датчика, датчика и устройства. Он создается в этом конкретном экземпляре Data Manager для сельского хозяйства с помощью API, созданных диспетчером данных для сельского хозяйства. Дополнительные сведения об API партнеров см. в документации по API партнеров.

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

Передача данных

Создание интеграции партнеров датчика

Создайте интеграцию партнера датчика для подключения определенной стороны к конкретному поставщику. IntegrationId позже используется при создании датчика. Документация по API: Интеграция партнеров датчика — создание или обновление

Создание модели данных датчика

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

Документация по API: модели данных датчика — создание или обновление

Пример данных телеметрии

{
	"pressure": 30.45,
	"temperature": 28,
	"name": "sensor-1"
}

Соответствующая модель данных датчика

{
  "type": "Sensor",
  "manufacturer": "Some sensor manufacturer",
  "productCode": "soil m",
  "measures": {
    "pressure": {
      "description": "measures soil moisture",
      "dataType": "Double",
      "type": "sm",
      "unit": "Bar",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    },
	"temperature": {
      "description": "measures soil temperature",
      "dataType": "Long",
      "type": "sm",
      "unit": "Celsius",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    },
	"name": {
      "description": "Sensor name",
      "dataType": "String",
      "type": "sm",
      "unit": "none",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    }
  },
  "sensorPartnerId": "sensor-partner-1",
  "id": "sdm124",
  "status": "new",
  "createdDateTime": "2022-01-24T06:12:15Z",
  "modifiedDateTime": "2022-01-24T06:12:15Z",
  "eTag": "040158a0-0000-0700-0000-61ee433f0000",
  "name": "my sdm for soil moisture",
  "description": "description goes here",
  "properties": {
    "key1": "value1",
    "key2": 123.45
  }
}

Создание датчика

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

Документация по API: датчики — создание или обновление

Получение строка подключения IoTHub

Получите строка подключения IoTHub для отправки данных телеметрии датчика на платформу, созданную датчиком.

Документация по API: датчики — получение строки подключения

Отправка данных с помощью Центр Интернета вещей

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

Для всех событий телеметрии датчика метка времени является обязательным свойством и должна быть в формате ISO 8601 (ГГГГ-ММ-ДДTHH:ММ:SSZ).

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

{
	"timestamp": "2022-02-11T03:15:00Z",
	"bar": 30.181,
	"bar_absolute": 29.748,
	"bar_trend": 0,
	"et_day": 0.081,
	"humidity": 55,
	"rain_15_min": 0,
	"rain_60_min": 0,
	"rain_24_hr": 0,
	"rain_day": 0,
	"rain_rate": 0,
	"rain_storm": 0,
	"solar_rad": 0,
	"temp_out": 58.8,
	"uv_index": 0,
	"wind_dir": 131,
	"wind_dir_of_gust_10_min": 134,
	"wind_gust_10_min": 0,
	"wind_speed": 0,
	"wind_speed_2_min": 0,
	"wind_speed_10_min": 0
}

После отправки данных на IOTHub клиенты смогут запрашивать данные датчика с помощью API исходящего трафика.

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

Проверьте наши API здесь.

Поделиться через