Share via

Érzékelőpartnerek integrációs folyamata

  • Cikk

Ez a dokumentum azokról a bevezetési lépésekről szól, amelyeket a partnernek meg kell tennie a Data Manager for Agriculture integrálásához. Áttekintést nyújt a modellek és listaérzékelők létrehozásához használt API-król, az adatok leküldéséhez használt telemetriai formátumról és végül az IOTHub-alapú adatbetöltésről.

Onboarding

Az előkészítés ismerteti azokat a lépéseket, amelyeket mindkét ügyfél és partner megkövetel a Data Manager for Agriculture integrálásához és az érzékelő telemetriai adatainak fogadásához/küldéséhez.

Screenshot showing sensor partners flow.

A fenti ábrán a fehér színnel kiemelt blokkok a partner által végrehajtott lépések, a fekete színnel kiemelteket pedig az ügyfelek végzik.

Partnerfolyamat: 1. fázis

Az alábbiakban bemutatjuk azokat a lépéseket, amelyeket a partnernek el kell végeznie a Data Manager for Agriculture integrálásához. Ez egy egyszeri integráció. Az 1. fázis végén a partnerek létrehozzák identitásukat a Data Manager for Agriculture szolgáltatásban.

Alkalmazás létrehozása

A partnereket hitelesíteni kell és engedélyezni kell a Data Manager for Agriculture ügyfelei adatsík API-iihoz való hozzáféréshez. Ezeknek az API-knak a elérése lehetővé teszi a partnerek számára, hogy érzékelőmodelleket, érzékelőket és eszközobjektumokat hozzanak létre az ügyfelek Data Manager for Agriculture-példányában. A Data Manager for Agriculture a megfelelő eszközök (érzékelők) IOTHubon való létrehozásához használja a (partner által létrehozott) érzékelőobjektum-információkat.

Ezért a hitelesítés és engedélyezés engedélyezéséhez a partnereknek az alábbiakat kell elvégeznie

  1. Azure-fiók létrehozása (ha még nem hozott létre egyet.)
  2. Több-bérlős Microsoft Entra-alkalmazás létrehozása – A több-bérlős Microsoft Entra alkalmazás, ahogy a név jelzi, több ügyfél bérlőjéhez is hozzáfér, ha az ügyfelek kifejezett hozzájárulást adtak a partneralkalmazáshoz (ezt a szerepkör-hozzárendelési lépés ismerteti).

A partnerek a Microsoft Entra ID-ban regisztrált több-bérlős Microsoft Entra alkalmazással férhetnek hozzá az ügyfélbérlelő API-khoz. Az alkalmazásregisztráció az Azure Portalon történik, így a Microsoft Identitásplatform hitelesítési és engedélyezési szolgáltatásokat biztosíthat az alkalmazás számára, amelyek viszont hozzáférnek a Data Manager for Agriculture szolgáltatáshoz.

Kövesse az alkalmazásregisztrációban megadott lépéseket a 8. lépésig az alábbi információk létrehozásához:

  1. Alkalmazás (ügyfél) azonosítója
  2. Címtár (bérlő) azonosítója
  3. Alkalmazás neve

Másolja és tárolja mind a három értéket, ahogy szüksége lenne rájuk a hozzáférési jogkivonat létrehozásához.

A létrehozott alkalmazás -(ügyfél-) azonosító az alkalmazás felhasználói azonosítójára hasonlít, és most létre kell hoznia a megfelelő alkalmazásjelszót (ügyfélkulcsot) az alkalmazás azonosításához.

Kövesse az Ügyfélkód hozzáadása és a létrehozott titkos ügyfélkód másolása című témakörben leírt lépéseket.

Nyilvántartás

Miután a partner sikeresen létrehozott egy több-bérlős Microsoft Entra-alkalmazást, a partnerek manuálisan megosztják az alkalmazásazonosítót és a partnerazonosítót a Data Manager for Agriculture szolgáltatással az alias elküldésével madma@microsoft.com . A Data Manager for Agriculture ezen információk használatával ellenőrzi, hogy hiteles partner-e, és a belső API-k használatával létrehoz egy partneridentitást (sensorPartnerId). A regisztrációs folyamat részeként a partnerek használhatják a partnerazonosítójukat (sensorPartnerId) az érzékelő/eszközök objektumának létrehozásakor, valamint a leküldéses érzékelőadatok részeként.

