Share via

Integrationsfluss für Sensorpartner

  • Artikel

In diesem Dokument werden die Onboarding-Schritte erläutert, die ein Partner für die Integration in Data Manager for Agriculture ausführen muss. Es zeigt eine Übersicht über die APIs, die zum Erstellen von Modellen und Listensensor, Telemetrieformat zum Pushen der Daten und schließlich zur IOTHub-basierten Datenaufnahme verwendet werden.

Onboarding

Onboarding deckt die Schritte ab, die von Kunden und Partnern benötigt werden, um mit Data Manager für Landwirtschaft zu integrieren und sensorischer Telemetrie zu empfangen bzw. zu senden.

Screenshot showing sensor partners flow.

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

Partnerfluss: Phase 1

Im Folgenden finden Sie die Schritte, die ein Partner für die Integration mit Data Manager for Agriculture ausführen muss. Dies ist eine einmalige Integration. Am Ende der Phase 1 etablieren Partner ihre Identität im Data Manager for Agriculture.

App-Erstellung

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

Um die Authentifizierung und Autorisierung zu aktivieren, müssen Partner die folgenden Schritte ausführen:

  1. Erstellen Sie ein Azure-Konto (Wenn Sie noch kein Konto erstellt haben.)
  2. Erstellen Sie eine Microsoft Entra-App mit mehreren Mandanten – Die Microsoft Entra-App mit mehreren Mandanten, die als Name bezeichnet wird, hat Zugriff auf die Mandanten mehrerer Kunden, wenn die Kunden der Partner-App explizit zugestimmt haben (im Schritt zur Rollenzuweisung erläutert).

Partner können auf die APIs im Kundenmandanten zugreifen, indem sie die microsoft Entra-App mit mehreren Mandanten verwenden, die in der Microsoft Entra-ID registriert sind. Die App-Registrierung erfolgt auf dem Azure-Portal, sodass die Microsoft Identity Platform Authentifizierungs- und Autorisierungsdienste für Ihre Anwendung bereitstellen kann, die wiederum auf Den Data Manager for Agriculture zugreift.

Führen Sie die in der App-Registrierungangegebenen Schritte aus, bis Schritt 8 die folgenden Informationen generiert werden:

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

Kopieren Und speichern Sie alle drei Werte, wie 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 Microsoft Entra-App mit mehreren Mandanten erstellt hat, geben Partner die APP-ID und Die Partner-ID manuell mit Data Manager for Agriculture per E-Mail-Alias madma@microsoft.com frei. Die Verwendung dieser Informationen vom Data Manager für Landwirtschaft überprüft, ob es sich um einen authentischen Partner handelt und mithilfe der internen APIs eine Partneridentität (sensorPartnerId) erstellt. Im Rahmen des Registrierungsprozesses können Partner ihre Partner-ID (sensorPartnerId) beim Erstellen des Sensor-/Geräteobjekts und auch als Teil der von ihnen übertragenen Sensordaten verwenden.

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

Ablauf für Kunden

Kunden, die Data Manager für Landwirtschaft verwenden, werden alle unterstützten Sensorpartner und ihre jeweiligen APP-IDs kennen. Diese Informationen sind in der öffentlichen Dokumentation für alle unsere Kunden verfügbar. Basierend auf den Sensoren, die Kunden verwenden, und der APP-ID des jeweiligen Sensorpartners muss der Kunde Zugriff auf den Partner (APP-ID) gewähren, um mit dem Pushen ihrer Sensordaten in ihre Data Manager for Agriculture-Instanz zu beginnen. Hier sind die erforderlichen Schritte:

Rollenzuweisung

Kunden, die sich für das Onboarding in einen bestimmten Partner entscheiden, sollten über die App-ID dieses bestimmten Partners verfügen. Die Verwendung der App-ID muss der Kunde die folgenden Schritte in Folge ausführen.

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

  2. Identity Access Management (IAM) – Kunden erstellen im Rahmen der Identitätszugriffsverwaltung eine neue Rollenzuweisung zur oben genannten App-ID, die ihre Zustimmung erteilt hat. Data Manager for Agriculture erstellt eine neue Rolle namens Sensorpartner (zusätzlich zu den vorhandenen Administrator-, Mitwirkenden-, Leser-Rollen). Kunden wählen die Sensorpartnerrolle und fügen die Partner-App-ID hinzu und bieten Zugriff.

