Flux d’intégration de partenaire de capteur

Article
05/28/2024

Ce document décrit les étapes d’intégration qu’un partenaire doit suivre pour s’intégrer à Data Manager for Agriculture. Il présente une vue d’ensemble des API utilisées pour créer des modèles et des capteurs de liste, le format de télémétrie pour envoyer (push) les données, et enfin l’ingestion de données basée sur IOTHub.

Intégration

L’intégration couvre les étapes requises à la fois par les clients et les partenaires pour s’intégrer à Data Manager for Agriculture et commencer respectivement à recevoir et envoyer des données de télémétrie de capteur.

Capture d’écran montrant le flux des partenaires de capteur.

Dans la figure ci-dessus, les blocs mis en évidence en blanc sont les étapes effectuées par un partenaire, et celles en noir sont effectuées par les clients.

Flux de partenaire : Phase 1

Voici l’ensemble des étapes que doit effectuer un partenaire pour l’intégration à Data Manager for Agriculture. Il s’agit d’une intégration ponctuelle. À la fin de la phase 1, les partenaires établissent leur identité dans Data Manager for Agriculture.

Création d’application

Les partenaires doivent être authentifiés et autorisés afin d’accéder aux API de plan de données des clients Data Manager for Agriculture. L’accès à ces API permet aux partenaires de créer des modèles de capteur, et des objets capteur et appareil au sein de l’instance Data Manager for Agriculture des clients. Les informations sur les objets capteur (créées par le partenaire) sont utilisées par Data Manager for Agriculture pour créer les appareils (capteurs) correspondants dans IOTHub.

Par conséquent, pour activer l’authentification et l’autorisation, les partenaires doivent effectuer les opérations suivantes :

Créer un compte Azure (si vous n’en avez pas).
Créer une application Microsoft Entra multilocataire : l’application Microsoft Entra multilocataire, comme son nom l’indique, a accès aux locataires de plusieurs clients, si les clients ont donné un consentement explicite à l’application partenaire (ceci est expliqué à l’étape d’attribution de rôle).

Les partenaires peuvent accéder aux API dans le locataire client à l’aide de l’application Microsoft Entra multilocataire, inscrite dans Microsoft Entra ID. L’inscription d’application s’effectue dans le portail Azure, afin que la plateforme d’identités Microsoft puisse fournir des services d’authentification et d’autorisation à votre application, qui à son tour accède à Data Manager for Agriculture.

Suivez les étapes fournies dans Inscription d’applicationjusqu’à l’étape 8 pour générer les informations suivantes :

ID d’application (client)
ID de l’annuaire (locataire)
Nom de l’application

Copiez et stockez les trois valeurs, car vous en aurez besoin pour générer un jeton d’accès.

L’ID d’application (client) créé est semblable à l’ID utilisateur de l’application, et vous devez maintenant créer son mot de passe d’application correspondant (clé secrète client) pour que l’application s’identifie.

Suivez les étapes fournies dans Ajouter une clé secrète client pour générer la Clé secrète client et copiez la clé secrète client générée.

Inscription

Une fois que le partenaire a créé une application Microsoft Entra multilocataire, les partenaires partagent manuellement l’ID d’application et l’ID de partenaire avec l’équipe Data Manager for Agriculture en créant un ticket de support. À l’aide de ces informations, Data Manager for Agriculture valide s’il s’agit d’un partenaire authentique et crée une identité partenaire (sensorPartnerId) à l’aide des API internes. Dans le cadre du processus d’inscription, les partenaires sont autorisés à utiliser leur ID partenaire (sensorPartnerId) lors de la création de l’objet capteur/appareil, ainsi que dans le cadre des données de capteur qu’ils envoient.

L’obtention de l’ID de partenaire marque l’achèvement de l’intégration du partenaire à Data Manager for Agriculture. À présent, le partenaire attend l’entrée de l’un de ses clients de capteur pour lancer son ingestion de données dans Data Manager for Agriculture.

Flux du client

