Algılayıcı iş ortağı tümleştirme akışı

Makale
05/23/2024

Bu belgede, bir iş ortağının Tarım için Data Manager ile tümleştirmek için gerçekleştirmesi gereken ekleme adımları anlatılacaktır. Modelleri ve liste algılayıcısını oluşturmak için kullanılan API'lere, verileri göndermek için telemetri biçimine ve son olarak IOTHub tabanlı veri alımına genel bir bakış sunar.

Ekleme

Ekleme, hem müşterilerin hem de iş ortaklarının Tarım için Data Manager ile tümleştirilmesi ve sırasıyla algılayıcı telemetrisi almaya/göndermeye başlaması için gereken adımları kapsar.

Algılayıcı iş ortakları akışını gösteren ekran görüntüsü.

Yukarıdaki şekilde, beyaz renkle vurgulanan bloklar bir iş ortağı tarafından gerçekleştirilir ve siyah renkle vurgulanan bloklar müşteriler tarafından gerçekleştirilir.

İş ortağı akışı: 1. Aşama

Aşağıda, bir iş ortağının Tarım için Data Manager ile tümleştirme için yapması gereken adımlar kümesi yer alır. Bu tek seferlik bir tümleştirmedir. 1. aşamanın sonunda iş ortakları, Tarım için Veri Yöneticisi'nde kimliklerini oluşturur.

Uygulama oluşturma

İş ortaklarının kimliğinin doğrulanması ve Tarım müşterilerinin veri düzlemi API'leri için Veri Yöneticisi'ne erişme yetkisine sahip olması gerekir. Bu API'lere erişim, iş ortaklarının müşterilerin Tarım için Data Manager örneğinde algılayıcı modelleri, algılayıcılar ve cihaz nesneleri oluşturmasını sağlar. Sensör nesne bilgileri (iş ortağı tarafından oluşturulan), Tarım için Data Manager tarafından IOTHub'da ilgili cihazları (algılayıcılar) oluşturmak için kullanılan bilgilerdir.

Bu nedenle, kimlik doğrulaması ve yetkilendirmeyi etkinleştirmek için iş ortaklarının aşağıdakileri yapması gerekir

Azure hesabı oluşturma (Önceden oluşturulmuş bir hesabınız yoksa.)
Çok kiracılı bir Microsoft Entra uygulaması oluşturma - Ad olarak çok kiracılı Microsoft Entra uygulamasının, müşteriler iş ortağı uygulamasına açık onay vermişse (rol atama adımında açıklanmıştır) birden çok müşterinin kiracısına erişimi vardır.

İş ortakları, Microsoft Entra Kimliği'nde kayıtlı çok kiracılı Microsoft Entra Uygulamasını kullanarak müşteri kiracısında API'lere erişebilir. Uygulama kaydı Azure portalında yapılır, böylece Microsoft kimlik platformu uygulamanız için tarım için Data Manager'a erişen kimlik doğrulama ve yetkilendirme hizmetleri sağlayabilir.

Aşağıdaki bilgileri oluşturmak için 8. Adıma kadar Uygulama Kaydı'nda sağlanan adımları izleyin:

Uygulama (istemci) kimliği
Dizin (kiracı) kimliği
Uygulama Adı

Erişim belirteci oluşturmak için ihtiyaç duyacağınız üç değeri de kopyalayıp depolayın.

Oluşturulan Uygulama (istemci) kimliği, uygulamanın Kullanıcı Kimliği gibidir ve şimdi uygulamanın kendisini tanımlaması için ilgili Uygulama parolasını (istemci gizli dizisi) oluşturmanız gerekir.

İstemci Gizli Dizisi oluşturmak ve oluşturulan istemci gizli dizisini kopyalamak için İstemci gizli dizisi ekleme bölümünde sağlanan adımları izleyin.

Kayıt

İş ortağı çok kiracılı bir Microsoft Entra uygulamasını başarıyla oluşturduktan sonra, iş ortakları destek bileti oluşturarak APP ID ve İş Ortağı Kimliğini Tarım için Data Manager ekibiyle el ile paylaşır. Tarım için Data Manager bu bilgilerin kullanılması, gerçek bir iş ortağı olup olmadığını doğrular ve iç API'leri kullanarak bir iş ortağı kimliği (sensorPartnerId) oluşturur. Kayıt işleminin bir parçası olarak, iş ortakları sensör/cihaz nesnesini oluştururken ve ayrıca gönderdikleri algılayıcı verilerinin bir parçası olarak iş ortağı kimliklerini (sensorPartnerId) kullanabilir.

