Udostępnij za pośrednictwem

Przepływ integracji partnerów sensoró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 omówienie interfejsów API używanych do tworzenia modeli i wymieniania czujników, formatu telemetrii dla przesyłania danych oraz na koniec pozyskiwania danych z użyciem IOTHub.

Wprowadzanie

Wdrażanie obejmuje kroki wymagane przez klientów i partnerów do integracji z Menedżerem Danych dla Rolnictwa i odpowiednio rozpoczęcie odbierania/nadawania danych telemetrycznych z czujników.

Zrzut ekranu przedstawiający przepływ partnerów 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ą zostać uwierzytelnieni i autoryzowani do uzyskania dostępu do interfejsów API płaszczyzny danych klientów 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 instancji Data Manager dla Rolnictwa 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

  1. Utwórz konto platformy Azure (jeśli jeszcze go nie utworzono).
  2. Stwórz wielodostępną aplikację Microsoft Entra — Wielodostępna aplikacja Microsoft Entra, zgodnie z nazwą, ma dostęp do wielu dzierżaw klientów, jeśli klienci wyrazili jawną zgodę na aplikację partnera (jak wyjaśniono w kroku przypisania roli).

Partnerzy mogą uzyskiwać dostęp do interfejsów API w dzierżawie klienta, korzystając z wielotenancyjnej aplikacji Microsoft Entra App zarejestrowanej w 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 Rejestracjaaplikacji do kroku 8 , aby wygenerować następujące informacje:

  1. Identyfikator aplikacji (klienta)
  2. Identyfikator katalogu (klienta)
  3. 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 Dodaj sekret klienta, aby wygenerować sekret klienta i skopiować wygenerowany sekret.

Rejestracja

Po pomyślnym utworzeniu wielodostępnej aplikacji Microsoft Entra partnerzy ręcznie udostępniają zespołowi Data Manager for Agriculture identyfikator aplikacji i identyfikator partnera, tworząc zgłoszenie do 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 mogą używać swojego identyfikatora partnera (sensorPartnerId) podczas tworzenia obiektu czujnika lub urządzeń, a także w ramach danych czujników, które wysyłają.

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 partnerowi (identyfikator aplikacji), aby rozpocząć przesyłanie danych czujników do instancji zarządzania danymi 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.

  1. Zgoda — ponieważ aplikacja partnera znajduje się w innym tenancie, a klient chce umożliwić partnerowi dostęp do określonych API w swoim wystąpieniu Data Manager for Agriculture, klienci muszą wykonać żądanie do określonego punktu końcowego https://login.microsoft.com/common/adminconsent/clientId=[client_id] i zastąpić [client_id] identyfikatorem aplikacji partnera. Dzięki temu identyfikator Microsoft Entra klienta może rozpoznać ten identyfikator aplikacji za każdym razem, gdy go używa do przypisania roli.

  2. 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, dla której udzielono zgody. Menedżer danych dla rolnictwa tworzy nową rolę o nazwie Partner sensora (oprócz istniejących ról Administrator, Współautor, Czytelnik). Klienci wybierają rolę partnera czujnika, 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 Data Manager for Agriculture, aby wygenerować link do 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.

  1. Link zgody i identyfikator najemcy — w tym kroku klient udostępnia link zgody i identyfikator najemcy. 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-preview

    Oprócz linku zgody, klienci również musieliby podać identyfikator dzierżawcy. Identyfikator dzierżawy jest używany do pobierania tokenu dostępu, który jest wymagany do wywołania punktu końcowego API klienta.

    Partnerzy weryfikują link zgody, wykonując wywołanie GET w API do sprawdzania zgody. Ponieważ link jest w pełni wypełniony zgodnie z oczekiwaniami Menedżera Danych ds. Rolnictwa, identyfikator URI żądania jest prawidłowy. 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 API (można wyodrębnić z pierwszej części łącza integracji)
    • IntegrationId (jest zwracany jako część odpowiedzi na wywołanie GET)

    Gdy partner zweryfikuje i przechowa te punkty danych, może umożliwić klientom dodawanie czujników, których dane muszą zostać przesłane do Menedżera Danych dla Rolnictwa.

  2. 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 tym jak klient doda czujniki/urządzenia, może oczekiwać przepływu danych z tych czujników do instancji Data Manager for Agriculture. Ten krok oznacza zakończenie onboardingu klienta w celu zdobycia 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 oraz identyfikatora dzierżawy klienta, które uzyskali podczas kroku rejestracji aplikacji, aby wygenerować token dostępu przy użyciu oAuth API 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 wywołują endpoint płaszczyzny danych klientów, aby stworzyć 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łują interfejs API uzyskiwania ciągu połączenia, aby otrzymać ciąg połączenia dla tego czujnika.

Przesyłanie danych

Opracowanie 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 API: Czujniki — Pobierz ciąg połączenia

Wysyłanie danych za pomocą IoT Hub

Użyj IoT Hub Device SDKs do przekazywania danych telemetrycznych przy użyciu ciągu połączenia.

Dla wszystkich zdarzeń telemetrii czujnika "znacznik czasu" jest obowiązkową właściwością i musi być w formacie zgodnym z ISO 8601 (RRRR-MM-DDTHH:MM:SSZ).

Partner jest teraz gotowy do przesyłania danych ze wszystkich czujników, używając odpowiednich parametrów połączenia dostarczonych dla każdego z nich. 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 przesłaniu danych do IOTHub klienci będą mogli zapytać o dane z czujników za pomocą interfejsu API egress.

Następne kroki