Flujo de integración de asociados de sensor

Artículo
05/28/2024

En este documento se habla de los pasos de incorporación que un asociado debe realizar para integrarse con Data Manager for Agriculture. Presenta una visión general de las API que se usan para crear modelos y enumerar sensor, formato de telemetría para insertar los datos y, por último, la ingesta de datos basada en IOTHub.

Incorporación

La incorporación cubre los pasos necesarios para que los clientes y asociados se integren con Data Manager for Agriculture y empiecen a recibir o enviar telemetría del sensor respectivamente.

Captura de pantalla que muestra el flujo de asociados del sensor.

En la ilustración anterior, los bloques resaltados en blanco son los pasos realizados por un asociado y los resaltados en negro los realizan los clientes.

Flujo de asociados: Fase 1

Este es el conjunto de pasos que un asociado debe realizar para la integración con Data Manager for Agriculture. Se trata de una integración única. Al final de la fase 1, los asociados establecen su identidad en Data Manager for Agriculture.

Creación de aplicación

Los asociados deben autenticarse y autorizarse para acceder a las API del plano de datos de los clientes de Data Manager for Agriculture. El acceso a estas API permite a los asociados crear modelos de sensor, sensores y objetos de dispositivo dentro de la instancia de Data Manager for Agriculture de los clientes. La información del objeto de sensor (creada por el asociado) es la que usa Data Manager for Agriculture para crear los dispositivos (sensores) respectivos en IOTHub.

Por lo tanto, para habilitar la autenticación y autorización, los partners deben hacer lo siguiente

Cree una cuenta de Azure (si aún no tiene una creada)
Crear una aplicación de Microsoft Entra multiinquilino: la aplicación Microsoft Entra multiinquilino como indica el nombre, tiene acceso a varios inquilinos de clientes, si los clientes han dado consentimiento explícito a la aplicación de asociado (se explica en el paso de asignación de roles).

Los partners pueden acceder a las APIs en el inquilino del cliente mediante la aplicación multi-inquilino Microsoft Entra App, registrada en Microsoft Entra ID. El registro de aplicaciones se realiza en Azure Portal para que la plataforma de identidad de Microsoft pueda proporcionar servicios de autenticación y autorización para la aplicación que, a su vez, accede a Data Manager for Agriculture.

Siga los pasos proporcionados en Registro de aplicaciones hasta el paso 8 para generar la siguiente información:

Id. de la aplicación (cliente)
Id. de directorio (inquilino)
Nombre de aplicación

Copie y almacene los tres valores, ya que los necesitará para generar el token de acceso.

El id. de aplicación (cliente) creado es como el id. de usuario de la aplicación y ahora debe crear su contraseña de aplicación (secreto de cliente) correspondiente para que la aplicación se identifique.

Siga los pasos proporcionados en Agregar un secreto de cliente para generar el secreto de cliente y copiar el secreto de cliente generado.

Registro

Una vez que el asociado ha creado correctamente una aplicación de Microsoft Entra multiinquilino, los asociados comparten manualmente el identificador de aplicación y el identificador de asociado con el equipo de Data Manager for Agriculture mediante la creación de una incidencia de soporte técnico. El uso de esta información en Data Manager for Agriculture valida si es un asociado auténtico y crea una identidad de asociado (sensorPartnerId) mediante las API internas. Como parte del proceso de registro, los asociados están habilitados para usar su identificador de asociado (sensorPartnerId) al crear el objeto sensor/devices y también como parte de los datos del sensor que insertan.

Obtener el identificador de asociado marca la finalización de la integración de partner-Data Manager for Agriculture. Ahora, el asociado espera la entrada de cualquiera de sus clientes del sensor para iniciar su ingesta de datos en Data Manager for Agriculture.

Flujo de clientes

Los clientes que usen Data Manager for Agriculture conocerán todos los socios de sensores compatibles y sus respectivos ID de APP. Esta información está disponible en la documentación pública de todos nuestros clientes. En función de los sensores que usan los clientes y el identificador de aplicación de su asociado de sensor respectivo, el cliente tiene que proporcionar acceso al asociado (id. de aplicación) para empezar a insertar los datos del sensor en su instancia de Data Manager for Agriculture. Estos son los pasos necesarios:

Asignación de roles

Los clientes que decidan incorporarse a un asociado específico deben tener el identificador de aplicación de ese asociado específico. El uso del identificador de aplicación del cliente debe hacer lo siguiente en secuencia.

Consentimiento : dado que la aplicación del asociado reside en un inquilino diferente y el cliente quiere que el asociado acceda a determinadas API en su instancia de Data Manager for Agriculture, los clientes deben llamar a un punto de conexión https://login.microsoft.com/common/adminconsent/clientId=[client_id] específico y reemplazar [client_id] por el identificador de aplicación de los asociados. Esto permite que el Microsoft Entra ID de los clientes reconozca este APP ID siempre que lo usen para la asignación de roles.
Administración de identidad y acceso (IAM): como parte de la de identidad y acceso, los clientes crean una nueva asignación de funciones para el ID de aplicación anterior, que se proporcionó con consentimiento. Data Manager for Agriculture crea un nuevo rol denominado Sensor Partner (además de los roles de administrador, colaborador y lector existentes). Los clientes eligen el rol de asociado de sensor y agregan el identificador de la aplicación de asociado y proporcionan acceso.

Iniciación

