Integrasi mitra cuaca dengan FarmBeats

Artikel
11/29/2023

Artikel ini menyediakan informasi tentang komponen Azure FarmBeats Connector Docker. Sebagai penyedia data cuaca, Anda dapat menggunakan Connector Docker untuk berintegrasi dengan FarmBeats. Gunakan API-nya untuk mengirim data cuaca ke FarmBeats. Di FarmBeats, data dapat digunakan untuk fusi data dan untuk membangun model pembelajaran mesin atau model kecerdasan buatan.

Penting

Azure FarmBeats dihentikan. Anda dapat melihat pengumuman publik di sini.

Kami telah membangun layanan berfokus pada pertanian baru, namanya Adalah Azure Data Manager untuk Pertanian dan sekarang tersedia sebagai layanan pratinjau. Untuk informasi selengkapnya, lihat dokumentasi publik di sini atau tulis kepada kami di madma@microsoft.com.

Anda harus menyediakan gambar atau program Docker yang sesuai dan meng-hosting gambar docker dalam registri kontainer yang dapat diakses pelanggan. Berikan informasi berikut kepada pelanggan Anda:

URL gambar Docker
Tag gambar Docker
Kunci atau kredensial untuk mengakses gambar Docker
Kunci atau kredensial API khusus pelanggan untuk mengakses data dari sistem Anda
Detail VM SKU (Berikan detail ini jika gambar Docker Anda memiliki persyaratan VM tertentu. Jika tidak, pelanggan dapat memilih dari SKU VM yang didukung di Azure.)

Pelanggan menggunakan informasi Docker ini untuk mendaftarkan mitra cuaca dalam instans FarmBeats mereka. Untuk informasi selengkapnya tentang bagaimana pelanggan dapat menggunakan Docker untuk memasukkan data cuaca di FarmBeats, lihat Mengumpulkan data dari mitra cuaca.

Pengembangan Connector Docker

Integrasi berbasis REST API

API FarmBeats berisi dokumentasi teknis Swagger.

Jika Anda sudah menginstal FarmBeats, akses FarmBeats Swagger Anda di https://yourfarmbeatswebsitename-api.azurewebsites.net/swagger

Perhatikan bahwa -api ditambahkan ke nama situs web FarmBeats Anda. Titik akhir API adalah https://yourfarmbeatswebsitename-api.azurewebsites.net

Pustaka Datahub

FarmBeats menyediakan pustaka yang dapat Anda gunakan. Pustaka saat ini tersedia sebagai bagian dari implementasi referensi. Nantinya, SDK akan tersedia dalam beberapa bahasa.

Autentikasi

Autentikasi dengan API FarmBeats

FarmBeats menggunakan autentikasi pembawa. Anda dapat mengakses API dengan memberikan token akses di bagian header permintaan. Berikut contohnya:

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

Anda dapat meminta token akses dari aplikasi Azure Functions yang berjalan pada instans FarmBeats pelanggan. URL Azure Functions disediakan untuk program Docker sebagai argumen. Anda bisa mendapatkan token akses dengan membuat GET permintaan di URL. Respons dari URL berisi token akses.

Gunakan fungsi pembantu di lib Datahub untuk mendapatkan token akses. Untuk informasi selengkapnya, lihat halaman GitHub untuk gambar NOAA Docker.

Token akses hanya berlaku selama beberapa jam. Ketika kedaluwarsa, Anda harus memintanya lagi.

Autentikasi dengan API pihak mitra

Untuk mengautentikasi API pihak mitra saat pekerjaan Docker berjalan, pelanggan perlu memberikan kredensial selama pendaftaran mitra. Berikut contohnya:

{
 "partnerCredentials": {
   "key1": "value1",
   "key2": "value2"
   }
}

Layanan API menserialisasikan kamus ini dan menyimpannya di brankas kunci.

Azure Data Factory digunakan untuk mengatur pekerjaan cuaca. Azure Data Factory memutar sumber daya untuk menjalankan kode Docker. Data Factory juga menyediakan mekanisme untuk mendorong data dengan aman ke VM tempat pekerjaan Docker berjalan. Info masuk API lalu disimpan dengan aman di brankas kunci.

Info masuk dibaca sebagai string aman dari brankas kunci. Brankas kunci disediakan sebagai properti yang diperluas di direktori kerja kontainer Docker. Jalur filenya adalah /mnt/working_dir/activity.json.

Kode Docker dapat membaca info masuk dari activity.json selama durasi untuk mengakses API pihak mitra untuk pelanggan. Dalam file JSON, info masuk terlihat seperti contoh kode ini:

{ 
   "typeProperties" : {
      "extendedProperties" : { 
         "partnerCredentials": "" } 
   } 
}

