Integracja z partnerami obsługującymi czujniki

Ten artykuł zawiera informacje o składniku Azure FarmBeats Translator, który umożliwia integrację partnerów czujników.

Ważne

Azure FarmBeats zostanie wycofana. Publiczne ogłoszenie można zobaczyć tutaj.

Utworzyliśmy nową usługę skoncentrowaną na rolnictwie, jej nazwa to Azure Data Manager for Agriculture i jest teraz dostępna jako usługa w wersji zapoznawczej. Aby uzyskać więcej informacji, zobacz publiczną dokumentację tutaj lub napisz do nas pod adresem madma@microsoft.com.

Korzystając z tego składnika, partnerzy mogą integrować się z usługą FarmBeats przy użyciu interfejsów API usługi DataHub FarmBeats i wysyłać dane telemetryczne urządzenia klienta do usługi FarmBeats Datahub. Gdy dane są dostępne w usłudze FarmBeats, są wizualizowane przy użyciu akceleratora FarmBeats i mogą być używane do łączenia danych oraz do tworzenia modeli uczenia maszynowego/sztucznej inteligencji.

Przed rozpoczęciem

Aby opracować składnik translatora, potrzebne będą następujące poświadczenia, które umożliwią dostęp do interfejsów API FarmBeats.

• Punkt końcowy interfejsu API
• Identyfikator dzierżawy
• Identyfikator klienta
• Klucz tajny klienta
• Parametry połączenia usługi EventHub

Zapoznaj się z tą sekcją, aby uzyskać powyższe poświadczenia: Włączanie integracji urządzenia

Programowanie w usłudze Translator

Integracja oparta na interfejsie API REST

Funkcje integracji danych z czujnikami usługi FarmBeats są udostępniane za pośrednictwem interfejsu API REST. Możliwości obejmują definicję metadanych, aprowizację urządzenia i czujnika oraz zarządzanie urządzeniami i czujnikami.

Pozyskiwanie danych telemetrycznych

Dane telemetryczne są mapowane na wiadomość kanoniczną opublikowaną na Azure Event Hubs na potrzeby przetwarzania. Azure Event Hubs to usługa, która umożliwia pozyskiwanie danych w czasie rzeczywistym (telemetrii) z połączonych urządzeń i aplikacji.

Programowanie interfejsu API

Interfejsy API zawierają dokumentację techniczną struktury Swagger.

Authentication

Usługa FarmBeats używa uwierzytelniania Microsoft Entra. Azure App Service zapewnia wbudowaną obsługę uwierzytelniania i autoryzacji.

Aby uzyskać więcej informacji, zobacz Tożsamość Microsoft Entra.

Usługa FarmBeats Datahub używa uwierzytelniania elementu nośnego, które wymaga następujących poświadczeń:

• Identyfikator klienta
• Klucz tajny klienta
• Identyfikator dzierżawy

Przy użyciu tych poświadczeń obiekt wywołujący może zażądać tokenu dostępu. Token musi zostać wysłany w kolejnych żądaniach interfejsu API w sekcji nagłówka w następujący sposób:

headers = {"Authorization": "Bearer " + access_token, …} 

Poniższy przykładowy kod w języku Python udostępnia token dostępu, który może być używany do kolejnych wywołań interfejsu API do aplikacji FarmBeats.

import requests
import json
import msal

# Your service principal App ID
CLIENT_ID = "<CLIENT_ID>"
# Your service principal password
CLIENT_SECRET = "<CLIENT_SECRET>"
# Tenant ID for your Azure subscription
TENANT_ID = "<TENANT_ID>"

AUTHORITY_HOST = 'https://login.microsoftonline.com'
AUTHORITY = AUTHORITY_HOST + '/' + TENANT_ID

ENDPOINT = "https://<yourfarmbeatswebsitename-api>.azurewebsites.net"
SCOPE = ENDPOINT + "/.default"

context = msal.ConfidentialClientApplication(CLIENT_ID, authority=AUTHORITY, client_credential=CLIENT_SECRET)
token_response = context.acquire_token_for_client(SCOPE)
# We should get an access token here
access_token = token_response.get('access_token')

Nagłówki żądań HTTP

Poniżej przedstawiono najbardziej typowe nagłówki żądań, które należy określić podczas wykonywania wywołania interfejsu API do usługi FarmBeats Datahub.

