Azure FarmBeats API
本文將說明 Azure FarmBeats API。 Azure FarmBeats API 以 JSON 架構回應提供標準化 RESTful 介面，協助您運用 Azure FarmBeats 功能，例如：
重要
Azure FarmBeats 已淘汰。 您可以 在這裡看到公開公告。
我們已建置新的農業焦點服務，其名稱為適用於農業的 Azure 數據管理員，現在可做為預覽服務使用。 如需詳細資訊，請參閱 此處 的公開檔，或在此 madma@microsoft.com寫入我們。
- 用來取得感應器、相機、無人機、天氣、衛星和策劃地面資料的 API。
- 常見資料提供者的資料正規化和內容化。
- 所有內嵌資料的架構化存取和查詢功能。
- 根據農業特徵自動產生可查詢的中繼資料。
- 自動產生時間序列彙總，以快速建置模型。
- 整合式 Azure Data Factory 引擎，輕鬆建置自訂資料處理管線。
XBOX Video Application Development
FarmBeats API 包含 Swagger 技術文件。
下表摘要說明 FarmBeats Datahub 中的所有物件和資源：
| 物件和資源 | 描述 |
|---|---|
| Farm | Farm 會對應至 FarmBeats 系統中關注點的實體位置。 每個農場都有農場名稱和唯一的農場識別碼。 |
| 裝置 | Device 會對應至存在於伺服器陣列上的實體裝置。 每個裝置都有唯一的裝置識別碼。 裝置通常會佈建至具有農場識別碼的農場。 |
| DeviceModel | DeviceModel 會對應至裝置的中繼資料，例如製造商和裝置類型 (閘道或節點)。 |
| Sensor | Sensor 會對應至記錄值的實體感應器。 感應器通常會使用裝置識別碼連線到裝置。 |
| SensorModel | SensorModel 會對應至感應器的中繼資料，例如製造商、感應器類型 (類比或數位)，以及感應器量值 (例如環境溫度和壓力)。 |
| 遙測 | 遙測可讓您讀取特定感應器和時間範圍的遙測訊息。 |
| 作業 | Job 會對應至 FarmBeats 系統中所執行活動的任何工作流程，以取得預期輸出。 每個作業都會與作業識別碼和作業類型相關聯。 |
| JobType | JobType 會對應至系統支援的不同作業類型。 系統定義和使用者定義的作業類型皆包含在其中。 |
| ExtendedType | ExtendedType 會對應至系統中的系統定義與使用者定義類型清單。 ExtendedType 有助於在 FarmBeats 系統中設定新的感應器、場景或場景檔案類型。 |
| Partner | Partner 會對應至 FarmBeats 的感應器和意象整合合作夥伴。 |
| 場景 | Scene 會對應至農場環境中產生的任何輸出。 每個場景都有一個場景識別碼、場景來源、場景類型和與其相關聯的農場識別碼。 每個場景識別碼都可以有多個與其相關聯的場景檔案。 |
| SceneFile | SceneFile 會對應至針對單一場景產生的所有檔案。 單一場景識別碼可以有多個與其相關聯的 SceneFile 識別碼。 |
| 規則 | Rule 會對應至農場相關資料的條件，以觸發警示。 每個規則都在農場資料的內容中。 |
| 警示 | Alert 會對應至符合規則條件時產生的通知。 每個警示都在規則的內容中。 |
| RoleDefinition | RoleDefinition 會定義允許和不允許的角色動作。 |
| RoleAssignment | RoleAssignment 會對應至指派給使用者或服務主體的角色指派。 |
資料格式
JSON 是一種與語言無關的通用資料格式，可提供任意資料結構的簡單文字表示。 如需詳細資訊，請參閱 JSON 網站。
驗證和授權
REST API 的 HTTP 要求會受到 Microsoft Entra ID 保護。 若要向 REST API 提出驗證的要求，用戶端程式碼必須先使用有效的認證進行驗證，才能呼叫 API。 驗證會透過 Microsoft Entra ID 協調各種動作專案。 然後為您的用戶端提供存取權杖作為驗證證明。 權杖接著會在 REST API 要求的 HTTP 授權標頭中傳送。 若要深入瞭解 Microsoft Entra 驗證，請參閱開發人員 Microsoft Entra ID。
此存取權杖必須在後續 API 要求的標頭區段中傳送，如下所示：
headers = {"Authorization": "Bearer " + **access_token**}
HTTP 要求標頭
以下是對 Azure FarmBeats Datahub 進行 API 呼叫時必須指定的最常見要求標頭。
| 標頭 | 描述及範例 |
|---|---|
| Content-Type | 要求格式 (Content-Type: application/<format>)。 Azure FarmBeats Datahub API 的格式為 JSON。 Content-Type: application/json |
| 授權 | 指定進行 API 呼叫所需的存取權杖。 授權：Bearer <Access-Token> |
| Accept | 回應格式。 Azure FarmBeats Datahub API 的格式為 JSON。 Accept: application/json |
API 要求
若要提出 REST API 要求，您可結合 HTTP (GET、POST、PUT 或 DELETE) 方法；API 服務的 URL、用以查詢、提交資料、更新或刪除的資源 URI，然後新增一個或多個 HTTP 要求標頭。
API 服務的 URL 是 Datahub URL，例如 https://<yourdatahub-website-name>.azurewebsites.net。
您可選擇性地在 GET 呼叫上包含查詢參數來篩選回應中的資料、限制其大小及進行排序。
下列範例要求用於取得裝置清單：
curl -X GET "https://microsoft-farmbeats.azurewebsites.net/Device" -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>”
大多數 GET、POST 和 PUT 呼叫都需要 JSON 要求本文。
下列範例要求會建立裝置。 此要求有輸入 JSON 和要求本文。
curl -X POST "https://microsoft-farmbeats.azurewebsites.net/Device" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>" -d "{ \"deviceModelId\": \"ID123\", \"hardwareId\": \"MHDN123\", \"reportingInterval\": 900, \"name\": \"Device123\", \"description\": \"Test Device 123\",}"
查詢參數
針對 REST GET 呼叫，您可以藉由在要求 URI 上加入一個或多個查詢參數，來對 API 回應執行篩選、資料大小限制及資料排序。 如需查詢參數，請參閱 API 文件和個別 GET 呼叫。 例如，當您查詢裝置清單時 (/Device 上的 GET 呼叫)，可以指定下列查詢參數：
錯誤處理
Azure FarmBeats Datahub API 會傳回標準 HTTP 錯誤。 最常見的錯誤碼如下：
| 錯誤碼 | 描述 |
|---|---|
| 200 | Success |
| 201 | 建立 (Post) 成功 |
| 400 | 不正確的要求。 要求中發生錯誤。 |
| 401 | 未經授權。 API 的呼叫端未獲授權存取資源。 |
| 404 | 找不到資源 |
| 5XX | 內部伺服器錯誤。 以 5XX 開頭的錯誤碼表示伺服器上發生一些錯誤。 如需詳細資訊，請參閱伺服器記錄和下一節。 |
除了標準 HTTP 錯誤之外，Azure FarmBeats Datahub API 也會以下列格式傳回內部錯誤：
{
"message": "<More information on the error>",
"status": "<error code>”,
"code": "<InternalErrorCode>",
"moreInfo": "<Details of the error>"
}
在此範例中，建立農場時，輸入承載中未指定強制欄位 [名稱]。 產生的錯誤訊息為：
{
"message": "Model validation failed",
"status": 400,
"code": "ModelValidationFailed",
"moreInfo": "[\"The Name field is required.\"]"
}
將使用者或應用程式註冊新增至 Microsoft Entra ID
Azure FarmBeats API 可由使用者或 Microsoft Entra ID 中的應用程式註冊來存取。 若要在 Microsoft Entra ID 中建立應用程式註冊，請遵循下列步驟：
移至 Azure 入口網站，然後選取 [Microsoft Entra ID>>應用程式註冊[新增註冊]。 或者，您可以使用現有帳戶。
針對新的帳戶，請執行下列動作：
- 輸入名稱。
- 選取 [僅限此組織目錄中的帳戶 (單一租用戶)]。
- 在其餘的欄位中使用預設值。
- 選取 [註冊]。
在新的和現有的應用程式註冊 [概觀] 窗格上，執行下列動作：
- 擷取用戶端識別碼和租用戶識別碼。
- 移至 [憑證和祕密] 以產生新的用戶端密碼，並擷取用戶端密碼。
- 返回至 [概觀]，然後選取 [在本機目錄中管理應用程式] 旁的連結。
- 移至 [屬性] 以擷取物件識別碼。
移至 Datahub Swagger (
https://<yourdatahub>.azurewebsites.net/swagger/index.html) 並執行下列動作：- 前往 RoleAssignment API。
- 執行 POST，為剛才建立的物件識別碼建立 RoleAssignment 物件。
{
"roleDefinitionId": "a400a00b-f67c-42b7-ba9a-f73d8c67e433",
"objectId": "objectId from step 3 above",
"objectIdType": "ServicePrincipalId",
"tenantId": "tenant id of your Azure subscription"
}
注意
如需如何新增使用者和 Active Directory 註冊的詳細資訊，請參閱 Microsoft Entra ID。
完成上述步驟之後，您的應用程式註冊 (用戶端) 可以透過持有人驗證使用存取權杖來呼叫 Azure FarmBeats API。
使用存取權杖在後續 API 要求的標頭區段中傳送，如下所示：
headers = {"Authorization": "Bearer " + **access_token**, "Content-Type" : "application/json" }