影像合作夥伴整合

  • 發行項

本文說明如何使用 Azure FarmBeats 翻譯工具元件，將影像資料傳送至 FarmBeats。 農業影像資料可以產生自各種來源，例如多光譜相機、衛星和無人機。 農業影像合作夥伴可以與 FarmBeats 整合，為客戶提供客製化產生的農場地圖。

重要

Azure FarmBeats 已淘汰。 您可以 在這裡看到公開公告。

我們已建置新的以農業為主的新農業服務，其名稱是適用於農業的 Azure 數據管理員，現在可做為預覽服務使用。 如需詳細資訊，請參閱 這裡的 公開檔，或透過 madma@microsoft.com寫入我們。

一旦有可用的資料，即可透過 FarmBeats Accelerator 將資料視覺化，可能的用途包括資料融合和機器學習/人工智慧 (ML/AI) 模型 (由農業企業或客戶系統整合商建置)。

FarmBeats 提供下列功能：

  • 使用 /ExtendedType API 定義自訂影像類型、來源和檔案格式。
  • 透過 /Scene 和 /SceneFile API 內嵌來自各種來源的影像資料。

下列資訊的重點在於將任何形式的影像放入 FarmBeats 系統中。

選取 [無人機影像] 區段時，快顯視窗即會開啟，顯示無人機正射鑲嵌影像的高解析度影像。 您可以存取合作夥伴軟體，以軟體協助規劃無人機飛行路線並取得原始資料。 接下來可使用合作夥伴的軟體處理路徑規劃和正射鑲嵌影像影像拼接。

無人機合作夥伴需讓客戶得以將客戶帳戶連結到其在 Azure 上的 FarmBeats 執行個體。

您必須在無人機合作夥伴軟體中使用下列認證來連結 FarmBeats：

  • API 端點
  • 租用戶識別碼
  • 用戶端識別碼
  • 用戶端密碼

API 開發

這些 API 包含 Swagger 技術文件。

驗證

FarmBeats 使用 Microsoft Entra ID。 Azure App Service 提供內建驗證和授權支援。 

如需詳細資訊，請參閱 Microsoft Entra ID。   

FarmBeats Datahub 使用持有人驗證，其需要下列認證：

  • 用戶端識別碼
  • 用戶端密碼
  • 租用戶識別碼

呼叫者可以使用先前的認證來要求存取權杖，而該權杖必須在後續 API 要求中於標頭區段傳送，如下所示：

headers = {"Authorization": "Bearer " + access_token, …} 

下列 Python 程式碼範例會擷取存取權杖。 接著可以使用權杖進行對 FarmBeats 的後續 API 呼叫。

import requests
import json
import msal

# Your service principal App ID
CLIENT_ID = "<CLIENT_ID>"
# Your service principal password
CLIENT_SECRET = "<CLIENT_SECRET>"
# Tenant ID for your Azure subscription
TENANT_ID = "<TENANT_ID>"

AUTHORITY_HOST = 'https://login.microsoftonline.com'
AUTHORITY = AUTHORITY_HOST + '/' + TENANT_ID

ENDPOINT = "https://<yourfarmbeatswebsitename-api>.azurewebsites.net"
SCOPE = ENDPOINT + "/.default"

context = msal.ConfidentialClientApplication(CLIENT_ID, authority=AUTHORITY, client_credential=CLIENT_SECRET)
token_response = context.acquire_token_for_client(SCOPE)
# We should get an access token here
access_token = token_response.get('access_token')

HTTP 要求標頭

以下是對 FarmBeats Datahub 進行 API 呼叫時所需指定的最常見要求標頭。

標頭 描述及範例
Content-Type 要求格式 (Content-Type: application/<format>)。 FarmBeats Datahub API 的格式為 JSON。 Content-Type: application/json
授權 指定進行 API 呼叫所需的存取權杖。 授權：Bearer <Access-Token>
Accept 回應格式。 FarmBeats Datahub API 的格式為 JSON。 Accept: application/json