Nagłówek	Opis i przykład
Content-Type	Format żądania (typ zawartości: application/<format>). W przypadku interfejsów API usługi FarmBeats Datahub format to JSON. Typ zawartości: application/json
Autoryzacja	Określa token dostępu wymagany do wywołania interfejsu API. Autoryzacja: token dostępu elementu <nośnego>
Zaakceptuj	Format odpowiedzi. W przypadku interfejsów API usługi FarmBeats Datahub format to JSON. Zaakceptuj: application/json

Żądania interfejsu API

Aby utworzyć żądanie interfejsu API REST, połączysz metodę HTTP (GET, POST lub PUT), adres URL usługi API, identyfikator URI (Uniform Resource Identifier) do zasobu w celu wykonywania zapytań, przesyłania danych do, aktualizowania lub usuwania oraz co najmniej jednego nagłówka żądania HTTP. Adres URL usługi interfejsu API to punkt końcowy interfejsu API, który podajesz. Oto przykład: https://\<yourdatahub-website-name>.azurewebsites.net

Opcjonalnie możesz uwzględnić parametry zapytania w wywołaniach GET w celu filtrowania, ograniczania rozmiaru i sortowania danych w odpowiedziach.

Następujące przykładowe żądanie polega na pobraniu listy urządzeń.

curl -X GET "https://microsoft-farmbeats.azurewebsites.net/Device" -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>"

Większość wywołań GET, POST i PUT wymaga treści żądania JSON.

Następujące przykładowe żądanie polega na utworzeniu urządzenia. (Ten przykład zawiera wejściowy kod JSON z treścią żądania).

curl -X POST "https://microsoft-farmbeats.azurewebsites.net/Device" -H  "accept: application/json" -H  "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>" -d "{  \"deviceModelId\": \"ID123\",  \"hardwareId\": \"MHDN123\",  \"reportingInterval\": 900,  \"name\": \"Device123\",  \"description\": \"Test Device 123\",}"

Format danych

JSON to wspólny format danych niezależnych od języka, który zapewnia prostą reprezentację tekstową dowolnych struktur danych. Aby uzyskać więcej informacji, zobacz json.org.

Specyfikacje metadanych

Usługa FarmBeats Datahub ma następujące interfejsy API, które umożliwiają partnerom urządzeń tworzenie metadanych urządzenia lub czujników i zarządzanie nimi.

• /DeviceModel: Model urządzenia odpowiada metadanym urządzenia, takim jak producent i typ urządzenia, który jest bramą lub węzłem.

• /Urządzenie: urządzenie odpowiada urządzeniu fizycznemu obecnemu w farmie.

• /SensorModel: Model SensorModel odpowiada metadanym czujnika, takim jak producent, typ czujnika, który jest analogowy lub cyfrowy, oraz pomiar czujnika, taki jak temperatura otoczenia i ciśnienie.

