感應器合作夥伴整合流程

發行項
12/04/2024

本文件將討論合作夥伴必須採取的上線步驟，以與用於農業的資料管理員整合。它概述了用來建立模型和清單感應器的 API、用來推送資料的遙測格式，最後是 IOTHub 型資料擷取。

合作夥伴流程：階段 1

以下是合作夥伴與用於農業的資料管理員整合所需的一組步驟。這是一次性整合。在階段 1 結束時，合作夥伴會在用於農業的資料管理員中建立其身分識別。

應用程式建立作業

合作夥伴必須經過驗證並獲得授權，才能存取用於農業的資料管理員客戶的資料平面 API。存取這些 API 可讓合作夥伴在客戶的用於農業的資料管理員執行個體內建立感應器模型、感應器和裝置物件。感應器物件資訊 (由合作夥伴建立) 是用於農業的資料管理員用來在 IOTHub 中建立個別裝置 (感應器) 的內容。

因此，若要啟用驗證和授權，合作夥伴必須執行下列動作

建立 Azure 帳戶 (如果您尚未建立帳戶。)
建立多租用戶 Microsoft Entra 應用程式 - 多租用戶 Microsoft Entra 應用程式顧名思義，表示如果客戶已明確同意合作夥伴應用程式，則有權存取多個客戶的租用戶 (如角色指派步驟中所述)。

合作夥伴可以使用在 Microsoft Entra ID 中註冊的多租用戶 Microsoft Entra 應用程式，存取客戶租用戶中的 API。應用程式註冊是在 Azure 入口網站上完成，因此 Microsoft 身分識別平台可以為您的應用程式提供驗證和授權服務，進而存取用於農業的資料管理員。

請遵循應用程式註冊中提供的步驟，直到步驟 8 產生下列資訊為止：

應用程式 (用戶端) ID
目錄 (租用戶) 識別碼
應用程式名稱

複製並儲存這三個值，因為您需要這些值來產生存取權杖。

所建立的應用程式 (用戶端) 識別碼就像應用程式的使用者識別碼，現在您需要為應用程式建立其對應的應用程式密碼 (用戶端密碼)，讓應用程式能夠自我識別。

遵循新增用戶端密碼 (部分機器翻譯) 中提供的步驟來產生「用戶端密碼」，並複製所產生的用戶端密碼。

註冊

合作夥伴成功建立多租使用者Microsoft Entra 應用程式之後，合作夥伴會建立支援票證，手動與農業用數據管理員小組共用應用程式標識碼和合作夥伴標識符。用於農業的資料管理員使用這項資訊，驗證其是否為真正的合作夥伴，並使用內部 API 建立合作夥伴身分識別 (sensorPartnerId)。在註冊過程中，合作夥伴能夠在建立感應器/裝置物件時使用其合作夥伴識別碼 (sensorPartnerId)，以及作為其所推送感應器資料的一部分。

取得合作夥伴識別碼會將用於農業的資料管理員合作夥伴整合標示為完成。現在，合作夥伴會等候來自任何感應器客戶的輸入，以起始其資料擷取至用於農業的資料管理員。

客戶流程

使用用於農業的資料管理員的客戶將會知道所有支援的感應器合作夥伴及其各自的應用程式識別碼。此資訊可在所有客戶的公開文件中取得。根據客戶所使用的感應器及其個別感應器合作夥伴的應用程式識別碼，客戶必須提供合作夥伴的存取權 (應用程式識別碼)，才能開始將感應器資料推送至其用於農業的資料管理員執行個體。必要步驟如下：

角色指派

選擇上線至特定合作夥伴的客戶應具有該特定合作夥伴的應用程式識別碼。使用應用程式識別碼時，客戶必須依序執行下列動作。

同意 – 由於合作夥伴的應用程式位於不同的租用戶中，且客戶希望合作夥伴在其用於農業的資料管理員執行個體中存取特定 API，因此客戶必須呼叫特定端點 https://login.microsoft.com/common/adminconsent/clientId=[client_id]，並將 [client_id] 取代為合作夥伴的應用程式識別碼。這可讓客戶的 Microsoft Entra ID 在客戶使用它進行角色指派時，辨識此應用程式識別碼。
身分識別存取管理 (IAM) – 身分識別存取管理的一部分，客戶會為上述已提供同意的應用程式識別碼建立新的角色指派。用於農業的資料管理員會建立名為感應器合作夥伴的新角色 (除了現有的管理員、參與者、讀取者角色之外)。客戶選擇感應器合作夥伴角色，並新增合作夥伴應用程式識別碼且提供存取權。