API 要求

若要提出 REST API 要求，可以結合以下項目：

  • HTTP 方法 (GET、POST 和 PUT)。
  • API 服務的 URL。
  • 資源 URI (用於查詢、提交資料、更新或刪除)。
  • 一或多個 HTTP 要求標頭。

您可選擇性地在 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\",}"

資料格式

JSON 是一種與語言無關的通用資料格式，可提供任意資料結構的簡單文字表示。 如需詳細資訊，請參閱 JSON org。

將影像內嵌至 FarmBeats

當合作夥伴取得用於連線到 FarmBeats Datahub 的認證之後，合作夥伴會在翻譯工具元件中採取下列步驟。

  1. 根據要上傳的影像類型，為下列欄位建立新的擴充類型：

    • 場景來源：例如，drone_partner_name
    • 場景類型：例如，無人機
    • 場景檔案類型：例如，葉綠素指數
    • 場景檔案內容類型：例如，影像/tiff

  2. 呼叫 /Farms API，從 Azure FarmBeats 系統內取得農場清單。

  3. 讓客戶能夠從農場清單中選擇單一農場。

    合作夥伴系統必須在合作夥伴軟體內顯示農場，才能執行路徑規劃、無人機飛行和影像收集作業。

  4. 呼叫 /Scene API 並提供必要的詳細資料，建立具有唯一場景識別碼的新場景。

  5. 接收 Blob SAS URL，依 FarmBeats 系統內所選農場的情境，將所需的影像上傳至 FarmBeats Datahub。

以下是 API 呼叫的詳細流程。

步驟 1：ExtendedType

簽入 /ExtendedType API，查看 FarmBeats 上是否有可用類型和檔案來源。 可在 /ExtendedType API 上呼叫 GET 來達成此目標。

以下是系統定義的值：