• /Czujnik: Czujnik odpowiada czujnikowi fizycznemu, który rejestruje wartości. Czujnik jest zwykle połączony z urządzeniem z identyfikatorem urządzenia.

  DeviceModel	Opis
  Typ (węzeł, brama)	Typ urządzenia — węzeł lub brama
  Producent	Nazwa producenta
  Kod_produktu	Kod produktu urządzenia lub nazwa modelu lub numer. Na przykład EnviroMonitor#6800.
  Porty	Nazwa i typ portu, który jest cyfrowy lub analogowy.
  Nazwa	Nazwa identyfikującego zasób. Na przykład nazwa modelu lub nazwa produktu.
  Opis	Podaj opis modelu.
  Właściwości	Dodatkowe właściwości od producenta.
  Urządzenie	Opis
  DeviceModelId	Identyfikator skojarzonego modelu urządzenia.
  Identyfikator sprzętu	Unikatowy identyfikator urządzenia, taki jak adres MAC.
  RaportowanieInterval	Interwał raportowania w sekundach.
  Lokalizacja	Szerokość geograficzna urządzenia (od-90 do +90), długość geograficzna (od-180 do 180) i wysokość (w metrach).
  ParentDeviceId	Identyfikator urządzenia nadrzędnego, z którym jest połączone to urządzenie. Jeśli na przykład węzeł jest połączony z bramą, węzeł ma element parentDeviceID jako bramę.
  Nazwa	Nazwa identyfikującego zasób. Partnerzy urządzeń muszą wysłać nazwę zgodną z nazwą urządzenia po stronie partnera urządzeń. Jeśli nazwa urządzenia jest zdefiniowana przez użytkownika po stronie partnera urządzeń, ta sama nazwa zdefiniowana przez użytkownika powinna zostać rozpropagowana do farmbeats.
  Opis	Podaj opis opisowy.
  Właściwości	Dodatkowe właściwości od producenta.
  SensorModel	Opis
  Typ (analogowy, cyfrowy)	Podaj czujnik analogowy lub cyfrowy.
  Producent	Nazwa producenta.
  Kod_produktu	Kod produktu lub nazwa modelu lub numer. Na przykład RS-CO2-N01.
  Nazwa sensorMeasures >	Nazwa miary czujnika. Obsługiwane są tylko małe litery. W przypadku pomiarów z różnych głębokości określ głębokość. Na przykład soil_moisture_15cm. Ta nazwa musi być zgodna z danymi telemetrycznymi.
  SensorMeasures > DataType	Typ danych telemetrycznych. Obecnie funkcja double jest obsługiwana.
  Typ sensorMeasures >	Typ pomiaru danych telemetrycznych czujnika. Poniżej przedstawiono zdefiniowane przez system typy: AmbientTemperature, CO2, Głębokość, ElectricalConductivity, LeafWetness, Length, LiquidLevel, Separator, O2, PH, Phos, PointInTime, Potas, Ciśnienie, RainGauge, RelativeHumidity, Zasolenie, GlebaMoisture, GlebaTemperature, SolarRadiation, State, TimeDuration, UVRadiation, UVIndex, Volume, WindDirection, WindRun, WindSpeed, Evapotranspiration, PAR. Aby dodać więcej, zapoznaj się z interfejsem API /ExtendedType.
  Jednostka SensorMeasures >	Jednostka danych telemetrycznych czujników. Poniżej przedstawiono zdefiniowane przez system jednostki: NoUnit, Celsjusza, Fahrenheit, Kelvin, Rankine, Pascal, Mercury, PSI, MilliMeter, CentiMeter, Meter, Inch, Feet, Mile, KiloMeter, MilesPerHour, MilesPerSecond, KMPerHour, KMPerSecond, MeterPerHour, MetersPerSecond, Degree, WattsPerSquareMeter, KiloWattsPerSquareMeter, MilliWattsPerSquareCentiMeter, MilliJoulesPerSquareCentiMeter, VolumetricWaterContent, Percentage, PartsPerMillion, MicroMol, MicroMolPerLiter, SiemensPerSquareMeterPerMole, MilliSiemensPerCentiMeter, Centibar, DeciSiemensPerMeter, KiloPascal, VolumetricIonContent, Liter, MilliLiter, Seconds, UnixTimestamp, MicroMolPerMeterSquaredPerSecond i InchesPerHour. Aby dodać więcej, zapoznaj się z interfejsem API /ExtendedType.
  SensorMeasures > AggregationType	Brak, średnia, maksymalna, minimalna lub StandardowaDeviation.
  Głębokość czujnika >	Głębokość czujnika w centymetrach. Na przykład pomiar wilgoci 10 cm pod ziemią.
  Opis sensorMeasures >	Podaj opis miary.
  Nazwa	Nazwa identyfikującego zasób. Na przykład nazwa modelu lub nazwa produktu.
  Opis	Podaj opis modelu.
  Właściwości	Dodatkowe właściwości od producenta.
  Czujnik	Opis
  Identyfikator sprzętu	Unikatowy identyfikator czujnika ustawionego przez producenta.
  SensorModelId	Identyfikator skojarzonego modelu czujnika.
  Lokalizacja	Szerokość geograficzna czujnika (od-90 do +90), długość geograficzna (od-180 do 180) i wysokość (w metrach).
  Nazwa portu >	Nazwa i typ portu, z którymi jest podłączony czujnik na urządzeniu. Musi to być taka sama nazwa jak zdefiniowana w modelu urządzenia.
  DeviceId	Identyfikator urządzenia, z którymi jest połączony czujnik.
  Nazwa	Nazwa identyfikującego zasób. Na przykład nazwa czujnika lub nazwa produktu oraz numer modelu lub kod produktu.
  Opis	Podaj opis opisowy.
  Właściwości	Dodatkowe właściwości od producenta.

Uwaga

Interfejsy API zwracają unikatowe identyfikatory dla każdego utworzonego wystąpienia. Ten identyfikator musi zostać zachowany przez usługę Translator na potrzeby zarządzania urządzeniami i synchronizacji metadanych.