Auftakt

Der Kunde hat Data Manager für Landwirtschaft bewusst gemacht, dass er Sensordaten von einem bestimmten Partner abrufen muss. Der Partner weiß jedoch noch nicht, für welchen Kunden die Sensordaten gesendet werden sollen. Daher würde der Kunde als nächster Schritt die Integrations-API in Data Manager for Agriculture aufrufen, um einen Integrationslink zu generieren. Nach dem Erwerb des Integrationslinks würden Kunden die folgenden Informationen in Sequenz teilen, entweder manuell freigeben oder das Portal des Partners verwenden.

  1. Zustimmungslink & Mandanten-ID – In diesem Schritt stellt der Kunde einen Zustimmungslink 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 Zustimmungslink 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 überprüfen den Zustimmungslink, indem sie einen GET-Aufruf für die API für die Zustimmungsprüfung durchführen. Da die Verknüpfung vollständig ausgefüllt ist, wird der Anforderungs-URI wie erwartet vom Data Manager für Landwirtschaft erwartet. 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 Informationssätze speichern.

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

    Sobald partner diese Datenpunkte überprüft und speichert, 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. Hinzufügen von Sensoren/Geräten – Jetzt weiß der Partner, mit welchem Kunden (API-Endpunkt) er integriert werden muss, aber sie wissen immer noch nicht, für welche Sensoren sie die Daten pushen 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 Portal-UI gesammelt werden.

    Nach dem Hinzufügen der Sensoren/Geräte kann der Kunde den Datenfluss der jeweiligen Sensoren in seine Data Manager for Agriculture-Instanz erwarten. Dieser Schritt markiert den Abschluss des Kunden-Onboardings zum Abrufen von Sensordaten.

Partnerfluss: Phase 2

Partner verfügt jetzt über die Informationen zum Aufrufen eines bestimmten API-Endpunkts (Datenebene von Kunden), aber sie verfügen immer noch nicht über die Informationen darüber, wo sie die Sensor-Telemetriedaten pushen müssen?

Integration

Im Rahmen der Integration müssen Partner ihre eigene App-ID, die App-Geheimnis und die Mandanten-ID des Kunden verwenden, die während des App-Registrierungsschritts erworben 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 access_token rufen Partner den Datenebenenendpunkt des Kunden 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.

Im Rahmen der Sensorerstellungs-API stellen die Partner die Sensor-ID bereit, sobald die Sensorressource erstellt wurde, rufen Partner die get Verbindungszeichenfolge-API auf, um eine Verbindungszeichenfolge für diesen Sensor zu erhalten.

Übertragen von Daten

Erstellen der Sensorpartnerintegration

Erstellen Sie die Sensorpartnerintegration, um eine bestimmte Partei mit einem bestimmten Anbieter zu verbinden. Die integrationId 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 Telemetrie zu definieren. Alle vom Sensor gesendeten Telemetriedaten werden gemäß diesem Datenmodell überprüft.

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

Sensor erstellen

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 verwenden – Erstellen oder Aktualisieren , um das Gerät zu erstellen.

API-Dokumentation: Sensoren – Erstellen oder Aktualisieren

IoTHub-Verbindungszeichenfolge abrufen

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

API-Dokumentation: Sensoren – abrufen Verbinden ion-Zeichenfolge

Pushdaten mit IoT Hub

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

Für alle Sensor-Telemetrieereignisse ist "Timestamp" eine obligatorische Eigenschaft und muss im ISO 8601-Format (JJJJ-MM-DDTHH:MM:SSZ) vorliegen.

Partner ist jetzt alle so eingestellt, dass sensordaten für alle Sensoren mit den jeweils für jeden Sensor bereitgestellten Verbindungszeichenfolge pushen. Der Partner sendet jedoch die Sensordaten in einem JSON-Format, wie von FarmBeats definiert. Weitere Informationen finden Sie im hier bereitgestellten 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 IOTHub übertragen werden, können die Kunden Sensordaten mithilfe der Ausgangs-API abfragen.

Nächste Schritte

  • Testen Sie hier unsere APIs.