Share via

Integratiestroom van sensorpartner

  • Artikel

Dit document gaat over de stappen voor onboarding die een partner moet uitvoeren om te integreren met Data Manager for Agriculture. Het bevat een overzicht van de API's die worden gebruikt voor het maken van modellen en lijstsensor, telemetrie-indeling om de gegevens te pushen en ten slotte de op IOTHub gebaseerde gegevensopname.

Onboarding

Onboarding omvat de stappen die zowel klanten als partners nodig hebben om te integreren met Data Manager for Agriculture en te beginnen met het ontvangen/verzenden van sensortelemetrie.

Schermopname van de stroom van sensorpartners.

Uit de bovenstaande afbeelding zijn de blokken die wit zijn gemarkeerd de stappen die een partner heeft genomen en de blokken die zwart zijn gemarkeerd, worden uitgevoerd door klanten.

Partnerstroom: fase 1

Hier volgt een reeks stappen die een partner moet uitvoeren voor integratie met Data Manager for Agriculture. Dit is een eenmalige integratie. Aan het einde van fase 1 stellen partners hun identiteit vast in Data Manager for Agriculture.

App maken

Partners moeten worden geverifieerd en gemachtigd om toegang te krijgen tot de Data Manager for Agriculture-api's voor gegevensvlak van klanten. Met toegang tot deze API's kunnen de partners sensormodellen, sensoren en apparaatobjecten maken binnen de Data Manager for Agriculture-instantie van de klant. De sensorobjectinformatie (gemaakt door partner) is wat door Data Manager for Agriculture wordt gebruikt om respectieve apparaten (sensoren) te maken in IOTHub.

Daarom moeten partners het volgende doen om verificatie en autorisatie in te schakelen

  1. Maak een Azure-account (als u er nog geen hebt gemaakt.)
  2. Een Microsoft Entra-app met meerdere tenants maken: de Microsoft Entra-app met meerdere tenants als de naam geeft, heeft toegang tot de tenants van meerdere klanten als de klanten expliciet toestemming hebben gegeven voor de partner-app (uitgelegd in de stap roltoewijzing).

Partners hebben toegang tot de API's in de tenant van de klant met behulp van de Microsoft Entra-app met meerdere tenants, geregistreerd in Microsoft Entra-id. App-registratie wordt uitgevoerd in Azure Portal, zodat het Microsoft Identity Platform verificatie- en autorisatieservices kan bieden voor uw toepassing die op zijn beurt toegang heeft tot Data Manager for Agriculture.

Volg de stappen in app-registratie tot stap 8 om de volgende informatie te genereren:

  1. Toepassings-id (client)
  2. Map-id (tenant)
  3. Naam van app

Kopieer en sla alle drie de waarden op zoals u ze nodig hebt voor het genereren van toegangstokens.

De gemaakte toepassings-id (client) is vergelijkbaar met de gebruikers-id van de toepassing. U moet nu het bijbehorende toepassingswachtwoord (clientgeheim) maken om de toepassing te identificeren.

Volg de stappen in Een clientgeheim toevoegen om clientgeheim te genereren en het gegenereerde clientgeheim te kopiëren.

Registratie

Zodra de partner een Microsoft Entra-app met meerdere tenants heeft gemaakt, delen partners de APP-id en partner-id handmatig met het Data Manager for Agriculture-team door een ondersteuningsticket te maken. Met behulp van deze informatie valideert Data Manager for Agriculture of het een authentieke partner is en een partneridentiteit (sensorPartnerId) maakt met behulp van de interne API's. Als onderdeel van het registratieproces kunnen partners hun partner-id (sensorPartnerId) gebruiken tijdens het maken van het object sensor/apparaten en ook als onderdeel van de sensorgegevens die ze pushen.

Als u de partner-id ophaalt, wordt de voltooiing van partner-Data Manager for Agriculture-integratie gemarkeerd. Nu wacht de partner op invoer van een van hun sensorklanten om hun gegevensopname in Data Manager voor Landbouw te initiëren.