Synchronizacja metadanych

Translator powinien wysyłać aktualizacje metadanych. Na przykład scenariusze aktualizacji to zmiana nazwy urządzenia lub czujnika oraz zmiana lokalizacji urządzenia lub czujnika.

Translator powinien mieć możliwość dodawania nowych urządzeń lub czujników zainstalowanych przez użytkownika po połączeniu aplikacji FarmBeats. Podobnie, jeśli użytkownik zaktualizował urządzenie lub czujnik, to samo powinno zostać zaktualizowane w obszarze FarmBeats dla odpowiedniego urządzenia lub czujnika. Typowe scenariusze wymagające aktualizacji urządzenia lub czujnika to zmiana lokalizacji urządzenia lub dodanie czujników w węźle.

Uwaga

Usuwanie nie jest obsługiwane w przypadku metadanych urządzenia ani czujnika.

Aby zaktualizować metadane, należy wywołać polecenie /Get/{id} na urządzeniu lub czujniku, zaktualizować zmienione właściwości, a następnie wykonać polecenie /Put/{id}, aby wszystkie właściwości ustawione przez użytkownika nie zostały utracone.

Dodawanie nowych typów i jednostek

Usługa FarmBeats obsługuje dodawanie nowych typów i jednostek miar czujników.

Specyfikacje telemetrii

Dane telemetryczne są mapowane na wiadomość kanoniczną opublikowaną na Azure Event Hubs na potrzeby przetwarzania. Azure Event Hubs to usługa, która umożliwia pozyskiwanie danych w czasie rzeczywistym (telemetrii) z połączonych urządzeń i aplikacji.

Wysyłanie danych telemetrycznych do usługi FarmBeats

Aby wysyłać dane telemetryczne do usługi FarmBeats, utwórz klienta wysyłającego komunikaty do centrum zdarzeń w usłudze FarmBeats. Aby uzyskać więcej informacji na temat danych telemetrycznych, zobacz Wysyłanie danych telemetrycznych do centrum zdarzeń.

Oto przykładowy kod w języku Python, który wysyła dane telemetryczne jako klienta do określonego centrum zdarzeń.

import azure
from azure.eventhub import EventHubClient, Sender, EventData, Receiver, Offset
EVENTHUBCONNECTIONSTRING = "<EventHub Connection String provided by customer>"
EVENTHUBNAME = "<EventHub Name provided by customer>"

write_client = EventHubClient.from_connection_string(EVENTHUBCONNECTIONSTRING, eventhub=EVENTHUBNAME, debug=False)
sender = write_client.add_sender(partition="0")
write_client.run()
for i in range(5):
    telemetry = "<Canonical Telemetry message>"
    print("Sending telemetry: " + telemetry)
    sender.send(EventData(telemetry))
write_client.stop()

Format wiadomości kanonicznej jest następujący:

{
"deviceid": "<id of the Device created>",
"timestamp": "<timestamp in ISO 8601 format>",
"version" : "1",
"sensors": [
    {
      "id": "<id of the sensor created>",
      "sensordata": [
        {
          "timestamp": "< timestamp in ISO 8601 format >",
          "<sensor measure name (as defined in the Sensor Model)>": <value>
        },
        {
          "timestamp": "<timestamp in ISO 8601 format>",
          "<sensor measure name (as defined in the Sensor Model)>": <value>
        }
      ]
    }
 ]
}

Wszystkie nazwy kluczy w formacie JSON telemetrii powinny mieć małe litery. Przykłady to deviceid i sensordata.

Oto na przykład komunikat telemetrii:

{
  "deviceid": "7f9b4b92-ba45-4a1d-a6ae-c6eda3a5bd12",
  "timestamp": "2019-06-22T06:55:02.7279559Z",
  "version" : "1",
  "sensors": [
    {
      "id": "d8e7beb4-72de-4eed-9e00-45e09043a0b3",
      "sensordata": [
        {
          "timestamp": "2019-06-22T06:55:02.7279559Z",
          "hum_max": 15
        },
        {
          "timestamp": "2019-06-22T06:55:02.7279559Z",
          "hum_min": 42
        }
      ]
    },
    {
      "id": "d8e7beb4-72de-4eed-9e00-45e09043a0b3",
      "sensordata": [
        {
          "timestamp": "2019-06-22T06:55:02.7279559Z",
          "hum_max": 20
        },
        {
          "timestamp": "2019-06-22T06:55:02.7279559Z",
          "hum_min": 89
        }
      ]
    }
  ]
}

