Przepływ integracji partnera czujników
W tym dokumencie omówiono kroki dołączania, które partner musi wykonać w celu integracji z usługą Data Manager for Agriculture. Przedstawia on omówienie interfejsów API używanych do tworzenia modeli i czujników listy, formatu telemetrii w celu wypychania danych, a na koniec pozyskiwania danych opartych na usłudze IOTHub.
Wprowadzanie
Dołączanie obejmuje kroki wymagane przez klientów i partnerów do integracji z menedżerem danych dla rolnictwa i odpowiednio rozpoczęcie odbierania/wysyłania danych telemetrycznych czujników.
Na powyższej ilustracji bloki wyróżnione w kolorze białym to kroki wykonywane przez partnera, a te wyróżnione na czarno są wykonywane przez klientów.
Przepływ partnera: faza 1
Oto zestaw kroków, które partner musi wykonać w celu integracji z usługą Data Manager for Agriculture. Jest to jednorazowa integracja. Na końcu fazy 1 partnerzy ustanowią swoją tożsamość w menedżerze danych dla rolnictwa.
Tworzenie aplikacji
Partnerzy muszą być uwierzytelniani i autoryzowani do uzyskiwania dostępu do interfejsów API płaszczyzny danych klienta usługi Data Manager for Agriculture. Dostęp do tych interfejsów API umożliwia partnerom tworzenie modeli czujników, czujników i obiektów urządzeń w ramach wystąpienia usługi Data Manager for Agriculture klienta. Informacje o obiekcie czujnika (utworzone przez partnera) są używane przez menedżera danych dla rolnictwa do tworzenia odpowiednich urządzeń (czujników) w usłudze IOTHub.
W związku z tym, aby włączyć uwierzytelnianie i autoryzację, partnerzy muszą wykonać następujące czynności
- Utwórz konto platformy Azure (jeśli jeszcze go nie utworzono).
- Tworzenie wielodostępnej aplikacji Firmy Microsoft Entra — wielodostępna aplikacja Firmy Microsoft Entra jest oznaczona jako nazwa, ma dostęp do dzierżaw wielu klientów, jeśli klienci wyrazili jawną zgodę na aplikację partnera (wyjaśniono w kroku przypisania roli).
Partnerzy mogą uzyskiwać dostęp do interfejsów API w dzierżawie klienta przy użyciu wielodostępnej aplikacji Microsoft Entra App zarejestrowanej w usłudze Microsoft Entra ID. Rejestracja aplikacji odbywa się w witrynie Azure Portal, dzięki czemu Platforma tożsamości Microsoft może zapewnić usługi uwierzytelniania i autoryzacji dla aplikacji, które z kolei uzyskują dostęp do usługi Data Manager for Agriculture.
Wykonaj kroki podane w sekcji Rejestracja aplikacji do kroku 8 , aby wygenerować następujące informacje:
- Identyfikator aplikacji (klienta)
- Identyfikator katalogu (dzierżawy)
- Nazwa aplikacji
Skopiuj i zapisz wszystkie trzy wartości, ponieważ będą potrzebne do generowania tokenu dostępu.
Utworzony identyfikator aplikacji (klienta) jest podobny do identyfikatora użytkownika aplikacji, a teraz musisz utworzyć odpowiednie hasło aplikacji (klucz tajny klienta), aby aplikacja mogła się zidentyfikować.
Wykonaj kroki podane w artykule Dodawanie wpisu tajnego klienta, aby wygenerować klucz tajny klienta i skopiować wygenerowany klucz tajny klienta.
Rejestracja
Po pomyślnym utworzeniu wielodostępnej aplikacji Firmy Microsoft Entra partnerzy ręcznie udostępniają identyfikator aplikacji i identyfikator partnera zespołowi Data Manager for Agriculture, tworząc bilet pomocy technicznej. Korzystając z tych informacji, menedżer danych dla rolnictwa sprawdza, czy jest to autentyczny partner i tworzy tożsamość partnera (sensorPartnerId) przy użyciu wewnętrznych interfejsów API. W ramach procesu rejestracji partnerzy są włączeni do korzystania z identyfikatora partnera (sensorPartnerId) podczas tworzenia obiektu czujnika/urządzeń, a także w ramach wypychanych danych czujników.
Uzyskanie identyfikatora partnera oznacza ukończenie integracji partner-Data Manager for Agriculture. Teraz partner czeka na dane wejściowe od dowolnego klienta czujnika, aby zainicjować pozyskiwanie danych do usługi Data Manager for Agriculture.
Przepływ klienta
Klienci korzystający z usługi Data Manager for Agriculture będą świadomi wszystkich obsługiwanych partnerów czujników i odpowiednich identyfikatorów aplikacji. Te informacje są dostępne w publicznej dokumentacji dla wszystkich naszych klientów. Na podstawie czujników używanych przez klientów i identyfikatora APLIKACJI partnera czujników klient musi zapewnić dostęp do partnera (identyfikatora APLIKACJI), aby rozpocząć wypychanie danych czujnika do wystąpienia menedżera danych dla rolnictwa. Poniżej przedstawiono wymagane kroki:
Przypisanie roli
Klienci, którzy zdecydują się dołączyć do określonego partnera, powinni mieć identyfikator aplikacji tego konkretnego partnera. Za pomocą identyfikatora aplikacji klient musi wykonać następujące czynności w sekwencji.
Zgoda — ponieważ aplikacja partnera znajduje się w innej dzierżawie, a klient chce, aby partner uzyskiwał dostęp do niektórych interfejsów API w swoim wystąpieniu Menedżera danych dla rolnictwa, klienci muszą wywołać określony punkt końcowy
https://login.microsoft.com/common/adminconsent/clientId=[client_id]i zastąpić wartość [client_id] identyfikatorem aplikacji partnera. Dzięki temu identyfikator entra firmy Microsoft klienta może rozpoznać ten identyfikator aplikacji za każdym razem, gdy będą używać go do przypisania roli.Zarządzanie dostępem do tożsamości ( IAM) — w ramach zarządzania dostępem do tożsamości klienci tworzą nowe przypisanie roli do powyższego identyfikatora aplikacji, który udzielił zgody. Menedżer danych dla rolnictwa tworzy nową rolę o nazwie Partner czujnika (oprócz istniejących ról Administrator, Współautor, Czytelnik). Klienci wybierają rolę partnera czujnika i dodaj identyfikator aplikacji partnera i zapewniają dostęp.
Inicjacja
Klient uświadomił menedżerowi danych dla rolnictwa, że musi uzyskać dane z czujników od określonego partnera. Jednak partner nie wie jeszcze, dla którego klienta powinien wysłać dane czujnika. W związku z tym w następnym kroku klient wywoła interfejs API integracji w narzędziu Data Manager for Agriculture w celu wygenerowania linku integracji. Po uzyskaniu linku integracji klienci będą udostępniać poniższe informacje w sekwencji, ręcznie udostępniając lub korzystając z portalu partnera.
Link zgody i identyfikator dzierżawy — w tym kroku klient udostępnia link zgody i identyfikator dzierżawy. Link integracji wygląda następująco:
fb-resource-name.farmbeats.com/sensor-partners/partnerId/integrations/IntegrationId/:check-consent?key=jgtHTFGDR?api-version=2021-07-31-previewOprócz linku zgody klienci również podać identyfikator dzierżawy. Identyfikator dzierżawy służy do pobierania tokenu dostępu wymaganego do wywołania punktu końcowego interfejsu API klienta.
Partnerzy weryfikują link zgody, wykonując wywołanie GET w interfejsie API linku sprawdzania zgody. Ponieważ link jest w pełni wypełniony identyfikator URI żądania zgodnie z oczekiwaniami menedżera danych dla rolnictwa. W ramach wywołania GET partnerzy sprawdzają kod odpowiedzi 200 OK i identyfikator IntegrationId, który ma zostać przekazany w odpowiedzi.
Po odebraniu prawidłowej odpowiedzi partnerzy muszą przechowywać dwa zestawy informacji
- Punkt końcowy interfejsu API (można wyodrębnić z pierwszej części linku integracji)
- IntegrationId (jest zwracany jako część odpowiedzi na wywołanie GET)
Gdy partner weryfikuje i przechowuje te punkty danych, może umożliwić klientom dodawanie czujników, dla których dane muszą zostać wypchnięte do menedżera danych dla rolnictwa.
Dodaj czujniki/urządzenia — teraz partner wie, z którym klientem (punktem końcowym interfejsu API) musi się zintegrować, jednak nadal nie wiedzą, z którymi wszystkimi czujnikami muszą wypchnąć dane. W związku z tym partnerzy zbierają informacje o czujniku/urządzeniu, dla których należy wypchnąć dane. Te dane można zbierać ręcznie lub za pośrednictwem interfejsu użytkownika portalu.
Po dodaniu czujników/urządzeń klient może oczekiwać przepływu danych odpowiednich czujników do wystąpienia usługi Data Manager for Agriculture. Ten krok oznacza ukończenie dołączania klienta w celu pobrania danych z czujników.
Przepływ partnera: faza 2
Partner ma teraz informacje dotyczące wywoływania określonego punktu końcowego interfejsu API (płaszczyzny danych klientów), ale nadal nie mają informacji na temat tego, gdzie muszą wypchnąć dane telemetryczne czujnika?
Integracja
W ramach integracji partnerzy muszą używać własnego identyfikatora aplikacji, klucza tajnego aplikacji i identyfikatora dzierżawy klienta uzyskanego podczas kroku rejestracji aplikacji, aby wygenerować token dostępu przy użyciu interfejsu API oAuth firmy Microsoft. Oto polecenie curl w celu wygenerowania tokenu dostępu
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'
Odpowiedź powinna wyglądać następująco:
{
"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"
}
Po wygenerowaniu access_token partnerzy nazywają punkt końcowy płaszczyzny danych klientów, aby utworzyć model czujnika, czujnik i urządzenie. Jest on tworzony w tym konkretnym wystąpieniu menedżera danych dla rolnictwa przy użyciu interfejsów API utworzonych przez menedżera danych dla rolnictwa. Aby uzyskać więcej informacji na temat interfejsów API partnerów, zapoznaj się z dokumentacją interfejsu API partnera.
W ramach interfejsu API tworzenia czujnika partnerzy dostarczają identyfikator czujnika, po utworzeniu zasobu czujnika partnerzy wywołają interfejs API pobierania parametry połączenia, aby uzyskać parametry połączenia dla tego czujnika.
Wypychanie danych
Tworzenie integracji partnera czujników
Utwórz integrację partnera czujników, aby połączyć określoną firmę z określonym dostawcą. Identyfikator integrationId jest później używany podczas tworzenia czujnika. Dokumentacja interfejsu API: Integracja partnerów czujników — tworzenie lub aktualizowanie
Tworzenie modelu danych czujnika
Użyj modelu danych czujnika, aby zdefiniować model wysyłanych danych telemetrycznych. Wszystkie dane telemetryczne wysyłane przez czujnik są weryfikowane zgodnie z tym modelem danych.
Dokumentacja interfejsu API: Modele danych czujników — tworzenie lub aktualizowanie
Przykładowa telemetria
{
"pressure": 30.45,
"temperature": 28,
"name": "sensor-1"
}
Odpowiedni model danych czujnika
{
"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
}
}
Tworzenie czujnika
Utwórz czujnik przy użyciu odpowiedniego identyfikatora integracji i identyfikatora modelu danych czujnika. DeviceId i HardwareId są opcjonalnymi parametrami, w razie potrzeby można użyć pozycji Urządzenia — utwórz lub zaktualizuj , aby utworzyć urządzenie.
Dokumentacja interfejsu API: Czujniki — tworzenie lub aktualizowanie
Pobieranie parametry połączenia usługi IoTHub
Pobierz parametry połączenia IoTHub, aby wypchnąć dane telemetryczne czujnika do platformy utworzonej przez czujnik.
Dokumentacja interfejsu API: Czujniki — uzyskiwanie parametrów połączenia
Wypychanie danych przy użyciu usługi IoT Hub
Użyj zestawów SDK urządzeń usługi IoT Hub, aby wypchnąć dane telemetryczne przy użyciu parametry połączenia.
W przypadku wszystkich zdarzeń telemetrii czujnika "sygnatura czasowa" jest obowiązkową właściwością i musi być w formacie ISO 8601 (RRRR-MM-DDTHH:MM:SSZ).
Partner jest teraz ustawiony, aby rozpocząć wypychanie danych czujników dla wszystkich czujników przy użyciu odpowiednich parametry połączenia dostarczonych dla każdego czujnika. Jednak partner wysyła dane czujnika w formacie JSON zdefiniowanym przez usługę FarmBeats. Zapoznaj się ze schematem telemetrii podanym tutaj.
{
"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
}
Po wypchnięciu danych do usługi IOTHub klienci będą mogli wykonywać zapytania dotyczące danych z czujników przy użyciu interfejsu API ruchu wychodzącego.
Następne kroki
- Przetestuj nasze interfejsy API tutaj.