Freigeben über

Ablauf der Sensorintegration für Partner

  • Artikel

In diesem Dokument werden die Onboardingschritte erläutert, die Partner für die Integration mit Data Manager for Agriculture ausführen müssen. Es enthält eine Übersicht über die APIs, die zum Erstellen von Modellen und Auflisten von Sensoren verwendet werden, über das Telemetrieformat zum Pushen der Daten und schließlich über die IoT Hub-basierte Datenerfassung.

Onboarding

Das Onboarding deckt die Schritte ab, die Kunden und Partner durchführen müssen, um die Integration mit Data Manager for Agriculture einzurichten und Sensortelemetrie zu empfangen bzw. zu senden.

Screenshot des Ablaufs der Sensorintegration für Partner

In der obigen Abbildung sind die weiß hervorgehobenen Blöcke die Schritte, die von einem Partner durchgeführt werden, und die schwarz hervorgehobenen werden von Kunden durchgeführt.

Ablauf für Partner: Phase 1

Im Folgenden finden Sie die Schritte, die ein Partner für die Integration mit Data Manager for Agriculture durchführen muss. Es handelt sich um eine einmalige Integration. Am Ende von Phase 1 richten Partner ihre Identität in Data Manager for Agriculture ein.

App-Erstellung

Partner müssen authentifiziert und autorisiert werden, um auf die Datenebenen-APIs der Kunden von Data Manager for Agriculture zuzugreifen. Der Zugriff auf diese APIs ermöglicht es den Partnern, Sensormodelle, Sensoren und Geräteobjekte innerhalb der Kundeninstanz von Data Manager for Agriculture zu erstellen. Die Sensorobjektinformationen (vom Partner erstellt) werden von Data Manager for Agriculture verwendet, um entsprechende Geräte (Sensoren) in IoT Hub zu erstellen.

Für die Authentifizierung und Autorisierung müssen Partner die folgenden Schritte durchführen:

  1. Azure-Konto erstellen (falls noch nicht vorhanden)
  2. Mehrinstanzenfähige Microsoft Entra-App erstellen: Eine mehrinstanzenfähige Microsoft Entra-App hat Zugriff auf mehrere Kundenmandanten, wenn die Kunden ihre Einwilligung für die Partner-App explizit erteilt haben (im Schritt „Rollenzuweisung“ erläutert).

Partner können auf die APIs im Kundenmandanten zugreifen, indem sie die mehrinstanzenfähige Microsoft Entra-App verwenden, die in Microsoft Entra ID registriert ist. Die App-Registrierung erfolgt im Azure-Portal, sodass die Microsoft Identity Platform Authentifizierungs- und Autorisierungsdienste für Ihre Anwendung bereitstellen kann, die wiederum auf Data Manager for Agriculture zugreift.

Führen Sie die Schritte unter App-Registrierung bis Schritt 8 aus, um die folgenden Informationen zu generieren:

  1. Anwendungs-ID (Client)
  2. Verzeichnis-ID (Mandant)
  3. App-Name

Kopieren und speichern Sie alle drei Werte, da Sie sie zum Generieren von Zugriffstoken benötigen.

Die erstellte Anwendungs-ID (Client-ID) ist ähnlich der Benutzer-ID der Anwendung. Jetzt müssen Sie das entsprechende Anwendungskennwort (geheimer Clientschlüssel) erstellen, damit sich die Anwendung identifizieren kann.

Führen Sie die unter Hinzufügen eines geheimen Clientschlüssels beschriebenen Schritte aus, um einen geheimen Clientschlüssel zu generieren, und kopieren Sie den generierten geheimen Clientschlüssel.

Registrierung

Nachdem der Partner erfolgreich eine mehrinstanzenfähige Microsoft Entra-App erstellt hat, geben Partner die App-ID und Partner-ID manuell an das Data Manager for Agriculture-Team weiter, indem sie ein Supportticket erstellen. Mithilfe dieser Informationen überprüft Data Manager for Agriculture, ob es sich um einen authentischen Partner handelt und erstellt eine Partneridentität (sensorPartnerId) mithilfe der internen APIs. Im Rahmen des Registrierungsprozesses können Partner ihre Partner-ID (sensorPartnerId) beim Erstellen des Sensor-/Geräteobjekts verwenden und beim Übertragen von Sensordaten angeben.