Les clients qui utilisent Data Manager for Agriculture auront connaissance de tous les partenaires de capteur pris en charge et de leurs ID d’application respectifs. Ces informations sont accessibles à tous nos clients dans la documentation publique. En fonction des capteurs utilisés par les clients et de leur ID d’application de partenaire de capteur respectif, le client doit fournir l’accès au partenaire (ID d’application) afin qu’il commence à envoyer (push) ses données de capteur dans son instance Data Manager for Agriculture. Voici les étapes à suivre :

Attribution de rôle

Les clients qui choisissent de s’intégrer à un partenaire spécifique doivent avoir l’ID d’application de ce partenaire spécifique. À l’aide de l’ID d’application, le client doit effectuer les opérations suivantes dans l’ordre indiqué.

Consentement : étant donné que l’application du partenaire réside dans un autre locataire et que le client souhaite que le partenaire accède à certaines API dans son instance Data Manager for Agriculture, le client doit appeler un point de terminaison spécifique https://login.microsoft.com/common/adminconsent/clientId=[client_id] et remplacer le [client_id] par l’ID d’application du partenaire. Cela permet à l’environnement Microsoft Entra ID du client de reconnaître cet ID d’application chaque fois qu’il l’utilise pour l’attribution de rôle.
Gestion des identités et des accès (IAM) : dans le cadre de la gestion des identités et des accès, les clients créent une attribution de rôle pour l’ID d’application ci-dessus, qui a reçu le consentement. Data Manager for Agriculture crée un rôle appelé Partenaire de capteur (en plus des rôles Administrateur, Contributeur et Lecteur existants). Les clients choisissent le rôle de partenaire de capteur, ajoutent l’ID d’application partenaire et fournissent l’accès.

Initiation

Le client a fait savoir à Data Manager for Agriculture qu’il doit obtenir des données de capteur auprès d’un partenaire spécifique. Toutefois, le partenaire ne sait pas encore pour quel client il doit envoyer les données de capteur. Par conséquent, l’étape suivante consiste pour le client à appeler l’API d’intégration dans Data Manager for Agriculture afin de générer un lien d’intégration. Après l’acquisition du lien d’intégration, les clients partagent les informations ci-dessous dans l’ordre, soit manuellement, soit à l’aide du portail du partenaire.

Lien de consentement et ID de locataire : lors de cette étape, le client fournit un lien de consentement et un ID de locataire. Voici un exemple de lien d’intégration :

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

En plus du lien de consentement, les clients fournissent également un ID de locataire. L’ID de locataire est utilisé pour extraire le jeton d’accès requis pour appeler le point de terminaison d’API du client.

Les partenaires valident le lien de consentement en effectuant un appel GET sur l’API de vérification du lien de consentement. Le lien est entièrement prérenseigné. Dans le cadre de l’appel GET, les partenaires recherchent un code de réponse 200 OK et l’IntegrationId à transmettre dans la réponse.

Une fois la réponse valide reçue, les partenaires doivent stocker deux ensembles d’informations.
- Point de terminaison d’API (peut être extrait de la première partie du lien d’intégration)
- IntegrationId (est retourné dans le cadre de la réponse à l’appel GET)
Une fois que le partenaire a validé et stocké ces points de données, il peut permettre aux clients d’ajouter des capteurs pour lesquels les données doivent être envoyées dans Data Manager for Agriculture.
Ajouter des capteurs/appareils : à présent, le partenaire sait avec quel client (point de terminaison d’API) il doit s’intégrer, mais il ne sait toujours pas pour quels capteurs il doit envoyer les données. Par conséquent, le partenaire collecte les informations de capteur/appareil pour lesquelles les données doivent être envoyées. Ces données peuvent être collectées manuellement ou via l’interface utilisateur du portail.

Après l’ajout des capteurs/appareils, le client peut s’attendre à ce que les données des capteurs correspondants soient transmises à son instance Data Manager for Agriculture. Cette étape marque l’achèvement de l’intégration du client pour extraire les données de capteur.

