Alur integrasi mitra sensor

Artikel
05/23/2024

Dokumen ini berbicara tentang langkah-langkah onboarding yang perlu diambil mitra untuk diintegrasikan dengan Data Manager for Agriculture. Ini menyajikan gambaran umum API yang digunakan untuk membuat model & mencantumkan sensor, format telemetri untuk mendorong data dan akhirnya penyerapan data berbasis IOTHub.

Onboarding

Onboarding mencakup langkah-langkah yang diperlukan oleh pelanggan & mitra untuk berintegrasi dengan Data Manager untuk Pertanian dan mulai menerima/mengirim telemetri sensor masing-masing.

Cuplikan layar memperlihatkan alur mitra sensor.

Dari gambar di atas, blok yang disorot dengan warna putih adalah langkah-langkah yang diambil oleh mitra, dan yang disorot dalam warna hitam dilakukan oleh pelanggan.

Alur mitra: Fase 1

Berikut adalah serangkaian langkah yang perlu dilakukan mitra untuk mengintegrasikan dengan Data Manager for Agriculture. Ini adalah integrasi satu kali. Pada akhir fase 1, mitra menetapkan identitas mereka di Manajer Data untuk Pertanian.

Pembuatan aplikasi

Mitra perlu diautentikasi dan diotorisasi untuk mengakses API data plane pelanggan Manajer Data untuk Pertanian. Akses ke API ini memungkinkan mitra untuk membuat model sensor, sensor, dan objek perangkat dalam instans Data Manager for Agriculture pelanggan. Informasi objek sensor (dibuat oleh mitra) adalah apa yang digunakan oleh Data Manager for Agriculture untuk membuat perangkat (sensor) masing-masing di IOTHub.

Oleh karena itu untuk mengaktifkan autentikasi & otorisasi, mitra perlu melakukan hal berikut

Buat akun Azure (Jika Anda belum membuatnya.)
Buat aplikasi Microsoft Entra multi-penyewa - Aplikasi Microsoft Entra multi-penyewa sebagai nama menandakan, memiliki akses ke beberapa penyewa pelanggan, jika pelanggan telah memberikan persetujuan eksplisit untuk aplikasi mitra (dijelaskan dalam langkah penetapan peran).

Mitra dapat mengakses API di penyewa pelanggan menggunakan Aplikasi Microsoft Entra multi-penyewa, yang terdaftar di ID Microsoft Entra. Pendaftaran aplikasi dilakukan pada portal Azure sehingga platform identitas Microsoft dapat menyediakan layanan autentikasi dan otorisasi untuk aplikasi Anda yang pada gilirannya mengakses Data Manager for Agriculture.

Ikuti langkah-langkah yang disediakan dalam PendaftaranAplikasi hingga Langkah 8 untuk menghasilkan informasi berikut:

ID aplikasi (klien)
ID direktori (tenant)
Nama Aplikasi

Salin dan simpan ketiga nilai karena Anda akan membutuhkannya untuk menghasilkan token akses.

ID Aplikasi (klien) yang dibuat seperti ID Pengguna aplikasi, dan sekarang Anda perlu membuat kata sandi Aplikasi (rahasia klien) yang sesuai agar aplikasi mengidentifikasi dirinya sendiri.

Ikuti langkah-langkah yang disediakan di Menambahkan rahasia klien untuk menghasilkan Rahasia Klien dan salin rahasia klien yang dihasilkan.

Pendaftaran

Setelah mitra berhasil membuat aplikasi Microsoft Entra multi-penyewa, mitra secara manual berbagi ID APLIKASI dan ID Mitra dengan tim Data Manager for Agriculture dengan membuat tiket dukungan. Menggunakan informasi ini Data Manager for Agriculture memvalidasi apakah itu adalah mitra autentik dan membuat identitas mitra (sensorPartnerId) menggunakan API internal. Sebagai bagian dari proses pendaftaran, mitra diaktifkan untuk menggunakan ID mitra mereka (sensorPartnerId) saat membuat objek sensor/perangkat dan juga sebagai bagian dari data sensor yang mereka dorong.