Uwaga

Poniższe sekcje są związane z innymi zmianami (np. Interfejs użytkownika, zarządzanie błędami itp.) partner czujnika może odwoływać się do opracowywania składnika usługi Translator.

Łączenie konta FarmBeats

Po zakupie i wdrożeniu urządzeń lub czujników klienci mogą uzyskiwać dostęp do danych i danych telemetrycznych urządzenia w portalu oprogramowania jako usługi (SaaS) partnerów urządzeń. Partnerzy urządzeń mogą umożliwić klientom łączenie swojego konta z wystąpieniem farmBeats na platformie Azure, zapewniając sposób wprowadzania następujących poświadczeń:

• Nazwa wyświetlana (opcjonalne pole dla użytkowników definiujące nazwę dla tej integracji)
• Punkt końcowy interfejsu API
• Identyfikator dzierżawy
• Identyfikator klienta
• Klucz tajny klienta
• EventHub parametry połączenia
• Data rozpoczęcia

Uwaga

Data rozpoczęcia umożliwia historyczne źródło danych, czyli dane z daty określonej przez użytkownika.

Odłącz farmębeats

Partnerzy urządzeń mogą umożliwić klientom odłączenie istniejącej integracji programu FarmBeats. Odłączanie elementu FarmBeats nie powinno usuwać żadnych metadanych urządzenia ani czujnika utworzonych w usłudze FarmBeats Datahub. Odłączanie wykonuje następujące czynności:

• Zatrzymuje przepływ telemetrii.
• Usuwa i usuwa poświadczenia integracji u partnera urządzeń.

Edytowanie integracji z usługą FarmBeats

Partnerzy urządzeń mogą umożliwić klientom edytowanie ustawień integracji FarmBeats, jeśli klucz tajny klienta lub parametry połączenia zmiany. W takim przypadku można edytować tylko następujące pola:

• Nazwa wyświetlana (jeśli dotyczy)
• Klucz tajny klienta (powinien być wyświetlany w formacie "2x8***********" lub funkcji Pokaż/Ukryj, a nie w postaci zwykłego tekstu)
• Parametry połączenia (powinny być wyświetlane w formacie "2x8***********" lub funkcji Pokaż/Ukryj, a nie w postaci zwykłego tekstu)

Wyświetlanie ostatniej wysłanej telemetrii

Partnerzy urządzeń mogą umożliwić klientom wyświetlanie znacznika czasu ostatniej wysłanej telemetrii, która znajduje się w obszarze Wysłane dane telemetryczne. Jest to czas, w którym najnowsze dane telemetryczne zostały pomyślnie wysłane do usługi FarmBeats.

Rozwiązywanie problemów i zarządzanie błędami

Rozwiązywanie problemów z opcją lub pomocą techniczną

Jeśli klient nie może odbierać danych urządzenia lub telemetrii w określonym wystąpieniu farmbeats, partner urządzenia powinien zapewnić pomoc techniczną i mechanizm rozwiązywania problemów.

Przechowywanie danych telemetrycznych

Dane telemetryczne powinny być również przechowywane przez wstępnie zdefiniowany okres czasu, dzięki czemu mogą być przydatne podczas debugowania lub ponownego wysyłanie danych telemetrycznych w przypadku wystąpienia błędu lub utraty danych.

Zarządzanie błędami lub powiadomienie o błędzie

Jeśli błąd dotyczy metadanych urządzenia lub czujnika albo integracji danych lub przepływu danych telemetrycznych w systemie partnerskim urządzeń, klient powinien otrzymać powiadomienie. Należy również zaprojektować i zaimplementować mechanizm rozwiązywania wszelkich błędów.

Lista kontrolna połączenia

Producenci urządzeń lub partnerzy mogą użyć następującej listy kontrolnej, aby upewnić się, że poświadczenia podane przez klienta są dokładne:

• Sprawdź, czy token dostępu został odebrany przy użyciu podanych poświadczeń.
• Sprawdź, czy wywołanie interfejsu API powiedzie się z odebranym tokenem dostępu.
• Sprawdź, czy połączenie klienta usługi EventHub zostało nawiązane.

Następne kroki

Aby uzyskać więcej informacji na temat interfejsu API REST, zobacz INTERFEJS API REST.