Klantstroom

Klanten die Data Manager for Agriculture gebruiken, zijn op de hoogte van alle ondersteunde sensorpartners en hun respectieve APP-id's. Deze informatie is beschikbaar in de openbare documentatie voor al onze klanten. Op basis van de sensoren die klanten gebruiken en de APP-id van hun respectieve sensorpartner, moet de klant toegang verlenen tot de partner (APP ID) om te beginnen met het pushen van hun sensorgegevens naar hun Data Manager for Agriculture-exemplaar. Dit zijn de vereiste stappen:

Roltoewijzing

Klanten die ervoor kiezen om onboarding naar een specifieke partner uit te voeren, moeten de app-id van die specifieke partner hebben. Als u de app-id gebruikt, moet de klant de volgende dingen op volgorde uitvoeren.

  1. Toestemming : omdat de app van de partner zich in een andere tenant bevindt en de klant wil dat de partner toegang heeft tot bepaalde API's in hun Data Manager for Agriculture-exemplaar, moeten de klanten een specifiek eindpunt https://login.microsoft.com/common/adminconsent/clientId=[client_id] aanroepen en de [client_id] vervangen door de app-id van de partners. Hierdoor kan de Microsoft Entra-id van de klant deze APP-id herkennen wanneer deze wordt gebruikt voor roltoewijzing.

  2. Identiteitstoegangsbeheer (IAM): als onderdeel van identiteitstoegangsbeheer maken klanten een nieuwe roltoewijzing aan de bovenstaande app-id, die toestemming heeft gegeven. Data Manager for Agriculture maakt een nieuwe rol met de naam Sensor Partner (naast de bestaande rollen Beheerder, Inzender, Lezer). Klanten kiezen de rol van sensorpartner en voegen de partner-app-id toe en bieden toegang.

Initiatie

De klant heeft Data Manager for Agriculture op de hoogte gesteld dat ze sensorgegevens van een specifieke partner moeten ophalen. De partner weet echter nog niet voor welke klant ze de sensorgegevens moeten verzenden. Daarom zou de klant als volgende stap inschakelen naar integratie-API binnen Data Manager for Agriculture om een integratiekoppeling te genereren. Na het verkrijgen van de integratiekoppeling delen klanten de onderstaande informatie op volgorde, hetzij handmatig delen of via de portal van de partner.

  1. Toestemmingskoppeling en tenant-id : in deze stap biedt de klant een toestemmingskoppeling en tenant-id. De integratiekoppeling ziet er als volgt uit in het voorbeeld:

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

    Naast de toestemmingskoppeling zouden klanten ook een tenant-id opgeven. De tenant-id wordt gebruikt om het toegangstoken op te halen dat is vereist om het API-eindpunt van de klant aan te roepen.

    De partners valideren de toestemmingskoppeling door een GET-aanroep uit te voeren op de API voor het controleren van toestemming. Aangezien de koppeling volledig vooraf ingevulde aanvraag-URI is zoals verwacht door Data Manager for Agriculture. Als onderdeel van de GET-aanroep controleren de partners op een 200 OK-antwoordcode en IntegrationId die in het antwoord moet worden doorgegeven.

    Zodra het geldige antwoord is ontvangen, moeten partners twee gegevenssets opslaan

    • API-eindpunt (kan worden geëxtraheerd uit het eerste deel van de integratiekoppeling)
    • IntegrationId (wordt geretourneerd als onderdeel van het antwoord op GET-aanroep)

    Zodra de partner deze gegevenspunten valideert en opslaat, kunnen ze klanten in staat stellen sensoren toe te voegen waarvoor de gegevens moeten worden gepusht naar Data Manager for Agriculture.

  2. Sensoren/apparaten toevoegen: de partner weet nu met welke klant (API-eindpunt) ze moeten integreren, maar ze weten nog steeds niet met welke sensoren ze de gegevens moeten pushen. Daarom verzamelen partners de sensor-/apparaatgegevens waarvoor de gegevens moeten worden gepusht. Deze gegevens kunnen handmatig of via de gebruikersinterface van de portal worden verzameld.

    Na het toevoegen van de sensoren/apparaten kan de klant de gegevensstroom van de respectieve sensoren verwachten in hun Data Manager for Agriculture-exemplaar. Deze stap markeert de voltooiing van onboarding van klanten om sensorgegevens op te halen.