partnerCredentialsInfo masuk tersedia sebagaimana yang diberikan pelanggan selama pendaftaran mitra.

Pustaka FarmBeats menyediakan fungsi pembantu. Gunakan fungsi ini untuk membaca info masuk dari properti aktivitas. Untuk informasi selengkapnya, lihat halaman GitHub untuk gambar NOAA Docker.

File ini hanya digunakan saat kode Docker sedang berjalan. Setelah kode selesai, file dihapus.

Untuk informasi selengkapnya tentang cara kerja alur dan aktivitas Data Factory, lihat Pemetaan skema dan tipe data.

Header permintaan HTTP

Tabel berikut ini memperlihatkan header permintaan paling umum yang perlu Anda tentukan saat melakukan panggilan API ke FarmBeats.

Header	Deskripsi dan contoh
Jenis-Konten	Format permintaan. Contoh: `Content-Type: application/<format>` Untuk API Datahub FarmBeats, formatnya adalah JSON. Contoh: `Content-Type: application/json`
Authorization	Token akses yang diperlukan untuk melakukan panggilan API. Contoh: `Authorization: Bearer <Access-Token>`
Terima	Format respons. Untuk API Datahub FarmBeats, formatnya adalah JSON. Contoh: `Accept: application/json`

Format data

JSON adalah format data independen bahasa umum yang menyediakan representasi teks sederhana dari struktur data arbitrer. Untuk informasi selengkapnya, lihat JSON.org.

Spesifikasi Docker

Program Docker membutuhkan dua komponen: bootstrap dan pekerjaan. Program ini dapat memiliki lebih dari satu pekerjaan.

Bootstrap

Komponen bootstrap akan berjalan ketika pelanggan memulai pendaftaran Docker di FarmBeats. Argumen berikut (arg1 dan arg2) diteruskan ke program:

Titik akhir API FarmBeats: Titik akhir API FarmBeats untuk permintaan API. Titik akhir ini melakukan panggilan API ke penyebaran FarmBeats.
URL Azure Functions: Titik akhir Anda sendiri. URL ini menyediakan token akses Anda untuk API FarmBeats. Anda dapat memanggil GET pada URL ini untuk mengambil token akses.

Bootstrap membuat metadata yang dibutuhkan pengguna untuk menjalankan pekerjaan Anda guna mendapatkan data cuaca. Untuk informasi selengkapnya, lihat implementasi referensi.

Jika Anda menyesuaikan file bootstrap_manifest.json, maka program bootstrap referensi akan membuat metadata yang diperlukan untuk Anda. Program bootstrap membuat metadata berikut:

Catatan

Jika Anda memperbarui file bootstrap_manifest.json sebagaimana penjelasan implementasi referensi, maka Anda tidak perlu membuat metadata berikut. Program bootstrap akan menggunakan file manifes Anda untuk membuat metadata yang diperlukan.

/WeatherDataModel: Metadata WeatherDataModel mewakili data cuaca. Data ini sesuai dengan kumpulan data yang disediakan sumber. Misalnya, DailyForecastSimpleModel akan memberikan informasi rerata suhu, kelembaban, dan curah hujan sekali sehari. Sebaliknya, DailyForecastAdvancedModel mungkin memberikan lebih banyak informasi pada granularitas per jam. Anda dapat membuat model data cuaca sebanyak apa pun.
/JobType: FarmBeats memiliki sistem manajemen pekerjaan yang dapat diperluas. Sebagai penyedia data cuaca, Anda akan memiliki berbagai set data dan API (misalnya, GetDailyForecasts). Anda dapat mengaktifkan set data dan API ini di FarmBeats dengan menggunakan JobType. Setelah jenis pekerjaan dibuat, pelanggan dapat memicu pekerjaan jenis itu untuk mendapatkan data cuaca untuk lokasi atau bidang minat mereka.

Pekerjaan

Komponen Jobs dipanggil setiap kali pengguna FarmBeats menjalankan pekerjaan /JobType yang Anda buat sebagai bagian dari proses bootstrap. Perintah jalankan Docker untuk pekerjaan ini didefinisikan sebagai bagian dari /JobType yang Anda buat.

Pekerjaan ini mengambil data dari sumber dan mendorongnya ke FarmBeats. Selama proses bootstrap, parameter yang diperlukan untuk mendapatkan data harus didefinisikan sebagai bagian dari /JobType.

Sebagai bagian dari pekerjaan, program harus membuat /WeatherDataLocation berdasarkan /WeatherDataModel yang dibuat selama proses bootstrap. /WeatherDataLocation sesuai dengan lokasi (koordinat lintang dan bujur) yang disediakan pengguna sebagai parameter untuk pekerjaan tersebut.

Detail objek

