以客戶身分整合感應器

發行項
05/25/2024

請遵循這些步驟，與感應器合作夥伴進行整合，以便合作夥伴開始將資料推送至用於農業的資料管理員執行個體。

每個感應器合作夥伴都已在用於農業的資料管理員平台上建立並發佈自己的多租用戶 Microsoft Entra 應用程式。該平台預設支援的感應器合作夥伴為 Davis Instruments (sensorPartnerId: DavisInstruments)。

若要開始使用已上線的感應器合作夥伴，您必須提供同意給感應器合作夥伴，這些合作夥伴才會開始顯示在 App Registrations 中。您必須執行下列步驟:

使用「全域管理員」或「特殊權限角色管理員」認證登入 Azure 入口網站。
針對 Davis Instruments，按一下此連結以提供同意。
在權限檢閱頁面上，Microsoft Entra 應用程式要求最低的「讀取使用者設定檔」權限。此權限等級足以與用於農業的資料管理員進行感應器整合。
按一下 [接受] 按鈕以授與管理員同意。
現在，請在 App Registrations 頁面的 [所有應用程式] 索引標籤下尋找 Davis Instruments WeatherLink Data Manager for Agriculture Connector (圖中以通用 Partner 表示)。
複製您想要提供存取權之特定合作夥伴應用程式的應用程式 (用戶端) 識別碼。

步驟 2: 將角色指派新增至合作夥伴應用程式

下一個步驟是在 Azure 入口網站中指派角色，以向感應器合作夥伴應用程式提供授權。用於農業的資料管理員會使用 Azure RBAC 來管理授權要求。

登入 Azure 入口網站，然後瀏覽至您建立用於農業的資料管理員資源的資源群組。

注意

在 [資源群組] 索引標籤內，如果您找不到所建立的用於農業的資料管理員資源，則必須啟用 [顯示隱藏類型] 核取方塊。

您可以在選項窗格左側找到 IAM (身分識別與存取權管理) 功能表選項，如下圖所示:

Screenshot showing role assignment.

按一下 [新增] > [新增角色指派]，此動作會在入口網站右側開啟窗格。請從下拉式清單中選擇角色:

AgFood Platform Sensor Partner Contributor - 具有感應器特定 CRU (建立、讀取、更新) 作業中的所有權限。

若要完成角色指派，請執行下列步驟:

選擇提及的角色。
在 [存取權指派對象] 區段中選擇 [使用者、群組或服務主體]。
在 [選取] 區段中貼上感應器合作夥伴應用程式名稱或識別碼 (如下圖所示)。
按一下 [儲存] 以指派角色。

Screenshot showing app selection for authorization.

此步驟可確保感應器合作夥伴應用程式已獲得用於農業的 Azure 資料管理員資源的存取權 (根據指派的角色)。

步驟 3: 啟用感應器整合

您必須在起始呼叫之前啟用感應器整合。此步驟會佈建必要的內部 Azure 資源，以在用於農業的資料管理員執行個體中整合感應器。您可以執行下列 armclient 命令來完成這項操作。

armclient patch /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>?api-version=2021-09-01-preview "{properties:{sensorIntegration:{enabled:'true'}}}"

範例輸出：

{
  "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>",
  "type": "Microsoft.AgFoodPlatform/farmBeats",
  "sku": {
    "name": "A0"
  },
  "systemData": {
    "createdBy": "<customer-id>",
    "createdByType": "User",
    "createdAt": "2022-03-11T03:36:32Z",
    "lastModifiedBy": "<customer-id>",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2022-03-11T03:40:06Z"
  },
  "properties": {
    "instanceUri": "https://<farmbeats-instance-name>.farmbeats.azure.net/",
    "provisioningState": "Succeeded",
    "sensorIntegration": {
      "enabled": "True",
      "provisioningState": "**Creating**"
    },
    "publicNetworkAccess": "Enabled"
  },
  "location": "eastus",
  "name": "myfarmbeats"
}

該作業可能需要幾分鐘的時間才能完成。若要了解作業的狀態，您可以使用下列 armclient 命令:

armclient get /subscriptions/<subscription-id>/resourceGroups/<resource-group-name> /providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>?api-version=2021-09-01-preview

若要確認狀態已完成，請查看 provisioningState 屬性。狀態必須從先前步驟的 “Creating” (建立中) 變更為 "Succeeded” (成功)。

範例輸出：