El cliente ha hecho que Data Manager for Agriculture tenga en cuenta que necesita obtener datos del sensor de un asociado específico. Sin embargo, el asociado aún no sabe para qué cliente debe enviar los datos del sensor. Por lo tanto, como paso siguiente, el cliente llamaría a la API de integración dentro de Data Manager for Agriculture para generar un vínculo de integración. Después de adquirir el vínculo de integración, los clientes compartirían la siguiente información en secuencia, ya sea de forma manual o mediante el portal del asociado.

Vínculo de consentimiento e id.de inquilino : en este paso, el cliente proporciona un vínculo de consentimiento e id. de inquilino. El vínculo de integración es similar al que se muestra en el ejemplo:

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

Además del vínculo de consentimiento, los clientes también proporcionarían un identificador de inquilino. El identificador de inquilino se usa para capturar el token de acceso necesario para llamar al punto de conexión de API del cliente.

Los asociados validan el vínculo de consentimiento mediante la realización de una llamada GET en la API del vínculo comprobar consentimiento. Dado que el vínculo está totalmente rellenado previamente el URI de solicitud según lo previsto por Data Manager for Agriculture. Como parte de la llamada GET, los asociados comprueban si hay un código de respuesta 200 OK y IntegrationId que se pasará en la respuesta.

Una vez recibida la respuesta válida, los partners tienen que almacenar dos conjuntos de información
- Punto de conexión de API (se puede extraer de la primera parte del vínculo de integración)
- IntegrationId (se devuelve como parte de la respuesta a la llamada GET)
Una vez que el asociado valida y almacena estos puntos de datos, puede permitir que los clientes agreguen sensores para los que se deben insertar los datos en Data Manager for Agriculture.
Agregar sensores o dispositivos : ahora, el asociado sabe con qué cliente (punto de conexión de API) necesitan integrarse; sin embargo, todavía no saben con qué sensores necesitan insertar los datos. Por lo tanto, los asociados recopilan la información del sensor o dispositivo para la que se deben insertar los datos. Estos datos se pueden recopilar manualmente o a través de la interfaz de usuario del portal.

Después de agregar los sensores o dispositivos, el cliente puede esperar el flujo de datos de los sensores respectivos en su instancia de Data Manager for Agriculture. Este paso marca la finalización de la incorporación de clientes para capturar datos del sensor.

Flujo de asociado: Fase 2

El asociado ahora tiene la información para llamar a un punto de conexión de API específico (plano de datos de los clientes), pero aún no tienen la información sobre dónde necesitan insertar los datos de telemetría del sensor?

Integración

Como parte de la integración, los partners deben usar su propio identificador de aplicación, el secreto de aplicación y el identificador de inquilino del cliente adquiridos durante el paso de registro de la aplicación, para generar un token de acceso mediante la API de oAuth de Microsoft. Este es el comando curl para generar el token de acceso

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'

La respuesta debería tener este aspecto:

{
  "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"
}

Con el access_token generado, los asociados llaman al punto de conexión del plano de datos de los clientes para crear el modelo de sensor, el sensor y el dispositivo. Se crea en esa instancia específica de Data Manager for Agriculture mediante las API creadas por Data Manager for Agriculture. Para más información sobre las API de asociados, consulte la documentación de la API de asociados.

Como parte de la API de creación de sensores, los partners proporcionan el ID del sensor; una vez creado el recurso del sensor, los partners llaman a la API de obtención de cadena de conexión para obtener una cadena de conexión para ese sensor.

Inserción de datos

Creación de la integración de asociados de sensor

Cree la integración de asociados de sensor para conectar una entidad determinada con un proveedor específico. IntegrationId se usa más adelante en la creación del sensor. Documentación de API: Integraciones de asociados de sensor: creación o actualización

Creación de un modelo de datos de sensor

Use el modelo de datos del sensor para definir el modelo de telemetría que se envía. Toda la telemetría enviada por el sensor se valida según este modelo de datos.

Documentación de API: Modelos de datos del sensor: creación o actualización

Telemetría de ejemplo

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

Modelo de datos del sensor correspondiente

{
  "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
  }
}

Creación de un sensor

Cree el sensor mediante el identificador de integración correspondiente y el identificador del modelo de datos del sensor. DeviceId y HardwareId son parámetros opcionales, si es necesario, puede usar Devices - Create Or Update (Dispositivos: crear o actualizar ) para crear el dispositivo.

Documentación de API: Sensores: Creación o actualización

Obtención de la cadena de conexión de IoTHub

Obtenga la cadena de conexión de IoTHub para insertar la telemetría del sensor en la plataforma del sensor creado.

Documentación de API: Sensores: Obtención de la cadena de conexión

Inserción de datos mediante IoT Hub

Use los SDK de dispositivo de IoT Hub para insertar la telemetría mediante la cadena de conexión.

Para todos los eventos de telemetría del sensor, "marca de tiempo" es una propiedad obligatoria y tiene que estar en formato ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).

El asociado ahora está configurado para empezar a insertar datos del sensor para todos los sensores mediante la cadena de conexión correspondiente proporcionada para cada sensor. Sin embargo, el asociado enviaría los datos del sensor en un formato JSON tal como lo define FarmBeats. Consulte el esquema de telemetría que se proporciona aquí.

{
	"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
}

Una vez que los datos se insertan en IOTHub, los clientes podrían consultar los datos del sensor mediante la API de salida.

Pasos siguientes

Pruebe nuestras API aquí.

Compartir a través de