{
  "items": [
    {
      "id": "ae2aa527-7d27-42e2-8fcf-841937c651d7",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-10-25T09:47:42.5910344Z",
      "key": "SceneFileType",
      "value": [
        "evi",
        "ndvi",
        "ndwi",
        "tci",
        "soil-moisture",
        "sensor-placement",
        "sentinel-b01",
        "sentinel-b02",
        "sentinel-b03",
        "sentinel-b04",
        "sentinel-b05",
        "sentinel-b06",
        "sentinel-b07",
        "sentinel-b08",
        "sentinel-b8a",
        "sentinel-b09",
        "sentinel-b10",
        "sentinel-b11",
        "sentinel-b12",
        "cloud-mask",
        "farm-mask",
        "image/tiff",
        "orthomosaic"
      ],
      "description": "List of scene file types available in system. User can add more values."
    },
    {
      "id": "b7824d2e-3e43-46d3-8fd4-ec7ba8918d84",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-10-25T09:45:44.8914691Z",
      "key": "SceneFileContentType",
      "value": [
        "image/tiff",
        "image/png",
        "image/jpeg",
        "text/csv",
        "text/plain",
        "text/tab-separated-values",
        "application/json",
        "application/octet-stream",
        "orthomosaic"
      ],
      "description": "List of scene file content types available in system. User can add more values."
    },
    {
      "id": "21d2924d-8b3e-4ce4-a7f8-318e85c0f7f2",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-10-25T09:45:37.5096445Z",
      "key": "SceneSource",
      "value": [
        "sentinel-l1c",
        "sentinel-l2a",
        "farmbeats-model",
        "dji",
        "SlantRange-3P",
        "DJI"
      ],
      "description": "List of scene sources available in system. User can add more values."
    },
    {
      "id": "6e09ca69-cacf-4b53-b63a-53c659aae4a4",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-10-25T09:45:34.7483899Z",
      "key": "SceneType",
      "value": [
        "base-bands",
        "sensor-placement",
        "soil-moisture",
        "evi",
        "ndwi",
        "ndvi",
        "drone",
        "orthomosaic-drone"
      ],
      "description": "List of scene types available in system. User can add more values."
    },
    {
      "id": "55d8436b-3a86-4bea-87ab-e1b51226525f",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-06-17T07:32:30.1135716Z",
      "key": "SensorMeasureType",
      "value": [
        "AmbientTemperature",
        "CO2",
        "Depth",
        "ElectricalConductivity",
        "LeafWetness",
        "Length",
        "LiquidLevel",
        "Nitrate",
        "O2",
        "PH",
        "Phosphate",
        "PointInTime",
        "Potassium",
        "Pressure",
        "RainGauge",
        "RelativeHumidity",
        "Salinity",
        "SoilMoisture",
        "SoilTemperature",
        "SolarRadiation",
        "State",
        "TimeDuration",
        "UVRadiation",
        "UVIndex",
        "Volume",
        "WindDirection",
        "WindRun",
        "WindSpeed",
        "Evapotranspiration",
        "PAR"
      ],
      "description": "List of sensor measure types available in system. User can add more values."
    },
    {
      "id": "0dfd6e6b-df58-428f-9ab8-a0674bfdcbe5",
      "createdAt": "2019-06-17T07:32:30.1135716Z",
      "lastModifiedAt": "2019-06-17T07:32:30.1135716Z",
      "key": "SensorMeasureUnit",
      "value": [
        "NoUnit",
        "Celsius",
        "Fahrenheit",
        "Kelvin",
        "Rankine",
        "Pascal",
        "Mercury",
        "PSI",
        "MilliMeter",
        "CentiMeter",
        "Meter",
        "Inch",
        "Feet",
        "Mile",
        "KiloMeter",
        "MilesPerHour",
        "MilesPerSecond",
        "KMPerHour",
        "KMPerSecond",
        "MetersPerHour",
        "MetersPerSecond",
        "Degree",
        "WattsPerSquareMeter",
        "KiloWattsPerSquareMeter",
        "MilliWattsPerSquareCentiMeter",
        "MilliJoulesPerSquareCentiMeter",
        "VolumetricWaterContent",
        "Percentage",
        "PartsPerMillion",
        "MicroMol",
        "MicroMolesPerLiter",
        "SiemensPerSquareMeterPerMole",
        "MilliSiemensPerCentiMeter",
        "Centibar",
        "DeciSiemensPerMeter",
        "KiloPascal",
        "VolumetricIonContent",
        "Liter",
        "MilliLiter",
        "Seconds",
        "UnixTimestamp",
        "MicroMolPerMeterSquaredPerSecond",
        "InchesPerHour"
      ],
      "description": "List of sensor measure units available in system. User can add more values."
    }
  ]
}

這個步驟是一次性設定。 這個新場景類型的範圍僅限於安裝 Azure FarmBeats 的訂閱。

例如，若要新增 SceneSource："SlantRange"，您可以在具有金鑰 "SceneSource" 輸入承載的 /ExtendedType API 識別碼上執行 PUT。

{

      "key": "SceneSource",
      "value": [
        "sentinel-l1c",
        "sentinel-l2a",
        "farmbeats-model",
        "dji",
        "SlantRange-3P"
      ],
      "description": "List of scene sources available in system. User can add more values."
}

綠色欄位是系統定義場景來源值的新增項目。

步驟 2：取得農場詳細資料

場景 (.tiff 或 .csv 檔案) 屬於農場情境。 您必須在 /Farm API 上執行 GET 來取得農場詳細資料。 API 會傳回 FarmBeats 中可用的農場清單。 您可以選取要對其內嵌資料的農場。

GET /Farm 回應：