Partnerstroom: fase 2

De partner heeft nu de informatie om een specifiek API-eindpunt (gegevensvlak van klanten) aan te roepen, maar ze hebben nog steeds niet de informatie over waar ze de sensortelemetriegegevens moeten pushen?

Integratie

Als onderdeel van integratie moeten partners hun eigen app-id, app-geheim en tenant-id van de klant gebruiken die tijdens de stap voor app-registratie is verkregen om een toegangstoken te genereren met behulp van de oAuth-API van Microsoft. Hier volgt de curl-opdracht om het toegangstoken te genereren

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'

Het antwoord moet er als volgt uitzien:

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

Met de gegenereerde access_token roepen partners het gegevensvlakeindpunt van de klant aan om een sensormodel, sensor en apparaat te maken. Het wordt gemaakt in dat specifieke Data Manager for Agriculture-exemplaar met behulp van de API's die zijn gebouwd door Data Manager for Agriculture. Raadpleeg de partner-API-documentatie voor meer informatie over partner-API's.

Als onderdeel van de api voor het maken van de sensor bieden de partners de sensor-id, zodra de sensorresource is gemaakt, roepen partners de get verbindingsreeks-API aan om een verbindingsreeks voor die sensor op te halen.

Gegevens pushen

Integratie van sensorpartner maken

Sensorpartnerintegratie maken om een bepaalde partij te verbinden met een specifieke provider. De integrationId wordt later gebruikt bij het maken van de sensor. API-documentatie: Sensor Partner-integraties - Maken of bijwerken

Sensorgegevensmodel maken

Gebruik sensorgegevensmodel om het model van telemetrie te definiëren dat wordt verzonden. Alle telemetrie die door de sensor wordt verzonden, wordt gevalideerd volgens dit gegevensmodel.

API-documentatie: Sensorgegevensmodellen - Maken of bijwerken

Voorbeeldtelemetrie

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

Bijbehorend sensorgegevensmodel

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

Sensor maken

Maak sensor met behulp van de bijbehorende integratie-id en sensorgegevensmodel-id. DeviceId en HardwareId zijn optionele parameters, indien nodig, kunt u de apparaten - Maken of bijwerken gebruiken om het apparaat te maken.

API-documentatie: Sensoren - Maken of bijwerken

IoTHub-verbindingsreeks ophalen

Download IoTHub verbindingsreeks om sensortelemetrie te pushen naar het platform voor de gemaakte sensor.

API-documentatie: Sensoren - Verbindingsreeks ophalen

Gegevens pushen met IoT Hub

Gebruik IoT Hub Device SDK's om de telemetrie te pushen met behulp van de verbindingsreeks.

Voor alle sensortelemetriegebeurtenissen is 'timestamp' een verplichte eigenschap en moet de ISO 8601-indeling hebben (JJJJ-MM-DDTHH:MM:SSZ).

De partner is nu klaar om sensorgegevens te pushen voor alle sensoren met behulp van de respectieve verbindingsreeks die voor elke sensor zijn opgegeven. De partner verzendt de sensorgegevens echter in een JSON-indeling zoals gedefinieerd door FarmBeats. Raadpleeg het telemetrieschema dat hier wordt opgegeven.

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

Zodra de gegevens naar IOTHub zijn gepusht, kunnen de klanten sensorgegevens opvragen met behulp van de uitgaande API.

Volgende stappen

  • Test onze API's hier.