Mendapatkan ID mitra menandai penyelesaian integrasi partner-Data Manager for Agriculture. Sekarang, mitra menunggu input dari salah satu pelanggan sensor mereka untuk memulai penyerapan data mereka ke Data Manager for Agriculture.

Alur pelanggan

Pelanggan yang menggunakan Data Manager for Agriculture akan mengetahui semua mitra sensor yang didukung dan ID APLIKASI masing-masing. Informasi ini tersedia dalam dokumentasi publik untuk semua pelanggan kami. Berdasarkan sensor yang digunakan pelanggan dan ID APLIKASI mitra sensor masing-masing, pelanggan harus menyediakan akses ke mitra (APP ID) untuk mulai mendorong data sensor mereka ke instans Data Manager for Agriculture mereka. Berikut adalah langkah-langkah yang diperlukan:

Penetapan peran

Pelanggan yang memilih untuk onboarding ke mitra tertentu harus memiliki ID aplikasi dari mitra tertentu tersebut. Menggunakan ID aplikasi pelanggan perlu melakukan hal-hal berikut secara berurutan.

Persetujuan – Karena aplikasi mitra berada di penyewa yang berbeda dan pelanggan ingin mitra mengakses API tertentu di instans Data Manager for Agriculture mereka, pelanggan diharuskan untuk memanggil titik https://login.microsoft.com/common/adminconsent/clientId=[client_id] akhir tertentu dan mengganti [client_id] dengan ID aplikasi mitra. Ini memungkinkan ID Microsoft Entra pelanggan mengenali ID APLIKASI ini setiap kali mereka menggunakannya untuk penetapan peran.
Manajemen Akses Identitas (IAM) – Sebagai bagian dari manajemen akses Identitas, pelanggan membuat penetapan peran baru ke ID aplikasi di atas, yang diberikan persetujuan. Manajer Data untuk Pertanian membuat peran baru yang disebut Mitra Sensor (Selain peran Admin, Kontributor, Pembaca yang ada). Pelanggan memilih peran mitra sensor dan menambahkan ID aplikasi mitra dan menyediakan akses.

Inisiasi

Pelanggan telah membuat Manajer Data untuk Pertanian menyadari bahwa mereka perlu mendapatkan data sensor dari mitra tertentu. Namun, mitra belum tahu pelanggan mana yang harus mereka kirimi data sensor. Oleh karena itu sebagai langkah berikutnya, pelanggan akan memanggil API integrasi dalam Data Manager for Agriculture untuk menghasilkan tautan integrasi. Pasca memperoleh tautan integrasi, pelanggan akan membagikan informasi di bawah ini secara berurutan, baik berbagi secara manual atau menggunakan portal mitra.

Tautan persetujuan & ID Penyewa – Dalam langkah ini, pelanggan menyediakan tautan persetujuan & ID penyewa. Tautan integrasi terlihat seperti yang ditunjukkan dalam contoh:

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

Selain tautan persetujuan, pelanggan juga akan memberikan ID penyewa. ID penyewa digunakan untuk mengambil token akses yang diperlukan untuk memanggil ke titik akhir API pelanggan.

Mitra memvalidasi tautan persetujuan dengan melakukan panggilan GET pada API tautan persetujuan pemeriksaan. Karena tautan sepenuhnya diisi sebelumnya meminta URI seperti yang diharapkan oleh Manajer Data untuk Pertanian. Sebagai bagian dari panggilan GET, mitra memeriksa kode respons 200 OK dan IntegrationId untuk diteruskan dalam respons.