İş ortağı kimliğinin alınması, tarım tümleştirmesi için partner-Data Manager'ın tamamlanmasını işaret eder. Şimdi iş ortağı, sensör müşterilerinden herhangi birinin tarım için Data Manager'a veri alımını başlatmasını bekler.

Müşteri akışı

Tarım için Data Manager kullanan müşteriler, desteklenen tüm algılayıcı iş ortaklarının ve ilgili UYGULAMA kimliklerinin farkında olacaktır. Bu bilgiler tüm müşterilerimiz için genel belgelerde yer alır. Müşterilerin kullandığı algılayıcılara ve ilgili algılayıcı iş ortağının APP kimliğine bağlı olarak müşterinin sensör verilerini Tarım için Data Manager örneğine göndermeye başlamak için iş ortağına (APP ID) erişim sağlaması gerekir. Gerekli adımlar şunlardır:

Rol ataması

Belirli bir iş ortağına eklemeyi seçen müşterilerin bu iş ortağının uygulama kimliğine sahip olması gerekir. Müşterinin uygulama kimliğini kullanarak sırayla aşağıdaki şeyleri yapması gerekir.

Onay – İş ortağının uygulaması farklı bir kiracıda bulunduğundan ve müşteri iş ortağının Tarım için Data Manager örneğindeki belirli API'lere erişmesini istediğinden, müşterilerin belirli bir uç noktayı https://login.microsoft.com/common/adminconsent/clientId=[client_id] çağırması ve [client_id] yerine iş ortaklarının uygulama kimliğini yazması gerekir. Bu, müşterilerin Microsoft Entra Id'sinin rol ataması için her kullandıklarında bu UYGULAMA Kimliğini tanımasını sağlar.
Kimlik Erişim Yönetimi (IAM) – Kimlik erişim yönetimi kapsamında müşteriler, yukarıdaki uygulama kimliğine onay verilen yeni bir rol ataması oluşturur. Tarım için Data Manager, Algılayıcı İş Ortağı adlı yeni bir rol oluşturur (Mevcut Yönetici, Katkıda Bulunan, Okuyucu rollerine ek olarak). Müşteriler algılayıcı iş ortağı rolünü seçer, iş ortağı uygulama kimliğini ekler ve erişim sağlar.

Başlatma

Müşteri, Tarım için Data Manager'ı belirli bir iş ortağından sensör verileri alması gerektiğinin farkında hale getirmiştir. Ancak iş ortağı, algılayıcı verilerini hangi müşteriye göndermesi gerektiğini henüz bilmiyor. Bu nedenle bir sonraki adım olarak müşteri, bir tümleştirme bağlantısı oluşturmak için Tarım için Data Manager'da tümleştirme API'sine çağrıda bulunur. Tümleştirme bağlantısı alındıktan sonra müşteriler aşağıdaki bilgileri el ile paylaşır veya iş ortağının portalını kullanarak sırayla paylaşır.

Onay bağlantısı ve Kiracı Kimliği – Bu adımda müşteri bir onay bağlantısı ve kiracı kimliği sağlar. Tümleştirme bağlantısı örnekte gösterildiği gibi görünür:

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

Onay bağlantısına ek olarak, müşteriler bir kiracı kimliği de sağlayabilir. Kiracı kimliği, müşterinin API uç noktasına çağrı yapmak için gereken erişim belirtecini getirmek için kullanılır.

İş ortakları onay bağlantısı API'sinde get çağrısı yaparak onay bağlantısını doğrular. Bağlantı, Tarım için Veri Yöneticisi tarafından beklendiği gibi tam olarak önceden doldurulmuş istek URI'sine sahip olduğundan. GET çağrısının bir parçası olarak, iş ortakları yanıtta geçirilecek 200 Ok yanıt kodunu ve IntegrationId değerini denetler.

Geçerli yanıt alındıktan sonra iş ortaklarının iki bilgi kümesini depolaması gerekir
- API uç noktası (tümleştirme bağlantısının ilk bölümünden ayıklanabilir)
- IntegrationId (GET çağrısı yanıtının bir parçası olarak döndürülür)
İş ortağı bu veri noktalarını doğrulayıp depoladıktan sonra müşterilerin verilerin Tarım için Data Manager'a gönderilmesi gereken algılayıcılar eklemesini sağlayabilir.
Algılayıcı/cihaz ekleme – İş ortağı artık hangi müşteriyle (API uç noktası) tümleştirilmesi gerektiğini biliyor ancak yine de verileri hangi algılayıcılar için göndermesi gerektiğini bilmiyor. Bu nedenle, iş ortakları verilerin gönderilmesi gereken algılayıcı/cihaz bilgilerini toplar. Bu veriler el ile veya portal kullanıcı arabirimi aracılığıyla toplanabilir.