起始

客戶已讓用於農業的資料管理員知道他們需要從特定合作夥伴取得感應器資料。不過，合作夥伴還不知道應向其傳送感應器資料的客戶。因此，在下一個步驟中，客戶會呼叫用於農業的資料管理員內的整合 API，以產生整合連結。取得整合連結之後，無論是手動共用或使用合作夥伴的入口網站，客戶會依序共用下列資訊。

同意連結和租用戶識別碼 – 在此步驟中，客戶會提供同意連結和租用戶識別碼。整合連結看起來如範例所示：

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

除了同意連結之外，客戶也會提供租用戶識別碼。租用戶識別碼可用來擷取呼叫客戶 API 端點所需的存取權杖。

合作夥伴會在檢查同意連結 API 上進行 GET 呼叫，以驗證同意連結。因為連結已完整預先填入用於農業的資料管理員所預期的要求 URI。作為 GET 呼叫的一部分，合作夥伴會檢查回應中要傳遞的 200 OK 回應碼和 IntegrationId。

收到有效的回應之後，合作夥伴必須儲存兩組資訊
- API 端點 (可以從整合連結的第一個部分擷取)
- IntegrationId (作為 GET 呼叫回應的一部分傳回)
合作夥伴驗證並儲存這些資料點之後，即可讓客戶新增資料必須推送至用於農業的資料管理員的感應器。
新增感應器/裝置 – 現在，合作夥伴知道他們需要與哪些客戶 (API 端點) 整合，不過，他們仍然不知道需要將資料推送至哪些感應器。因此，合作夥伴會收集需要用來推送資料的感應器/裝置資訊。您可以手動或透過入口網站 UI 收集這項資料。

新增感應器/裝置之後，客戶可以預期個別感應器的資料流入其用於農業的資料管理員執行個體。此步驟會將客戶上線以擷取感應器資料標示為完成。

合作夥伴流程：階段 2

合作夥伴現在有呼叫特定 API 端點的資訊 (客戶的資料平面)，但他們仍然沒有需要將感應器遙測資料推送到哪個位置的資訊？

整合

在整合過程中，合作夥伴必須使用自己的應用程式識別碼、應用程式祕密和客戶在應用程式註冊步驟期間取得的租用戶識別碼，才能使用 Microsoft 的 oAuth API 來產生存取權杖。以下是用來產生存取權杖的 curl 命令

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'

回應看起來應如下所示：

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

透過產生的 access_token，合作夥伴會呼叫客戶的資料平面端點，以建立感應器模型、感應器和裝置。它是使用用於農業的資料管理員所建置的 API，在該特定用於農業的資料管理員執行個體中建立的。如需合作夥伴 API 的詳細資訊，請參閱合作夥伴 API 文件。

在感應器建立 API 中，合作夥伴會提供感應器識別碼，一旦建立感應器資源之後，合作夥伴就會呼叫取得連接字串 API，以取得該感應器的連接字串。

推送資料

建立感應器合作夥伴整合

建立感應器合作夥伴整合，以將特定合作夥伴與特定提供者連線。 integrationId 稍後會在感應器建立中使用。 API 文件：感應器合作夥伴整合 - 建立或更新

建立感應器資料模型

使用感應器資料模型來定義要傳送的遙測模型。感應器傳送的所有遙測都會根據此資料模型進行驗證。

API 文件：感應器資料模型 - 建立或更新

樣本遙測

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

對應的感應器資料模型

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

建立感應器

使用對應的整合識別碼和感應器資料模型識別碼建立感應器。 DeviceId 和 HardwareId 是選擇性參數，如有需要，您可以使用裝置 - 建立或更新以建立裝置。

API 文件：感應器 - 建立或更新

取得 IoTHub 連接字串

取得IoTHub連接字串，以將感應器遙測推送至所建立感應器的平台。

API 文件：感應器 - 取得連接字串

使用 IoT 中樞推送資料

使用 IoT中樞裝置SDK 以使用連接字串來推送遙測。

針對所有感應器遙測事件，“timestamp” 是必要屬性，且必須使用 ISO 8601 格式 (YYYY-MM-DDTHH:MM:SSZ)。

合作夥伴現在全都設定為使用針對每個感應器提供的個別連接字串，開始推送所有感應器的感應器資料。不過，合作夥伴會以 FarmBeats 所定義的 JSON 格式傳送感應器資料。請參閱此處提供的遙測結構描述。

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

將資料推送至 IOTHub 之後，客戶就能夠使用輸出 API 查詢感應器資料。

下一步

請在此測試 API。

共用方式為