Setelah respons yang valid diterima, mitra harus menyimpan dua set informasi
- Titik akhir API (dapat diekstrak dari bagian pertama tautan integrasi)
- IntegrationId (dikembalikan sebagai bagian dari respons terhadap panggilan GET)
Setelah mitra memvalidasi dan menyimpan titik data ini, mereka dapat memungkinkan pelanggan untuk menambahkan sensor yang datanya harus didorong ke Manajer Data untuk Pertanian.
Tambahkan sensor/perangkat – Sekarang, mitra tahu pelanggan (titik akhir API) mana yang perlu mereka integrasikan, namun, mereka masih tidak tahu yang semua sensornya perlu mendorong data. Oleh karena itu, mitra mengumpulkan informasi sensor/perangkat yang datanya perlu didorong. Data ini dapat dikumpulkan baik secara manual atau melalui UI portal.

Pasca menambahkan sensor/perangkat, pelanggan dapat mengharapkan aliran data sensor masing-masing ke instans Data Manager for Agriculture mereka. Langkah ini menandai penyelesaian onboarding pelanggan untuk mengambil data sensor.

Alur mitra: Fase 2

Mitra sekarang memiliki informasi untuk memanggil titik akhir API tertentu (bidang data Pelanggan), tetapi mereka masih tidak memiliki informasi di mana mereka perlu mendorong data telemetri sensor?

Integrasi

Sebagai bagian dari integrasi, mitra perlu menggunakan ID aplikasi mereka sendiri, rahasia aplikasi & ID penyewa pelanggan yang diperoleh selama langkah pendaftaran aplikasi, untuk menghasilkan token akses menggunakan API oAuth Microsoft. Berikut perintah curl untuk menghasilkan token akses

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'

Respons akan terlihat seperti ini:

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

Dengan access_token yang dihasilkan, mitra memanggil titik akhir bidang data pelanggan untuk membuat model sensor, sensor, dan perangkat. Ini dibuat dalam instans Data Manager for Agriculture tertentu menggunakan API yang dibangun oleh Data Manager for Agriculture. Untuk informasi selengkapnya tentang API mitra, lihat dokumentasi API mitra.

Sebagai bagian dari API pembuatan sensor, mitra menyediakan ID sensor, setelah sumber daya sensor dibuat, mitra memanggil ke GET string koneksi API untuk mendapatkan string koneksi untuk sensor tersebut.

Mendorong data

Membuat integrasi mitra sensor

Buat integrasi mitra sensor untuk menghubungkan pihak tertentu dengan penyedia tertentu. IntegrationId kemudian digunakan dalam pembuatan sensor. Dokumentasi API: Integrasi Mitra Sensor - Buat Atau Perbarui

Membuat model data sensor

Gunakan model data sensor untuk menentukan model telemetri yang dikirim. Semua telemetri yang dikirim oleh sensor divalidasi sesuai model data ini.

Dokumentasi API: Model Data Sensor - Buat Atau Perbarui

Telemetri sampel

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

Model data sensor yang sesuai

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

Membuat sensor

Buat sensor menggunakan ID integrasi dan ID model data sensor yang sesuai. DeviceId dan HardwareId adalah parameter opsional, jika diperlukan, Anda dapat menggunakan Perangkat - Buat Atau Perbarui untuk membuat perangkat.

Dokumentasi API: Sensor - Buat Atau Perbarui

Dapatkan string koneksi IoTHub

Dapatkan string koneksi IoTHub untuk mendorong telemetri sensor ke platform untuk Sensor yang dibuat.

Dokumentasi API: Sensor - Dapatkan String Koneksi ion

Mendorong Data menggunakan IoT Hub

Gunakan SDK Perangkat IoT Hub untuk mendorong telemetri menggunakan string koneksi.

Untuk semua peristiwa telemetri sensor, "tanda waktu" adalah properti wajib dan harus dalam format ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).

Mitra sekarang semua diatur untuk mulai mendorong data sensor untuk semua sensor menggunakan masing-masing string koneksi disediakan untuk setiap sensor. Namun, mitra akan mengirim data sensor dalam format JSON seperti yang didefinisikan oleh FarmBeats. Lihat skema telemetri yang disediakan di sini.

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

Setelah data didorong ke IOTHub, pelanggan akan dapat mengkueri data sensor menggunakan API keluar.

Langkah berikutnya

Uji API kami di sini.

Bagikan melalui