A partnerazonosító lekérése a partner-Data Manager for Agriculture integráció befejezését jelzi. A partner most bármelyik érzékelőügyfelétől várja a bemenetet, hogy elindítsa az adatbetöltést a Data Manager for Agriculture szolgáltatásba.

Ügyfélfolyamat

A Data Manager for Agriculture szolgáltatást használó ügyfelek tisztában lesznek az összes támogatott érzékelőpartnerrel és azok alkalmazásazonosítóival. Ez az információ minden ügyfelünk számára elérhető a nyilvános dokumentációban. Az ügyfelek által használt érzékelők és a megfelelő érzékelőpartner alkalmazásazonosítója alapján az ügyfélnek hozzáférést kell biztosítania a partnerhez (APP ID), hogy megkezdhesse az érzékelőadatok leküldését a Data Manager for Agriculture-példányba. Íme a szükséges lépések:

Szerepkör-hozzárendelés

Azoknak az ügyfeleknek, akik egy adott partnerhez kívánnak csatlakozni, rendelkezniük kell az adott partner alkalmazásazonosítójával. Az alkalmazásazonosítót használó ügyfélnek a következő műveleteket kell elvégeznie egymás után.

  1. Hozzájárulás – Mivel a partner alkalmazása egy másik bérlőben található, és az ügyfél azt szeretné, hogy a partner hozzáférjen bizonyos API-khoz a Data Manager for Agriculture-példányban, az ügyfeleknek meg kell hívniuk egy adott végpontot https://login.microsoft.com/common/adminconsent/clientId=[client_id] , és le kell cserélniük a [client_id]-t a partnerek alkalmazásazonosítójára. Ez lehetővé teszi, hogy az ügyfelek Microsoft Entra-azonosítója felismerje ezt az alkalmazásazonosítót, amikor szerepkör-hozzárendeléshez használják.

  2. Identitáshozzáférés-kezelés (IAM) – Az identitáshozzáférés-kezelés részeként az ügyfelek létrehoznak egy új szerepkör-hozzárendelést a fenti alkalmazásazonosítóhoz, amelyhez hozzájárulást adtak. A Data Manager for Agriculture létrehoz egy érzékelőpartner nevű új szerepkört (a meglévő Rendszergazda, közreműködői és olvasói szerepkörök mellett). Az ügyfelek kiválasztják az érzékelőpartneri szerepkört, hozzáadják a partneralkalmazás azonosítóját, és hozzáférést biztosítanak.

Kezdeményezése

Az ügyfél tudatta a Data Manager for Agriculture szolgáltatással, hogy érzékelőadatokat kell lekérnie egy adott partnertől. A partner azonban még nem tudja, hogy melyik ügyfélnek küldje el az érzékelő adatait. Ezért a következő lépésben az ügyfél integrálási API-t hívna meg a Data Manager for Agriculture szolgáltatáson belül egy integrációs hivatkozás létrehozásához. Az integrációs hivatkozás beszerzését követően az ügyfelek egymás után osztják meg az alábbi információkat, akár manuálisan, akár a partner portálján.

  1. Hozzájárulási hivatkozás > Bérlőazonosító – Ebben a lépésben az ügyfél egy hozzájárulási hivatkozást & bérlőazonosítót ad meg. Az integrációs hivatkozás a példában látható módon jelenik meg:

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

    A hozzájárulási hivatkozáson kívül az ügyfelek egy bérlőazonosítót is megadnak. A bérlőazonosító az ügyfél API-végpontjába való behíváshoz szükséges hozzáférési jogkivonat lekérésére szolgál.

    A partnerek get hívással érvényesítik a hozzájárulási hivatkozást az ellenőrző hozzájárulási hivatkozás API-ján. Mivel a hivatkozás teljes mértékben előre fel van töltve, a Data Manager for Agriculture által elvárt URI-kérés. A GET hívás részeként a partnerek ellenőrzik, hogy a válaszban egy 200 OK-válaszkód és integrationId szerepel-e.

    Az érvényes válasz beérkezése után a partnereknek két információkészletet kell tárolniuk

    • API-végpont (az integrációs hivatkozás első részéből nyerhető ki)
    • IntegrationId (a GET hívásra adott válasz részeként lesz visszaadva)

    Miután a partner érvényesíti és tárolja ezeket az adatpontokat, lehetővé teszik az ügyfelek számára, hogy érzékelőket adjanak hozzá, amelyekhez az adatokat le kell küldeni a Data Manager for Agriculture szolgáltatásba.

  2. Érzékelők/eszközök hozzáadása – A partner most már tudja, hogy melyik ügyfélhez (API-végponthoz) kell integrálnia, de még mindig nem tudja, hogy melyik érzékelőhöz kell leküldnie az adatokat. Ezért a partnerek összegyűjtik azokat az érzékelő- és eszközinformációkat, amelyekhez le kell küldeni az adatokat. Ezek az adatok manuálisan vagy a portál felhasználói felületén keresztül gyűjthetők.

    Az érzékelők/eszközök hozzáadása után az ügyfél számíthat a megfelelő érzékelők adatfolyamára a Data Manager for Agriculture-példányba. Ez a lépés jelzi az ügyfél előkészítésének befejezését az érzékelőadatok lekéréséhez.

