Flusso di integrazione del partner del sensore

Articolo
05/23/2024

Questo documento illustra i passaggi di onboarding che un partner deve eseguire per l'integrazione con Data Manager for Agriculture. Presenta una panoramica delle API usate per creare modelli e sensori di elenco, formato di telemetria per eseguire il push dei dati e infine l'inserimento dei dati basato su IOTHub.

Onboarding

L'onboarding illustra i passaggi richiesti da clienti e partner per l'integrazione con Data Manager per l'agricoltura e iniziare a ricevere/inviare i dati di telemetria dei sensori rispettivamente.

Screenshot che mostra il flusso dei partner del sensore.

Dalla figura precedente, i blocchi evidenziati in bianco sono i passaggi eseguiti da un partner e quelli evidenziati in nero vengono eseguiti dai clienti.

Flusso del partner: fase 1

Ecco il set di passaggi che un partner deve eseguire per l'integrazione con Data Manager for Agriculture. Si tratta di un'integrazione una tantum. Alla fine della fase 1, i partner stabiliscono la propria identità in Data Manager for Agriculture.

Creazione di app

I partner devono essere autenticati e autorizzati ad accedere alle API del piano dati dei clienti di Data Manager for Agriculture. L'accesso a queste API consente ai partner di creare modelli di sensori, sensori e oggetti dispositivo all'interno dell'istanza di Data Manager for Agriculture dei clienti. Le informazioni sull'oggetto sensore (create dal partner) sono usate da Data Manager per l'agricoltura per creare i rispettivi dispositivi (sensori) in IOTHub.

Di conseguenza, per abilitare l'autenticazione e l'autorizzazione, i partner devono eseguire le operazioni seguenti

Creare un account Azure (se non ne è già stato creato uno).
Creare un'app Microsoft Entra multi-tenant: l'app Microsoft Entra multi-tenant come nome significa, ha accesso a più tenant dei clienti, se i clienti hanno dato il consenso esplicito all'app partner (come illustrato nel passaggio di assegnazione del ruolo).

I partner possono accedere alle API nel tenant del cliente usando l'app Microsoft Entra multi-tenant registrata in Microsoft Entra ID. La registrazione delle app viene eseguita nella portale di Azure in modo che Microsoft Identity Platform possa fornire servizi di autenticazione e autorizzazione per l'applicazione che a sua volta accede a Data Manager for Agriculture.

Seguire i passaggi forniti in Registrazioneapp fino al passaggio 8 per generare le informazioni seguenti:

ID applicazione (client)
ID della directory (tenant)
Nome app

Copiare e archiviare tutti e tre i valori necessari per generare il token di accesso.

L'ID applicazione (client) creato è simile all'ID utente dell'applicazione e ora è necessario creare la password dell'applicazione (segreto client) corrispondente per l'identificazione dell'applicazione.

Seguire la procedura descritta in Aggiungere un segreto client per generare il segreto client e copiare il segreto client generato.

Registrazione

Dopo che il partner ha creato correttamente un'app Microsoft Entra multi-tenant, i partner condividono manualmente l'ID APP e l'ID partner con il team di Data Manager for Agriculture creando un ticket di supporto. L'uso di queste informazioni data manager per l'agricoltura verifica se si tratta di un partner autentico e crea un'identità partner (sensorPartnerId) usando le API interne. Nell'ambito del processo di registrazione, i partner sono abilitati per l'uso dell'ID partner (sensorPartnerId) durante la creazione dell'oggetto sensore/dispositivo e anche come parte dei dati del sensore di cui eseguono il push.

Ottenere l'ID partner contrassegna il completamento dell'integrazione tra partner-Data Manager per l'agricoltura. Il partner attende ora l'input da uno dei clienti dei sensori per avviare l'inserimento dei dati in Data Manager for Agriculture.

Flusso del cliente

I clienti che usano Data Manager per l'agricoltura saranno a conoscenza di tutti i partner di sensori supportati e dei rispettivi ID APP. Queste informazioni sono disponibili nella documentazione pubblica per tutti i clienti. In base ai sensori usati dai clienti e all'ID APP del rispettivo partner sensore, il cliente deve fornire l'accesso al partner (ID APP) per iniziare a eseguire il push dei dati del sensore nell'istanza di Data Manager for Agriculture. Ecco i passaggi necessari:

Assegnazione di ruolo

I clienti che scelgono di eseguire l'onboarding in un partner specifico devono avere l'ID app di quel partner specifico. L'uso dell'ID app cliente deve eseguire le operazioni seguenti in sequenza.

Consenso : poiché l'app del partner risiede in un tenant diverso e il cliente vuole che il partner acceda a determinate API nel proprio istanza di Data Manager per l'agricoltura, i clienti devono chiamare un endpoint https://login.microsoft.com/common/adminconsent/clientId=[client_id] specifico e sostituire [client_id] con l'ID app dei partner. Ciò consente all'ID Microsoft Entra dei clienti di riconoscere questo ID APP ogni volta che lo usano per l'assegnazione di ruolo.
Identity Access Management (IAM): nell'ambito della gestione degli accessi alle identità, i clienti creano una nuova assegnazione di ruolo all'ID app precedente, che è stato fornito il consenso. Data Manager for Agriculture crea un nuovo ruolo denominato Sensor Partner (oltre ai ruoli esistenti di Amministrazione, Collaboratore, Lettore). I clienti scelgono il ruolo partner sensore e aggiungono l'ID app partner e forniscono l'accesso.

Avvio