{
  "id": "07f3e09c-89aa-4619-8d50-e57fb083d8f9",
  "createdAt": "2019-11-01T13:55:41.8804663Z",
  "lastModifiedAt": "2019-11-01T13:55:41.8804663Z",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          78.34252251428694,
          17.402556352862675
        ],
        [
          78.34278000635095,
          17.407920852463022
        ],
        [
          78.34883106989963,
          17.40878079576528
        ],
        [
          78.3498181228054,
          17.403539173730607
        ],
        [
          78.34805859369493,
          17.39977166504127
        ],
        [
          78.34252251428694,
          17.402556352862675
        ]
      ]
    ]
  },
  "name": "Samplefarm",
  "properties": {
    "crops": "Corn",
    "address": "Sample street"
  }
}

步驟 3：建立場景識別碼 (POST 呼叫)

建立具有指定資訊的新場景 (.tiff 或 .csv 檔案)，用於提供場景相關的日期、序列和農場識別碼。 場景相關的中繼資料可以在屬性下定義，包括持續時間和量值類型。

建立新的場景即會建立與農場相關聯的新場景識別碼。 建立場景識別碼之後，使用者可以使用相同的識別碼來建立新的檔案 (.tiff 或 .csv)，並儲存檔案的內容。

/Scene API 上 POST 呼叫的範例輸入承載：

{
  "sceneId": "a0505928-c480-491b-ba31-d38285a28c1d",
  "type": "newtype",
  "contentType": "image/tiff",
  "name": "test scene file",
  "description": "test scene file description",
  "properties": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

API 回應：

{
  "id": "a0505928-c480-491b-ba31-d38285a28c1d",
  "createdAt": "2019-10-04T16:19:12.4838584Z",
  "lastModifiedAt": "2019-10-04T16:19:12.4838584Z",
  "type": "new type",
  "source": "SlantRange-3P",
  "farmId": "d41a33e7-b73e-480e-9279-0fcb3207332b",
  "date": "2019-10-04T16:13:39.064Z",
  "sequence": 5,
  "name": "test scene",
  "description": "test scene description",
  "properties": {}
}

建立場景檔案

步驟 3 中傳回的場景識別碼是場景檔案的輸入內容。 場景檔案會傳回 SAS URL 權杖，有效期為 24 小時。

如果使用者需要以程式設計方式上傳影像串流，Blob 儲存體 SDK 可以使用場景檔案識別碼、位置和 URL 來定義方法。

/SceneFile API 上 POST 呼叫的輸入承載範例：

{
  "sceneId": "a0505928-c480-491b-ba31-d38285a28c1d",
  "type": "newtype",
  "contentType": "image/tiff",
  "name": "test scene file",
  "description": "test scene file description",
  "properties": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

API 回應：

{
  "uploadSASUrl": "https://storagej2lho.blob.core.windows.net/farm-scene/2019/a0505928-c480-491b-ba31-d38285a28c1d/e91139a7-4ebd-4e2f-b17c-c677822dc840?sv=2018-03-28&sr=b&sig=%2F1426JkDcIFE5g3d%2BjOevCVMIn%2FJo9YKwBn3La5zL8Y%3D&se=2019-10-05T16%3A23%3A57Z&sp=w",
  "id": "e91139a7-4ebd-4e2f-b17c-c677822dc840",
  "createdAt": "2019-10-04T16:23:57.1192916Z",
  "lastModifiedAt": "2019-10-04T16:23:57.1192916Z",
  "blobUrl": "https://storagej2lho.blob.core.windows.net/farm-scene/2019/a0505928-c480-491b-ba31-d38285a28c1d/e91139a7-4ebd-4e2f-b17c-c677822dc840",
  "sceneId": "a0505928-c480-491b-ba31-d38285a28c1d",
  "type": "newtype",
  "contentType": "image/tiff",
  "name": "test scene file",
  "description": "test scene file description",
  "properties": {}
}

對 /SceneFile API 的 POST 呼叫會傳回 SAS 上傳 URL，其可用來使用 Azure Blob 儲存體用戶端或程式庫上傳 .csv 或 .tiff 檔案。

下一步

如需 REST API 型整合詳細資料的更多資訊，請參閱 REST API。