Das Abrufen der Partner-ID markiert den Abschluss der Integration von Data Manager for Agriculture für Partner. Nun wartet der Partner auf Eingaben eines Sensorkunden, um die Datenerfassung in Data Manager for Agriculture zu initiieren.

Ablauf für Kunden

Kunden, die Data Manager for Agriculture verwenden, kennen alle unterstützten Sensorpartner und ihre jeweiligen App-IDs. Diese Informationen sind in der öffentlichen Dokumentation für alle unsere Kunden verfügbar. Je nach Sensoren, die Kunden verwenden, und der App-ID des jeweiligen Sensorpartners muss der Kunde dem Partner Zugriff gewähren (über die App-ID), um mit dem Übertragen von Sensordaten in seine Instanz von Data Manager for Agriculture zu beginnen. Die folgenden Schritte sind erforderlich:

Rollenzuweisung

Kunden, die sich für das Onboarding bei einem bestimmten Partner entscheiden, sollten über die App-ID dieses Partners verfügen. Unter Verwendung der App-ID muss der Kunde die folgenden Schritte nacheinander durchführen.

  1. Einwilligung: Da sich die Partner-App in einem anderen Mandanten befindet und der Kunde möchte, dass der Partner auf bestimmte APIs in seiner Instanz von Data Manager for Agriculture zugreifen kann, müssen Kunden einen bestimmten Endpunkt (https://login.microsoft.com/common/adminconsent/clientId=[client_id]) aufrufen und [client_id] durch die App-ID des Partners ersetzen. Auf diese Weise kann die Microsoft Entra ID-Instanz der Kunden diese App-ID erkennen, wann immer sie sie für die Rollenzuweisung verwenden.

  2. Identity & Access Management (IAM): Im Rahmen der Identitäts- und Zugriffsverwaltung erstellen Kunden eine neue Rollenzuweisung zur obigen App-ID, für die die Einwilligung erteilt wurde. Data Manager for Agriculture erstellt eine neue Rolle namens „Sensorpartner“ (zusätzlich zu den vorhandenen Rollen „Administrator“, „Mitwirkender“ und „Leser“). Kunden wählen die Rolle „Sensorpartner“, fügen die Partner-App-ID hinzu und gewähren Zugriff.

Auftakt

Der Kunde hat Data Manager for Agriculture mitgeteilt, dass Sensordaten von einem bestimmten Partner abgerufen werden müssen. Der Partner weiß jedoch noch nicht, für welchen Kunden die Sensordaten gesendet werden sollen. Daher würde der Kunde im nächsten Schritt die Integrations-API in Data Manager for Agriculture aufrufen, um einen Integrationslink zu generieren. Nach dem Erhalt des Integrationslinks würden Kunden nacheinander die folgenden Informationen teilen, entweder manuell oder über das Partnerportal.

  1. Einwilligungslink und Mandanten-ID: In diesem Schritt stellt der Kunde einen Einwilligungslink und eine Mandanten-ID bereit. Der Integrationslink sieht wie im Beispiel gezeigt aus:

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

    Zusätzlich zum Einwilligungslink würden Kunden auch eine Mandanten-ID angeben. Die Mandanten-ID wird verwendet, um das Zugriffstoken abzurufen, das zum Aufrufen des API-Endpunkts des Kunden erforderlich ist.

    Die Partner validieren den Einwilligungslink, indem sie einen GET-Aufruf an die API für die Einwilligungsprüfung durchführen. Durch den Link wird der Anforderungs-URI wie von Data Manager for Agriculture erwartet vollständig vorausgefüllt. Im Rahmen des GET-Aufrufs überprüfen die Partner, ob der Antwortcode „200 OK“ und „IntegrationId“ in der Antwort übergeben werden.

    Sobald die gültige Antwort empfangen wurde, müssen Partner zwei Informationen speichern:

    • API-Endpunkt (kann aus dem ersten Teil des Integrationslinks extrahiert werden)
    • IntegrationId (wird als Teil der Antwort auf den GET-Aufruf zurückgegeben)

    Sobald Partner diese Datenpunkte validieren und speichern, können sie es Kunden ermöglichen, Sensoren hinzuzufügen, für die die Daten in Data Manager for Agriculture übertragen werden müssen.

  2. Sensoren/Geräte hinzufügen: Jetzt weiß der Partner, mit welchem Kunden (API-Endpunkt) sie integriert werden müssen, aber immer noch nicht, für welche Sensoren die Daten übertragen werden müssen. Daher erfassen Partner die Sensor-/Geräteinformationen, für die die Daten übertragen werden müssen. Diese Daten können entweder manuell oder über die Portalbenutzeroberfläche gesammelt werden.

    Nach dem Hinzufügen der Sensoren/Geräte kann der Kunde damit rechnen, dass die jeweiligen Sensordaten in seine Data Manager for Agriculture-Instanz fließen. Dieser Schritt markiert den Abschluss des Kundenonboardings zum Abrufen von Sensordaten.

Ablauf für Partner: Phase 2

Der Partner verfügt jetzt über die Informationen zum Aufrufen eines bestimmten API-Endpunkts (Kundendatenebene), aber immer noch nicht über die Informationen darüber, wohin die Sensortelemetriedaten übertragen werden müssen.

Integration

Im Rahmen der Integration müssen Partner ihre eigene App-ID, das App-Geheimnis und die Mandanten-ID des Kunden verwenden, die während des App-Registrierungsschritts abgerufen wurden, um ein Zugriffstoken mithilfe der OAuth-API von Microsoft zu generieren. Hier sehen Sie den cURL-Befehl zum Generieren des Zugriffstokens:

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'

Die Antwort sollte in etwa wie folgt aussehen:

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

Mit dem generierten Zugriffstoken (access_token) rufen Partner den Endpunkt der Kundendatenebene auf, um Sensormodell, Sensor und Gerät zu erstellen. Es wird in dieser spezifischen Data Manager for Agriculture-Instanz mithilfe der APIs erstellt, die von Data Manager for Agriculture erstellt wurden. Weitere Informationen zu Partner-APIs finden Sie in der Partner-API-Dokumentation.

Mit der Sensorerstellungs-API stellen die Partner die Sensor-ID bereit. Sobald die Sensorressource erstellt wurde, rufen Partner die API zum Abrufen der Verbindungszeichenfolge auf, um eine Verbindungszeichenfolge für diesen Sensor abzurufen.

Übertragen von Daten

Erstellen der Sensorpartnerintegration

Erstellen Sie die Sensorpartnerintegration, um eine bestimmte Partei mit einem bestimmten Anbieter zu verbinden. Der IntegrationId-Wert wird später bei der Sensorerstellung verwendet. API-Dokumentation: Sensorpartnerintegrationen – Erstellen oder Aktualisieren

Erstellen eines Sensordatenmodells

Verwenden Sie das Sensordatenmodell, um das Modell der gesendeten Telemetriedaten zu definieren. Alle vom Sensor gesendeten Telemetriedaten werden gemäß diesem Datenmodell validiert.

API-Dokumentation: Sensordatenmodelle – Erstellen oder Aktualisieren

Beispieltelemetrie

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

Entsprechendes Sensordatenmodell

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

Erstellen des Sensors

Erstellen Sie einen Sensor mit der entsprechenden Integrations-ID und Sensordatenmodell-ID. DeviceId und HardwareId sind optionale Parameter. Falls erforderlich, können Sie die Geräte – Erstellen oder Aktualisieren verwenden, um das Gerät zu erstellen.

API-Dokumentation: Sensoren – Erstellen oder Aktualisieren

Abrufen der IoT Hub-Verbindungszeichenfolge

Rufen Sie die IoT Hub-Verbindungszeichenfolge ab, um Sensortelemetrie an die Plattform für den erstellten Sensor zu übertragen.

API-Dokumentation: Sensoren – Abrufen der Verbindungszeichenfolge

Übertragen von Daten mit IoT Hub

Verwenden Sie die IoT Hub-Geräte-SDKs, um die Telemetrie mithilfe der Verbindungszeichenfolge zu übertragen.

Für alle Sensortelemetrieereignisse ist „timestamp“ eine obligatorische Eigenschaft und muss im ISO 8601-Format (YYYY-MM-DDTHH:MM:SSZ) vorliegen.

Der Partner kann jetzt Sensordaten für alle Sensoren mit der jeweils für jeden Sensor bereitgestellten Verbindungszeichenfolge übertragen. Der Partner sendet jedoch die Sensordaten in einem JSON-Format, wie von FarmBeats definiert. Orientieren Sie sich am hier angegebenen Telemetrieschema.

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

Sobald die Daten an IoT Hub übertragen werden, können die Kunden Sensordaten mithilfe der Ausgangs-API abfragen.

Nächste Schritte

  • Testen Sie hier unsere APIs.