Partnerfolyamat: 2. fázis

A partner most már rendelkezik egy adott API-végpont meghívásához szükséges információkkal (az ügyfelek adatsíkjával), de még mindig nem rendelkezik azokkal az információkkal, hogy hol kell leküldniük az érzékelő telemetriai adatait?

Integration

Az integráció részeként a partnereknek az alkalmazásregisztrációs lépés során beszerzett saját alkalmazásazonosítójukat, az alkalmazás titkos kódját és az ügyfél bérlőazonosítóját kell használniuk ahhoz, hogy hozzáférési jogkivonatot hozhassanak létre a Microsoft oAuth API-jával. Az alábbi curl-parancs a hozzáférési jogkivonat létrehozásához

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'

A válasznak így kell kinéznie:

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

A létrehozott access_token a partnerek meghívják az ügyfelek adatsík-végpontját az érzékelőmodell, az érzékelő és az eszköz létrehozásához. Ebben az adott Data Manager for Agriculture-példányban jön létre a Data Manager for Agriculture által létrehozott API-k használatával. A partnerek API-ival kapcsolatos további információkért tekintse meg a partner API dokumentációját.

Az érzékelőlétrehozás API részeként a partnerek megadják az érzékelő azonosítóját, miután létrejött az érzékelőerőforrás, a partnerek betárcsáznak a get kapcsolati sztring API-ba, hogy lekérjenek egy kapcsolati sztring az érzékelőhöz.

Adatok leküldése

Érzékelőpartner-integráció létrehozása

Érzékelőpartner-integráció létrehozása egy adott fél és egy adott szolgáltató összekapcsolásához. Az integrációs azonosítót később az érzékelő létrehozásakor használják. API-dokumentáció: Érzékelőpartner-integrációk – Létrehozás vagy frissítés

Érzékelő adatmodelljének létrehozása

Az elküldött telemetriai modell meghatározásához használjon érzékelőadat-modellt. Az érzékelő által küldött összes telemetriát az adatmodellnek megfelelően ellenőrzi a rendszer.

API-dokumentáció: Érzékelő adatmodelljei – Létrehozás vagy frissítés

Mintatelemetria

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

Megfelelő érzékelőadat-modell

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

Érzékelő létrehozása

Hozzon létre érzékelőt a megfelelő integrációs azonosító és az érzékelő adatmodell-azonosítójával. A DeviceId és a HardwareId opcionális paraméterek, ha szükséges, az Eszközök – Létrehozás vagy frissítés használatával hozhatja létre az eszközt.

API-dokumentáció: Érzékelők – Létrehozás vagy frissítés

IoTHub-kapcsolati sztring lekérése

Kérje le az IoTHub kapcsolati sztring, hogy leküldje az érzékelő telemetriáját a létrehozott érzékelő platformjához.

API-dokumentáció: Érzékelők – Csatlakozás ion-sztring lekérése

Adatok leküldése az IoT Hub használatával

Az IoT Hub Device SDK-k használatával küldje le a telemetriát a kapcsolati sztring használatával.

Minden érzékelőtelemetria-esemény esetében az "időbélyeg" kötelező tulajdonság, amelynek ISO 8601 formátumban kell lennie (YYYY-MM-DDTHH:MM:SSZ).

A partner most már minden érzékelő érzékelőadatainak leküldésére van beállítva az egyes érzékelőkhöz megadott megfelelő kapcsolati sztring használatával. A partner azonban a FarmBeats által meghatározott JSON formátumban küldi el az érzékelőadatokat. Tekintse meg az itt megadott telemetriai sémát.

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

Miután leküldte az adatokat az IOTHubra, az ügyfelek le tudják kérdezni az érzékelő adatait a kimenő API használatával.

További lépések

  • Itt tesztelje az API-kat.