Il cliente ha reso Data Manager per l'agricoltura consapevole della necessità di ottenere i dati dei sensori da un partner specifico. Tuttavia, il partner non sa ancora per quale cliente deve inviare i dati del sensore. Di conseguenza, come passaggio successivo, il cliente chiamerebbe l'API di integrazione all'interno di Data Manager for Agriculture per generare un collegamento di integrazione. Dopo aver acquisito il collegamento di integrazione, i clienti condividerebbero le informazioni seguenti in sequenza, condividendo manualmente o usando il portale del partner.

Collegamento di consenso e ID tenant: in questo passaggio il cliente fornisce un collegamento di consenso e un ID tenant. Il collegamento di integrazione è simile a quello illustrato nell'esempio:

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

Oltre al collegamento di consenso, i clienti fornirebbero anche un ID tenant. L'ID tenant viene usato per recuperare il token di accesso necessario per chiamare l'endpoint API del cliente.

I partner convalidano il collegamento di consenso effettuando una chiamata GET sull'API del collegamento di consenso check. Poiché il collegamento è completamente prepopolato URI della richiesta come previsto da Data Manager for Agriculture. Come parte della chiamata GET, i partner controllano la presenza di un codice di risposta 200 OK e integrationId da passare nella risposta.

Una volta ricevuta la risposta valida, i partner devono archiviare due set di informazioni
- Endpoint API (può essere estratto dalla prima parte del collegamento di integrazione)
- IntegrationId (viene restituito come parte della risposta alla chiamata GET)
Dopo aver convalidato e archiviato questi punti dati, i partner possono consentire ai clienti di aggiungere sensori per i quali i dati devono essere inseriti in Data Manager per l'agricoltura.
Aggiungere sensori/dispositivi : ora il partner sa con quale cliente (endpoint API) deve integrarsi, ma non sa con quali sensori devono eseguire il push dei dati. Di conseguenza, i partner raccolgono le informazioni sul sensore/dispositivo per cui devono essere inseriti i dati. Questi dati possono essere raccolti manualmente o tramite l'interfaccia utente del portale.

Dopo aver aggiunto i sensori/dispositivi, il cliente può aspettarsi il flusso di dati dei rispettivi sensori nell'istanza di Data Manager per l'agricoltura. Questo passaggio contrassegna il completamento dell'onboarding dei clienti per recuperare i dati del sensore.

Flusso del partner: fase 2

Il partner ha ora le informazioni per chiamare un endpoint API specifico (piano dati dei clienti), ma non ha ancora le informazioni su dove devono eseguire il push dei dati di telemetria del sensore?

Integrazione

Nell'ambito dell'integrazione, i partner devono usare il proprio ID app, il segreto dell'app e l'ID tenant del cliente acquisiti durante il passaggio di registrazione dell'app, per generare un token di accesso usando l'API oAuth di Microsoft. Ecco il comando curl per generare il token di accesso

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 risposta dovrebbe essere simile alla seguente:

{
  "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 il access_token generato, i partner chiamano l'endpoint del piano dati dei clienti per creare un modello di sensore, un sensore e un dispositivo. Viene creato in tale istanza specifica di Data Manager per l'agricoltura usando le API create da Data Manager per l'agricoltura. Per altre informazioni sulle API dei partner, vedere la documentazione dell'API partner.

Nell'ambito dell'API di creazione del sensore, i partner forniscono l'ID sensore, una volta creata la risorsa del sensore, i partner chiamano nell'API get stringa di connessione per ottenere un stringa di connessione per tale sensore.

Effettuare il push dei dati

Creare l'integrazione del partner del sensore

Creare l'integrazione del partner del sensore per connettere una determinata parte a un provider specifico. L'integrationId viene usato successivamente nella creazione del sensore. Documentazione dell'API: Integrazioni dei partner del sensore - Creare o aggiornare

Creare un modello di dati del sensore

Usare il modello di dati del sensore per definire il modello di telemetria inviato. Tutti i dati di telemetria inviati dal sensore vengono convalidati in base a questo modello di dati.

Documentazione dell'API: Modelli di dati dei sensori - Creare o aggiornare

Telemetria di esempio

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

Modello di dati del sensore corrispondente

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

Creare un sensore

Creare un sensore usando l'ID di integrazione e l'ID del modello di dati del sensore corrispondenti. DeviceId e HardwareId sono parametri facoltativi, se necessario, è possibile usare Dispositivi - Crea o Aggiorna per creare il dispositivo.

Documentazione dell'API: Sensori - Creare o aggiornare

Ottenere i stringa di connessione IoTHub

Ottenere i stringa di connessione IoTHub per eseguire il push dei dati di telemetria dei sensori nella piattaforma per il sensore creato.

Documentazione dell'API: Sensors - Get Connessione ion String

Eseguire il push dei dati con hub IoT

Usare hub IoT SDK per dispositivi per eseguire il push dei dati di telemetria usando il stringa di connessione.

Per tutti gli eventi di telemetria del sensore, "timestamp" è una proprietà obbligatoria e deve essere in formato ISO 8601 (AAAA-MM-GGTHH:MM:SSZ).

Il partner è ora tutto pronto per iniziare a eseguire il push dei dati dei sensori per tutti i sensori usando i rispettivi stringa di connessione forniti per ogni sensore. Tuttavia, il partner inviano i dati del sensore in un formato JSON come definito da FarmBeats. Fare riferimento allo schema di telemetria fornito qui.

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

Dopo aver eseguito il push dei dati in IOTHub, i clienti saranno in grado di eseguire query sui dati dei sensori usando l'API in uscita.

Passaggi successivi

Testare le API qui.

Condividi tramite