WeatherDataModel	Deskripsi
Nama	Nama model data cuaca.
Deskripsi	Deskripsi model yang bermakna.
Properti	Properti tambahan yang ditentukan oleh penyedia data.
Nama weatherMeasures >	Nama ukuran cuaca. Misalnya, humidity_max.
weatherMeasures > DataType	Baik Double atau Enum. Jika Enum, maka measureEnumDefinition diperlukan.
weatherMeasures > measureEnumDefinition	Diperlukan hanya jika DataType adalah Enum. Contohnya, `{ "NoRain": 0, "Snow": 1, "Drizzle": 2, "Rain": 3 }`
Jenis weatherMeasures >	Jenis data telemetri cuaca. Misalnya, RelativeHumidity. Jenis yang ditentukan sistem adalah AmbientTemperature, NoUnit, CO2, Depth, ElectricalConductivity, LeafWetness, Length, LiquidLevel, Nitrate, O2, PH, Phosphate, PointInTime, Potassium, Pressure, RainGauge, RelativeHumidity, Salinity, SoilMoisture, SoilTemperature, SolarRadiation, State, TimeDuration, UVRadiation, UVIndex, Volume, WindDirection, WindRun, WindSpeed, Evapotranspiration, dan PAR. Untuk menambahkan tipe lainnya, lihat bagian Tambahkan ExtendedType di artikel ini.
Unit weatherMeasures >	Unit data telemetri cuaca. Unit yang ditentukan sistem adalah NoUnit, Celsius, Fahrenheit, Kelvin, Rankine, Pascal, Mercury, PSI, MilliMeter, CentiMeter, Meter, Inch, Feet, Mile, KiloMeter, MilesPerHour, MilesPerSecond, KMPerHour, KMPerSecond, MetersPerHour, MetersPerSecond, Degree, WattsPerSquareMeter, KiloWattsPerSquareMeter, MilliWattsPerSquareCentiMeter, MilliJoulesPerSquareCentiMeter, VolumetricWaterContent, Percentage, PartsPerMillion, MicroMole, MicroMolesPerLiter, SiemensPerSquareMeterPerMole, MilliSiemensPerCentiMeter, Centibar, DeciSiemensPerMeter, KiloPascal, VolumetricIonContent, Liter, MilliLiter, Seconds, UnixTimestamp, MicroMolePerMeterSquaredPerSecond, dan InchesPerHour. Untuk menambahkan tipe lainnya, lihat bagian Tambahkan ExtendedType di artikel ini.
weatherMeasures > AggregationType	Jenis agregasi. Nilai yang mungkin adalah None, Average, Maximum, Minimum, StandardDeviation, Sum, and Total.
Kedalaman weatherMeasures >	Kedalaman sensor dalam sentimeter. Misalnya, pengukuran kelembaban 10 cm di bawah tanah.
Deskripsi weatherMeasures >	Deskripsi model yang bermakna.

JobType	Deskripsi
Nama	Nama pekerjaan. Misalnya, Get_Daily_Forecast. Pelanggan akan menjalankan pekerjaan ini untuk mendapatkan data cuaca.
nama parameter pipelineDetails >>	Nama parameter.
jenis parameter pipelineDetails >>	Jenis parameter Nilai yang mungkin termasuk String, Int, Float, Bool, dan Array.
parameter pipelineDetails >> isRequired	Nilai Boolean parameter. Nilai tersebut true jika parameter diperlukan. Jika tidak, nilainya false. Defaultnya adalah true.
parameter pipelineDetails >> defaultValue	Nilai default parameter.
deskripsi parameter pipelineDetails >>	Deskripsi parameter.
Properti	Properti tambahan dari produsen.
Program propertiRunCommand >	Perintah menjalankan Docker. Perintah ini berjalan ketika pelanggan menjalankan pekerjaan cuaca.

WeatherDataLocation	Deskripsi
weatherDataModelId	ID dari WeatherDataModel yang sesuai yang dibuat selama proses bootstrap.
lokasi	Garis lintang, bujur, dan ketinggian.
Nama	Nama objek.
Deskripsi	Deskripsi lokasi data cuaca.
farmId	(Opsional) ID peternakan. Pelanggan memberikan ID ini sebagai bagian dari parameter pekerjaan.
Properti	Properti tambahan dari produsen.

Catatan

API mengembalikan ID unik untuk setiap instans yang dibuat. Penerjemah untuk manajemen perangkat dan sinkronisasi metadata perlu mempertahankan ID ini.

Sinkronisasi metadata

Komponen Connector Docker harus dapat mengirim pembaruan pada metadata. Misalnya, penyedia cuaca harus mengirim pembaruan saat penyedia cuaca menambahkan parameter baru ke set data atau saat fungsionalitas baru, seperti perkiraan 30 hari baru, ditambahkan.