Müşteriler, algılayıcıları/cihazları ekledikten sonra ilgili sensörlerin veri akışının Tarım için Data Manager örneğine gelmesini bekleyebilir. Bu adım, algılayıcı verilerini getirmek için müşteri ekleme işleminin tamamlanmasını işaretler.

İş ortağı akışı: 2. Aşama

İş ortağı artık belirli bir API uç noktasını çağırmaya yönelik bilgilere (Müşterilerin veri düzlemi) sahip ancak algılayıcı telemetri verilerini nereye göndermeleri gerektiği konusunda hala bilgi sahibi değil mi?

Tümleştirme

Tümleştirme kapsamında, iş ortaklarının Microsoft'un oAuth API'sini kullanarak bir erişim belirteci oluşturmak için uygulama kayıt adımı sırasında alınan kendi uygulama kimliğini, uygulama gizli dizisini ve müşterinin kiracı kimliğini kullanması gerekir. Erişim belirtecini oluşturmak için curl komutu aşağıdadır

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'

Yanıt şöyle görünmelidir:

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

Oluşturulan access_token, iş ortakları sensör modeli, algılayıcı ve cihaz oluşturmak için müşterilerin veri düzlemi uç noktasını çağırır. Bu örnek, Tarım için Veri Yöneticisi tarafından oluşturulan API'ler kullanılarak ilgili Tarım için Veri Yöneticisi örneğinde oluşturulur. İş ortağı API'leri hakkında daha fazla bilgi için iş ortağı API'sinin belgelerine bakın.

Algılayıcı oluşturma API'sinin bir parçası olarak, iş ortakları algılayıcı kimliğini sağlar ve algılayıcı kaynağı oluşturulduktan sonra iş ortakları bu algılayıcı için bir bağlantı dizesi almak için get bağlantı dizesi API'sini çağırır.

Verileri gönderme

Algılayıcı iş ortağı tümleştirmesi oluşturma

Belirli bir tarafı belirli bir sağlayıcıya bağlamak için algılayıcı iş ortağı tümleştirmesi oluşturun. IntegrationId daha sonra algılayıcı oluşturmada kullanılır. API belgeleri: Algılayıcı İş Ortağı Tümleştirmeleri - Oluşturma veya Güncelleştirme

Algılayıcı veri modeli oluşturma

Gönderilen telemetri modelini tanımlamak için algılayıcı veri modelini kullanın. Algılayıcı tarafından gönderilen tüm telemetri verileri bu veri modeline göre doğrulanır.

API belgeleri: Algılayıcı Veri Modelleri - Oluşturma veya Güncelleştirme

Örnek telemetri

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

İlgili sensör veri modeli

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

Algılayıcı oluşturma

İlgili tümleştirme kimliğini ve algılayıcı veri modeli kimliğini kullanarak algılayıcı oluşturun. DeviceId ve HardwareId isteğe bağlı parametrelerdir; gerekirse cihazı oluşturmak için Cihazlar - Oluştur veya Güncelleştir'i kullanabilirsiniz.

API belgeleri: Algılayıcılar - Oluşturma veya Güncelleştirme

IoTHub bağlantı dizesi edinin

Oluşturulan Algılayıcı için platforma algılayıcı telemetrisi göndermek için IoTHub bağlantı dizesi edinin.

API Belgeleri: Algılayıcılar - Bağlan Ion Dizesini Alma

IoT Hub kullanarak Veri Gönderme

bağlantı dizesi kullanarak telemetriyi göndermek için IoT Hub Cihaz SDK'larını kullanın.

Tüm algılayıcı telemetri olayları için "zaman damgası" zorunlu bir özelliktir ve ISO 8601 biçiminde olmalıdır (YYYY-MM-DDTHH:MM:SSZ).

İş ortağı artık her sensör için sağlanan ilgili bağlantı dizesi kullanarak tüm algılayıcılar için sensör verilerini göndermeye başlamaya hazır. Ancak iş ortağı, algılayıcı verilerini FarmBeats tarafından tanımlandığı şekilde JSON biçiminde gönderiyor olacaktır. Burada sağlanan telemetri şemasına bakın.

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

Veriler IOTHub'a gönderildikten sonra müşteriler çıkış API'sini kullanarak algılayıcı verilerini sorgulayabilecektir.

Sonraki adımlar

API'lerimizi burada test edin.

Aracılığıyla paylaş