{
  "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<farmbeats-instance-name>",
  "type": "Microsoft.AgFoodPlatform/farmBeats",
  "sku": {
    "name": "A0"
  },
  "systemData": {
    "createdBy": "<customer-id>",
    "createdByType": "User",
    "createdAt": "2022-03-11T03:36:32Z",
    "lastModifiedBy": "<customer-id>",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2022-03-11T03:40:06Z"
  },
  "properties": {
    "instanceUri": "https://<customer-host-name>.farmbeats.azure.net/",
    "provisioningState": "Succeeded",
    "sensorIntegration": {
      "enabled": "True",
      "provisioningState": "**Succeeded**"
    },
    "publicNetworkAccess": "Enabled"
  },
  "tags": {
    "usage": "<sensor-partner-id>"
  },
  "location": "eastus",
  "name": "<customer-id>"
}

感應器整合步驟完成，現在您可以建立感應器整合物件。

步驟 4: 建立整合物件

使用 SensorPartnerIntegrations 集合並呼叫 SensorPartnerIntegrations_CreateOrUpdate API，為指定的感應器合作夥伴建立整合物件。感應器合作夥伴 (例如 Davis) 的每個客戶都需要在其用於農業的資料管理員資源中建立唯一的整合識別碼。

您需要評估兩個不同的路徑:

如果您是感應器合作夥伴所提供感應器的擁有者，則只要為您的感應器合作夥伴帳戶建立一個整合物件 (識別碼) 即可。
如果您的終端使用者 (也就是農民/零售商/農學家) 擁有感應器，則請為每個終端使用者建立唯一的整合物件 (識別碼)，因為每位終端使用者都有自己的感應器合作夥伴帳戶。

API 端點: PATCH /sensor-partners/{感應器合作夥伴識別碼}/integrations/{整合識別碼}

要求同意連結的區段是感應器合作夥伴整合流程的一部分。此同意連結可讓感應器合作夥伴驗證客戶是否為服務的有效使用者。感應器整合會繫結至同意金鑰。

我們的感應器合作夥伴 Davis Instruments 會使用此 UI 來設定和要求同意連結。

感應器合作夥伴會呼叫 check-consent API 端點來確認有效性。若要產生同意連結，您必須使用 SensorPartnerIntegrations_GenerateConsentLink API，並提供在步驟 (3) 中建立的整合識別碼。作為回應，您會取得名為 consentLink 的字串。請複製此字串，並將其提供給感應器合作夥伴以進行進一步驗證。如果您使用來自 Davis Instruments 的感應器，請依照此頁面 (英文) 上的指示進行。

API 端點: PATCH /sensor-partners/{感應器合作夥伴識別碼}/integrations/{整合識別碼}/: generate-consent-link

此步驟表示從客戶的觀點來看，感應器合作夥伴上線已完成。您將取得呼叫 API 端點以建立感應器模型、裝置模型、感應器與裝置所需的所有資訊。合作夥伴現在可以使用針對每個感應器識別碼產生的連接字串來推送感應器事件。

最後一個步驟是開始取用感應器事件。取用事件之前，您必須建立每個感應器識別碼與特定合作對象識別碼和資源 (欄位、季節性欄位) 的對應。

步驟 6: 建立感應器對應

使用 SensorMappings 集合，呼叫 SensorMappings_CreateOrUpdate API 來建立每個感應器的對應。對應只會將感應器識別碼與特定合作對象識別碼和資源 (欄位、季節性欄位等) 建立關聯。用於農業的資料管理員系統中已有合作對象識別碼和資源。此關聯可確保作為平台，您會以資源與合作對象維度的通用幾何為中心建立資料科學模型。每個資料來源 (衛星、天氣、農場作業) 都會繫結至合作對象與資源。當您在每個感應器層級上建立此對應物件時，您就能支援所有農學使用案例，以利用感應器資料。

API 端點: PATCH /sensor-mappings/{感應器對應識別碼}

步驟 7: 取用感應器事件

使用 SensorEvents 集合來呼叫 SensorEvents_List API，並取用您的感應器所推送的資料。您必須提供下列資訊

sensorId (指定您希望顯示哪個感應器的資料)
sensorPartnerId (指定哪個感應器合作夥伴將推送此資料)
startDateTime 與 endDateTime (時間範圍篩選可確保根據要求的時間軸切割資料)

API 端點: GET /sensor-events

下一步

請參閱這裡以測試我們的 API。

共用方式為

以客戶身分整合感應器

步驟 2: 將角色指派新增至合作夥伴應用程式

步驟 3: 啟用感應器整合

步驟 4: 建立整合物件

步驟 6: 建立感應器對應

步驟 7: 取用感應器事件

下一步

意見反應

其他資源

共用方式為

以客戶身分整合感應器

步驟 1: 識別感應器合作夥伴應用程式並提供同意

步驟 2: 將角色指派新增至合作夥伴應用程式

步驟 3: 啟用感應器整合

步驟 4: 建立整合物件

步驟 5: 產生同意連結

步驟 6: 建立感應器對應

步驟 7: 取用感應器事件

下一步

意見反應

其他資源