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

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

Введение в должность

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Регистрация

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

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

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

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

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

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

Согласие — Поскольку приложение партнера находится в другом арендаторе и клиент хочет, чтобы партнер имел доступ к определенным API в своем экземпляре Data Manager для сельского хозяйства, клиентам необходимо вызвать определённый конечный пункт https://login.microsoft.com/common/adminconsent/clientId=[client_id] и заменить [client_id] идентификатором приложения партнера. Это позволяет клиентам распознавать Microsoft Entra 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, созданных Data Manager для сельского хозяйства. Дополнительные сведения об 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: датчики — получение строки подключения

Отправка данных с помощью IoT-хаб

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

Для всех событий телеметрии датчика метка времени является обязательным свойством и должна быть в формате 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 здесь.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2024-05-23