Flux de partenaire : Phase 2

Le partenaire dispose désormais des informations permettant d’appeler un point de terminaison d’API spécifique (plan de données du client), mais il n’a toujours pas les informations indiquant où il doit envoyer les données de télémétrie de capteur.

Intégration

Dans le cadre de l’intégration, le partenaire doit utiliser son propre ID d’application, secret d’application et ID de locataire du client acquis pendant l’étape d’inscription de l’application pour générer un jeton d’accès à l’aide de l’API oAuth de Microsoft. Voici la commande curl pour générer le jeton d’accès :

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 réponse doit ressembler à ce qui suit :

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

L’access_token étant généré, le partenaire appelle le point de terminaison du plan de données du client pour créer un modèle de capteur, un capteur et un appareil. Il est créé dans cette instance spécifique de Data Manager for Agriculture à l’aide des API créées par Data Manager for Agriculture. Pour plus d’informations sur les API partenaires, consultez la documentation sur les API partenaires.

Dans le cadre de l’API de création de capteur, le partenaire fournit l’ID de capteur. Une fois la ressource de capteur créée, le partenaire appelle l’API d’obtention de chaîne de connexion afin d’obtenir une chaîne de connexion pour ce capteur.

Effectuer une transmission des données de type push

Créer une intégration de partenaire de capteur

Créez une intégration de partenaire de capteur pour connecter un tiers particulier à un fournisseur spécifique. L’integrationId est utilisé ultérieurement lors de la création de capteur. Documentation d’API : Intégrations des partenaires de capteur – Créer ou mettre à jour

Créer un modèle de données de capteur

Utilisez le modèle de données de capteur pour définir le modèle de télémétrie envoyée. Toute la télémétrie envoyée par le capteur est validée conformément à ce modèle de données.

Documentation d’API : Modèles de données de capteur – Créer ou mettre à jour

Exemple de télémétrie

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

Modèle de données de capteur correspondant

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

Créer un capteur

Créez un capteur à l’aide de l’ID d’intégration et de l’ID de modèle de données de capteur correspondants. DeviceId et HardwareId sont des paramètres facultatifs. Si nécessaire, vous pouvez utiliser Appareils – Créer ou mettre à jour pour créer l’appareil.

Documentation d’API : Capteurs – Créer ou mettre à jour

Obtenir la chaîne de connexion IoTHub

Obtenez la chaîne de connexion IoTHub pour envoyer la télémétrie de capteur à la plateforme pour le capteur créé.

Documentation d’API : Capteurs – Obtenir la chaîne de connexion

Envoyer des données à l’aide d’IoT Hub

Utilisez les kits SDK d’appareil IoT Hub pour envoyer la télémétrie à l’aide de la chaîne de connexion.

Pour tous les événements de télémétrie de capteur, « timestamp » est une propriété obligatoire qui doit être au format ISO 8601 (AAAA-MM-JJTHH:MM:SSZ).

Le partenaire est maintenant prêt à commencer à envoyer des données de capteur pour tous les capteurs à l’aide de la chaîne de connexion correspondante fournie pour chaque capteur. Toutefois, le partenaire enverra les données de capteur dans un format JSON tel que défini par FarmBeats. Reportez-vous au schéma de télémétrie fourni ici.

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

Une fois les données envoyées à IOTHub, le client peut interroger les données de capteur à l’aide de l’API de sortie.

Étapes suivantes

Testez nos API ici.

Partage via

Flux d’intégration de partenaire de capteur

Intégration

Flux de partenaire : Phase 1

Création d’application

Inscription

Flux du client

Attribution de rôle

Initiation

Flux de partenaire : Phase 2

Intégration

Effectuer une transmission des données de type push

Créer une intégration de partenaire de capteur

Créer un modèle de données de capteur

Créer un capteur

Obtenir la chaîne de connexion IoTHub

Envoyer des données à l’aide d’IoT Hub

Étapes suivantes

Ressources supplémentaires