Catatan

Penghapusan tidak didukung untuk metadata dalam model data cuaca.

Untuk memperbarui metadata, Anda harus memanggil /Get/{ID} model data cuaca. Perbarui properti yang diubah, lalu lakukan /Put/{ID} untuk mempertahankan properti apa pun yang ditetapkan pengguna.

Spesifikasi data cuaca (telemetri)

Data cuaca dipetakan ke pesan kanonis yang didorong ke hub kejadian Azure untuk diproses. Azure Event Hubs adalah layanan yang memungkinkan penyebaran data (telemetri) secara real time dari perangkat dan aplikasi yang terhubung.

Untuk mengirim data cuaca ke FarmBeats, buat klien yang mengirim pesan ke hub acara di FarmBeats. Untuk informasi lebih lanjut, lihat Mengirim telemetri ke hub kejadian.

Contoh kode Python berikut mengirimkan telemetri sebagai klien ke hub kejadian tertentu.

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()

Berikut format pesan kanonisnya:

{
   "weatherstations": [
   {
   "id": "ID of the WeatherDataLocation.",
   "weatherdata": [
   {
     "timestamp": "Timestamp of the data. For historical purposes, this is the time for which the observations are sent. For forecast, this is the time for which data is forecasted. Format is ISO 8601. Default time zone is UTC.",
     "predictiontimestamp": "Timestamp on which the forecast data is predicted. I.e., the time of prediction. Required only for forecast data. Format is ISO 8601. Default time zone is UTC. ",
     "weathermeasurename1": <value>,
     "weathermeasurename2": <value>
     }
     ]
    }
   ]
}

Berikut ini contoh pesan telemetri:

{
   "weatherstations": [
   {
     "id": "5e4b34e7-bf9e-4f39-xxxx-f3c06d0366ea",
     "weatherdata": [
     {
      "timestamp": "2019-07-10T00:00:00Z",
      "predictiontimestamp": "2019-07-05T00:00:00Z",
      "PrecipitationTotalLiquidEquivalent": 0,
      "AvgPressure": 0,
      "AvgRelativeHumidity": 72
     }
    ] 
  }
 ]
}

Pemecahan masalah dan manajemen kesalahan

Pencatatan galat

Pekerjaan mitra berjalan dalam kerangka kerja yang sudah ada. Jadi kesalahan dicatat dengan cara yang sama seperti kesalahan pada pekerjaan FarmBeats lain yang sudah ada sebelumnya (seperti GetFarmData dan SensorPlacement). Aktivitas Data Factory yang berjalan dalam alur Data Factory mencatat baik STDERR maupaun STDOUT. Kedua file tersedia di datahublogs-xxx akun penyimpanan dalam grup sumber daya FarmBeats.

Pustaka Datahub menyediakan fungsi pembantu untuk mengaktifkan pencatatan sebagai bagian dari keseluruhan log Datahub. Untuk informasi selengkapnya, lihat halaman GitHub untuk gambar NOAA Docker.

Pemecahan masalah dan dukungan

Jika pelanggan tidak dapat menerima data cuaca di instans FarmBeats, berikan dukungan dan mekanisme untuk memecahkan masalah.

Tambahkan ExtendedType

FarmBeats mendukung penambahan jenis dan unit pengukuran sensor baru. Anda dapat menambahkan unit atau jenis baru dengan memperbarui file bootstrap_manifest.json dalam implementasi referensi.

Ikuti langkah-langkah ini untuk menambahkan jenis WeatherMeasure baru, misalnya, PrecipitationDepth.

Buat permintaan GETdi /ExtendedType dengan menggunakan kueri filter - key = WeatherMeasureType.
Perhatikan ID objek yang dikembalikan.
Tambahkan tipe baru ke daftar di objek yang dikembalikan. Buat permintaan PUT di /ExtendedType{ID} dengan daftar baru berikut ini. Payload input harus sama dengan respons yang Anda terima sebelumnya. Unit baru akan ditambahkan di akhir daftar nilai.

Langkah berikutnya

Sekarang Anda memiliki komponen Connector Docker yang terintegrasi dengan FarmBeats. Selanjutnya, cari tahu cara mendapatkan data cuaca dengan menggunakan gambar Docker Anda di FarmBeats.

Integrasi mitra cuaca dengan FarmBeats

Pengembangan Connector Docker

Pustaka Datahub

Autentikasi

Format data

Spesifikasi Docker

Bootstrap

Pekerjaan

Detail objek

Spesifikasi data cuaca (telemetri)

Pemecahan masalah dan manajemen kesalahan

Pencatatan galat

Pemecahan masalah dan dukungan

Tambahkan ExtendedType

Langkah berikutnya

Sumber Daya Tambahan: