Integrationsflöde för sensorpartner

  • Artikel

I det här dokumentet beskrivs de registreringssteg som en partner måste vidta för att integrera med Data Manager for Agriculture. Den visar en översikt över DE API:er som används för att skapa modeller och listsensorer, telemetriformat för att skicka data och slutligen den IOTHub-baserade datainmatningen.

Introduktion

Onboarding omfattar de steg som krävs av båda kunderna och partner för att integrera med Data Manager för jordbruk och börja ta emot/skicka sensortelemetri.

Screenshot showing sensor partners flow.

Från bilden ovan är de block som är markerade i vitt de steg som vidtas av en partner, och de som är markerade i svart görs av kunderna.

Partnerflöde: Fas 1

Här är den uppsättning steg som en partner behöver utföra för att integrera med Data Manager for Agriculture. Det här är en engångsintegrering. I slutet av fas 1 etablerar partner sin identitet i Data Manager for Agriculture.

App skapad

Partner måste autentiseras och auktoriseras för att få åtkomst till Data Manager for Agriculture-kundernas API:er för dataplan. Med åtkomst till dessa API:er kan partnerna skapa sensormodeller, sensorer och enhetsobjekt i kundernas Instans av Data Manager for Agriculture. Informationen om sensorobjektet (skapad av partner) är det som används av Data Manager for Agriculture för att skapa respektive enheter (sensorer) i IOTHub.

För att aktivera autentisering och auktorisering måste partner därför göra följande

  1. Skapa ett Azure-konto (om du inte redan har skapat ett.)
  2. Skapa en Microsoft Entra-app för flera klientorganisationer – Microsoft Entra-appen med flera klientorganisationer som namnet betyder, har åtkomst till flera kunders klientorganisationer, om kunderna har gett uttryckligt medgivande till partnerappen (förklaras i rolltilldelningssteget).

Partner kan komma åt API:erna i kundklientorganisationen med hjälp av Microsoft Entra-appen för flera innehavare, registrerad i Microsoft Entra-ID. Appregistrering görs på Azure-portalen så att Microsofts identitetsplattform kan tillhandahålla autentiserings- och auktoriseringstjänster för ditt program som i sin tur har åtkomst till Data Manager for Agriculture.

Följ stegen i Appregistreringfram till steg 8 för att generera följande information:

  1. Program-ID (klient)-ID
  2. Katalog-ID (klientorganisation)
  3. Appnamn

Kopiera och lagra alla tre värden eftersom du skulle behöva dem för att generera åtkomsttoken.

Det program-ID (klient)-ID som skapats liknar programmets användar-ID och nu måste du skapa motsvarande programlösenord (klienthemlighet) för att programmet ska kunna identifiera sig.

Följ stegen i Lägg till en klienthemlighet för att generera klienthemlighet och kopiera klienthemligheten som genereras.

Registrering

När partnern har skapat en Microsoft Entra-app för flera innehavare delar partner manuellt APP-ID:t och partner-ID:t med Data Manager for Agriculture via e-postalias madma@microsoft.com . Med den här informationen verifierar Data Manager for Agriculture om det är en autentisk partner och skapar en partneridentitet (sensorPartnerId) med hjälp av de interna API:erna. Som en del av registreringsprocessen har partner aktiverats för att använda sitt partner-ID (sensorPartnerId) när de skapar sensor-/enhetsobjektet och även som en del av de sensordata som de skickar.

Att hämta partner-ID:t markerar slutförandet av partner-Data Manager för jordbruksintegrering. Nu väntar partnern på indata från någon av sina sensorkunder för att initiera datainmatningen till Data Manager for Agriculture.

Kundflöde

Kunder som använder Data Manager for Agriculture kommer att känna till alla sensorpartner som stöds och deras respektive APP-ID:n. Den här informationen finns i den offentliga dokumentationen för alla våra kunder. Baserat på de sensorer som kunder använder och deras respektive sensorpartners APP-ID måste kunden ge åtkomst till partnern (APP-ID) för att börja skicka sina sensordata till sin Data Manager for Agriculture-instans. Här är de steg som krävs:

Rolltilldelning

Kunder som väljer att registrera sig för en specifik partner bör ha app-ID:t för den specifika partnern. Om du använder app-ID:t måste kunden göra följande i följd.

  1. Medgivande – Eftersom partnerns app finns i en annan klientorganisation och kunden vill att partnern ska få åtkomst till vissa API:er i sin Data Manager for Agriculture-instans måste kunderna anropa en specifik slutpunkt https://login.microsoft.com/common/adminconsent/clientId=[client_id] och ersätta [client_id] med partnerns app-ID. På så sätt kan kundernas Microsoft Entra-ID identifiera det här APP-ID:t när de använder det för rolltilldelning.

  2. IAM (IDENTITY Access Management) – Som en del av hantering av identitetsåtkomst skapar kunderna en ny rolltilldelning till app-ID:t ovan, som har getts medgivande. Data Manager for Agriculture skapar en ny roll som kallas sensorpartner (förutom de befintliga rollerna Admin, Deltagare och Läsare). Kunder väljer rollen sensorpartner och lägger till partnerappens ID och ger åtkomst.

Inledande

Kunden har gjort Data Manager for Agriculture medveten om att de behöver hämta sensordata från en specifik partner. Partnern vet dock ännu inte för vilken kund som ska skicka sensordata. Som nästa steg anropar kunden därför integrerings-API:et i Data Manager for Agriculture för att generera en integreringslänk. Efter att ha hämtat integrationslänken skulle kunderna dela informationen nedan i följd, antingen manuellt dela eller använda partnerns portal.

  1. Medgivandelänk och klientorganisations-ID – I det här steget tillhandahåller kunden en medgivandelänk och ett klient-ID. Integreringslänken ser ut som i exemplet:

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

    Utöver medgivandelänken skulle kunderna också tillhandahålla ett klientorganisations-ID. Klientorganisations-ID:t används för att hämta den åtkomsttoken som krävs för att anropa till kundens API-slutpunkt.

    Partnerna validerar medgivandelänken genom att göra ett GET-anrop på api:et check consent link . Eftersom länken är helt ifyllda begärande-URI som förväntat av Data Manager för jordbruk. Som en del av GET-anropet söker partnerna efter att en 200 OK-svarskod och IntegrationId ska skickas i svaret.

    När det giltiga svaret har tagits emot måste partner lagra två uppsättningar med information

    • API-slutpunkt (kan extraheras från den första delen av integreringslänken)
    • IntegrationId (returneras som en del av svaret på GET-anropet)

    När partnern har verifierat och lagrat dessa datapunkter kan de göra det möjligt för kunder att lägga till sensorer för vilka data måste push-överföras till Data Manager for Agriculture.

  2. Lägg till sensorer/enheter – Nu vet partnern för vilken kund (API-slutpunkt) de behöver integrera med, men de vet fortfarande inte för vilka alla sensorer de behöver för att skicka data. Därför samlar partner in den sensor-/enhetsinformation som data behöver push-överföras för. Dessa data kan samlas in antingen manuellt eller via portalens användargränssnitt.

    Efter att ha lagt till sensorer/enheter kan kunden förvänta sig respektive sensorers dataflöde i sin Data Manager for Agriculture-instans. Det här steget markerar slutförandet av kundens registrering för att hämta sensordata.

Partnerflöde: Fas 2

Partnern har nu information för att anropa en specifik API-slutpunkt (kundernas dataplan), men de har fortfarande inte informationen om var de behöver skicka sensortelemetridata?

Integrering

Som en del av integreringen måste partner använda sitt eget app-ID, apphemlighet och kundens klient-ID som förvärvades under appregistreringssteget, för att generera en åtkomsttoken med hjälp av Microsofts oAuth-API. Här är curl-kommandot för att generera åtkomsttoken

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'

Svaret ska se ut så här:

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

Med den genererade access_token anropar partner kundernas dataplansslutpunkt för att skapa sensormodell, sensor och enhet. Den skapas i den specifika Data Manager for Agriculture-instansen med hjälp av API:erna som skapats av Data Manager for Agriculture. Mer information om partner-API:er finns i dokumentationen för partner-API:et.

Som en del av API:et för att skapa sensorn tillhandahåller partnerna sensor-ID:t. När sensorresursen har skapats anropar partnerna api:et get anslutningssträng för att få en anslutningssträng för sensorn.

Skicka data

Skapa sensorpartnerintegrering

Skapa sensorpartnerintegrering för att ansluta en viss part till en specifik provider. IntegrationId används senare när sensorn skapas. API-dokumentation: Sensorpartnerintegreringar – Skapa eller uppdatera

Skapa sensordatamodell

Använd sensordatamodellen för att definiera modellen för telemetri som skickas. All telemetri som skickas av sensorn verifieras enligt den här datamodellen.

API-dokumentation: Sensordatamodeller – Skapa eller uppdatera

Exempeltelemetri

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

Motsvarande sensordatamodell

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

Skapa sensor

Skapa sensor med motsvarande integrations-ID och sensordatamodell-ID. DeviceId och HardwareId är valfria parametrar, om det behövs kan du använda Enheter – Skapa eller uppdatera för att skapa enheten.

API-dokumentation: Sensorer – Skapa eller uppdatera

Hämta IoTHub-anslutningssträng

Hämta IoTHub-anslutningssträng för att skicka sensortelemetri till plattformen för sensorn som skapats.

API-dokumentation: Sensorer – Hämta Anslut ionssträng

Skicka data med IoT Hub

Använd IoT Hub Device SDK:er för att push-överföra telemetrin med hjälp av anslutningssträng.

För alla sensortelemetrihändelser är "tidsstämpel" en obligatorisk egenskap och måste vara i ISO 8601-format (ÅÅÅÅ-MM-DDTHH:MM:SSZ).

Partnern är nu redo att börja skicka sensordata för alla sensorer med respektive anslutningssträng som tillhandahålls för varje sensor. Partnern skulle dock skicka sensordata i ett JSON-format som definierats av FarmBeats. Se telemetrischemat som anges här.

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

När data skickas till IOTHub kan kunderna köra frågor mot sensordata med hjälp av utgående API.

Nästa steg

  • Testa våra API:er här.