天氣合作夥伴與 FarmBeats 整合

本文提供 Azure FarmBeats Connector Docker 元件的相關資訊。 身為天氣資料提供者,您可以使用連接器 Docker 來與 FarmBeats 整合。 使用其 API 將天氣資料傳送至 FarmBeats。 在 FarmBeats 中,資料可用於資料融合,以及建置機器學習模型或人工智慧模型。

注意

在本文中,我們會使用 Azure 開放資料集和來自國家海洋和氣象系統管理 (NOAA) 的 Azure 開放資料集和天氣資料所建置的 參考實 作。 我們也使用對應的 Docker 映射

您必須提供 適當的 Docker 映射或程式 ,並在客戶可存取的容器登錄中裝載 Docker 映射。 為客戶提供下列資訊:

  • Docker 映射 URL
  • Docker 映射標籤
  • 用來存取 Docker 映射的金鑰或認證
  • 客戶特定的 API 金鑰或認證,以從您的系統存取資料
  • VM SKU 詳細資料 (如果您的 Docker 映射有特定的 VM 需求,請提供這些詳細資料。否則,客戶可以選擇 Azure.) 中支援的 VM SKU

客戶會使用此 Docker 資訊在其 FarmBeats 實例中註冊天氣合作夥伴。 如需客戶如何使用 Docker 在 FarmBeats 中擷取天氣資料的詳細資訊,請參閱 從天氣合作夥伴取得資料

連接器 Docker 開發

以 REST API 為基礎的整合

FarmBeats API 包含 Swagger 技術檔。

如果您已安裝 FarmBeats,請在 存取您的 FarmBeats Swagger https://yourfarmbeatswebsitename-api.azurewebsites.net/swagger

請注意, -api 會附加至您的 FarmBeats 網站名稱。 API 端點為 https://yourfarmbeatswebsitename-api.azurewebsites.net

Datahub lib

FarmBeats 提供您可以使用的 lib。 程式庫目前在 參考實作中可供使用。 稍後,它將會以 SDK 的形式提供多種語言。

驗證

使用 FarmBeats API 進行驗證

FarmBeats 使用持有人驗證。 您可以在要求的標頭區段中提供存取權杖,以存取 API。 以下為範例:

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

您可以從客戶 FarmBeats 實例上執行的Azure Functions應用程式要求存取權杖。 Azure Functions URL 會以引數的形式提供給 Docker 程式。 您可以在 URL 上提出 GET 要求,以取得存取權杖。 來自 URL 的回應包含存取權杖。

使用 Datahub lib 中的協助程式函式來取得存取權杖。 如需詳細資訊,請參閱 NOAA Docker 映射的 GitHub 頁面

存取權杖僅有效數小時。 到期時,您必須再次要求。

使用合作夥伴端 API 進行驗證

若要在 Docker 作業執行時向合作夥伴端 API 進行驗證,客戶必須在合作夥伴註冊期間提供認證。 以下為範例:

{
 "partnerCredentials": {
   "key1": "value1",
   "key2": "value2"
   }
}

API 服務會序列化此聽寫,並將其儲存在 金鑰保存庫中

Azure Data Factory是用來協調天氣作業。 它會啟動資源以執行 Docker 程式碼。 Data Factory 也提供一種機制,可將資料安全地推送至 Docker 作業執行所在的 VM。 然後,API 認證會安全地儲存在金鑰保存庫中。

認證會從金鑰保存庫讀取為安全字串。 它們會在 Docker 容器的工作目錄中以擴充屬性的形式提供。 其檔案路徑為 /mnt/working_dir/activity.json

Docker 程式碼可以在執行時間從 activity.json 讀取認證,以存取客戶的合作夥伴端 API。 在 JSON 檔案中,認證看起來像下列程式碼範例:

{ 
   "typeProperties" : {
      "extendedProperties" : { 
         "partnerCredentials": "" } 
   } 
}

認證 partnerCredentials 是以客戶在合作夥伴註冊期間提供認證的方式提供。

FarmBeats lib 提供協助程式函式。 使用這些函式從活動屬性讀取認證。 如需詳細資訊,請參閱 NOAA Docker 映射的 GitHub 頁面

只有在 Docker 程式碼正在執行時,才會使用檔案。 程式碼完成之後,會刪除檔案。

如需 Data Factory 管線和活動運作方式的詳細資訊,請參閱 架構和資料類型對應

HTTP 要求標頭

下表顯示當您對 FarmBeats 進行 API 呼叫時,需要指定的最常見要求標頭。

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

資料格式

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

Docker 規格

Docker 程式需要兩個元件:啟動程式和作業。 程式可以有多個作業。

拔靴複製法

當客戶在 FarmBeats 上啟動 Docker 註冊時,應該執行啟動程式元件。 下列引數 (arg1arg2) 傳遞至程式:

  • FarmBeats API 端點:API 要求的 FarmBeats API 端點。 此端點會對 FarmBeats 部署進行 API 呼叫。
  • Azure Functions URL:您自己的端點。 此 URL 提供 FarmBeats API 的存取權杖。 您可以在此 URL 上呼叫 GET 以擷取存取權杖。

啟動程式會建立使用者執行作業以取得天氣資料的中繼資料。 如需詳細資訊,請參閱 參考實作

如果您自訂 bootstrap_manifest.json 檔案,則參考啟動程式會為您建立必要的中繼資料。 啟動程式程式會建立下列中繼資料:

注意

如果您以參考實作所述方式更新 bootstrap_manifest.json檔案,則不需要建立下列中繼資料。 啟動程式程式會使用您的資訊清單檔案來建立必要的中繼資料。

  • /WeatherDataModel:WeatherDataModel中繼資料代表天氣資料。 它會對應至來源提供的資料集。 例如,DailyForecastSimpleModel 可能會每天提供平均溫度、濕度和濕度資訊一次。 相較之下,DailyForecastAdvancedModel 可能會每小時提供更多資訊。 您可以建立任意數目的天氣資料模型。
  • /JobType:FarmBeats 具有可延伸的作業管理系統。 身為天氣資料提供者,您會有各種資料集和 API (,例如 GetDailyForecasts) 。 您可以使用 JobType 在 FarmBeats 中啟用這些資料集和 API。 建立作業類型之後,客戶可以觸發該類型的作業,以取得其位置或其感興趣的伺服器陣列的天氣資料。

工作

每次 FarmBeats 使用者執行您在啟動程式過程中建立之 /JobType 的作業時,都會叫用 Jobs 元件。 作業的 Docker 執行命令會定義為您所建立 /JobType 的一部分。

作業會從來源擷取資料,並將其推送至 FarmBeats。 在啟動程式過程中,取得資料所需的參數應該定義為 /JobType 的一部分。

在作業過程中,程式必須根據啟動程式程式期間建立的 /WeatherDataModel 來建立 /WeatherDataLocation。 /WeatherDataLocation 會對應至使用者提供做為作業參數的位置 (緯度和經度座標) 。

物件詳細資料

WeatherDataModel 描述
名稱 天氣資料模型的名稱。
描述 模型的有意義描述。
屬性 資料提供者所定義的其他屬性。
weatherMeasures > 名稱 天氣量值的名稱。 例如,humidity_max。
weatherMeasures > DataType Double 或 Enum。 如果為 Enum,則需要 measureEnumDefinition。
weatherMeasures > measureEnumDefinition 只有在 DataType 為 Enum 時才需要。 例如, { "NoRain": 0, "Snow": 1, "Drizzle": 2, "Rain": 3 }
weatherMeasures > 類型 天氣遙測資料的類型。 例如 RelativeHumidity。 系統定義的類型為 AmbientTemperature、NoUnit、CO2、 Depth、ElectricalConductivity、LeafWetness、Length、LiquidLevel、Nitrate、O2、PH、Source、PointInTime、系統、壓力、RainGauge、RelativeHumidity、Salinity、RainMoisture、SoilTemperature、SolarRadiation、State、TimeDuration、UVRadiation、UVIndex、Volume、WindDirection、WindRun、WindSpeed、Evapotranityation 和 PAR。 若要新增更多類型,請參閱本文中的 新增 ExtendedType 一節。
weatherMeasures > Unit 天氣遙測資料的單位。 系統定義的單位為 NoUnit、攝氏、華氏、Kelvin、Rankine、Pascal、Mercury、PSI、MilliMeter、CentiMeter、Meter、Inch、Feet、Miles、KiloMeter、MilesPerHour、MilesPerSecond、 KMPerHour、KMPerSecond、MeterPerHour、MeterPerSecond、Degree、AultsPerSquareMeter、KiloWattsPerSquareMeter、MilliWattsPerSquareCentiMeter、MilliJoulesPerSquareCentiMeter、VolumetricWaterContent、Percentage、PartsPerMillion、MicroMole、MicroMolesPerLiter、MillPerSquareMeterPerMole、MilliSiemensPerCentiMeter、Centibar、DeciSiemensPerMeter、KiloPascal、VolumetricIonContent、Coffee、MilliLiter、Seconds、UnixTimestamp、MicroMolePerMeterSquaredPerSecond 和 InchesPerHour。 若要新增更多單位,請參閱本文中的 新增 ExtendedType 一節。
weatherMeasures > AggregationType 匯總的類型。 可能的值為 None、Average、Maximum、Minimum、StandardDeviation、Sum 和 Total。
weatherMeasures > Depth 感應器的深度 (公分)。 例如,地下 10 公分的濕度度量。
weatherMeasures > 描述 測量的有意義描述。
JobType 描述
名稱 作業的名稱。 例如,Get_Daily_Forecast。 客戶會執行此作業以取得天氣資料。
pipelineDetails > 參數 > 名稱 參數的名稱。
pipelineDetails > 參數 > 類型 參數類型。 可能的值包括 String、Int、Float、Bool 和 Array。
pipelineDetails > 參數 > isRequired 參數的布林值。 如果需要 參數,此值為 true。 否則,這個值便為 false。 預設值是 true。
pipelineDetails > 參數 > defaultValue 參數的預設值。
pipelineDetails > 參數 > 描述 參數的描述。
屬性 製造商的其他屬性。
Properties > programRunCommand Docker 執行命令。 當客戶執行天氣作業時,此命令就會執行。
WeatherDataLocation 描述
weatherDataModelId 啟動程式程式期間所建立之對應 WeatherDataModel 的識別碼。
location 緯度、經度和高度。
名稱 物件的名稱。
描述 天氣資料位置的描述。
farmId (伺服器陣列的選擇性) 識別碼。 客戶會提供此識別碼作為作業參數的一部分。
屬性 製造商的其他屬性。

注意

API 會針對所建立的每個實例傳回唯一識別碼。 裝置管理和元資料同步的翻譯工具必須保留此識別碼。

中繼資料同步

連接器 Docker 元件應該能夠傳送中繼資料上的更新。 例如,當天氣提供者將新參數新增至資料集,或新增新功能,例如新的 30 天預測時,它應該傳送更新。

注意

天氣資料模型中的中繼資料不支援刪除。

若要更新中繼資料,您必須呼叫 /Get/{ID} 天氣資料模型。 更新變更的屬性,然後執行 /Put/{ID} 以保留使用者設定的任何屬性。

天氣資料 (遙測) 規格

天氣資料會對應至推送至 Azure 事件中樞進行處理的正式訊息。 Azure 事件中樞是一項服務,可從連線的裝置和應用程式擷取即時資料 (遙測)。

若要將天氣資料傳送至 FarmBeats,請建立用戶端,以將訊息傳送至 FarmBeats 中的事件中樞。 如需詳細資訊,請參閱 將遙測傳送至事件中樞

下列範例 Python 程式碼會將遙測當做用戶端傳送至指定的事件中樞。

import azure
from azure.eventhub import EventHubClient, Sender, EventData, Receiver, Offset
EVENTHUBCONNECTIONSTRING = "<EventHub connection string provided by customer>"
EVENTHUBNAME = "<EventHub name provided by customer>"

write_client = EventHubClient.from_connection_string(EVENTHUBCONNECTIONSTRING, eventhub=EVENTHUBNAME, debug=False)
sender = write_client.add_sender(partition="0")
write_client.run()
for i in range(5):
    telemetry = "<Canonical telemetry message>"
    print("Sending telemetry: " + telemetry)
    sender.send(EventData(telemetry))
write_client.stop()

以下是標準訊息格式:

{
   "weatherstations": [
   {
   "id": "ID of the WeatherDataLocation.",
   "weatherdata": [
   {
     "timestamp": "Timestamp of the data. For historical purposes, this is the time for which the observations are sent. For forecast, this is the time for which data is forecasted. Format is ISO 8601. Default time zone is UTC.",
     "predictiontimestamp": "Timestamp on which the forecast data is predicted. I.e., the time of prediction. Required only for forecast data. Format is ISO 8601. Default time zone is UTC. ",
     "weathermeasurename1": <value>,
     "weathermeasurename2": <value>
     }
     ]
    }
   ]
}

以下是遙測訊息的範例:

{
   "weatherstations": [
   {
     "id": "5e4b34e7-bf9e-4f39-xxxx-f3c06d0366ea",
     "weatherdata": [
     {
      "timestamp": "2019-07-10T00:00:00Z",
      "predictiontimestamp": "2019-07-05T00:00:00Z",
      "PrecipitationTotalLiquidEquivalent": 0,
      "AvgPressure": 0,
      "AvgRelativeHumidity": 72
     }
    ] 
  }
 ]
}

疑難排解和錯誤管理

錯誤記錄

合作夥伴作業會在現有的作業架構中執行。 因此,這些錯誤會記錄與其他預先存在 FarmBeats 作業的錯誤相同的方式 (,例如 GetFarmData 和 SensorPlacement) 。 Data Factory 管線內執行的 Data Factory 活動會記錄 STDERRSTDOUT 。 這兩個檔案都可在 datahublogs-xxx FarmBeats 資源群組內的儲存體帳戶中使用。

Datahub lib 提供協助程式函式,以在整體 Datahub 記錄中啟用記錄功能。 如需詳細資訊,請參閱 NOAA Docker 映射的 GitHub 頁面

疑難排解和支援

如果客戶無法在 FarmBeats 實例中收到天氣資料,請提供支援和機制來針對問題進行疑難排解。

新增 ExtendedType

FarmBeats 支援新增感應器量值類型和單位。 您可以在參考實作中更新bootstrap_manifest.json檔案,以新增單位或類型。

請遵循下列步驟來新增 WeatherMeasure 類型,例如,一個「雪地」。

  1. GET使用查詢 filter - key = WeatherMeasureType 在 /ExtendedType 上提出要求。
  2. 請注意傳回物件的識別碼。
  3. 將新類型新增至傳回物件中的清單。 PUT在具有下列新清單的 /ExtendedType{ID} 上提出要求。 輸入承載應該與您稍早收到的回應相同。 新的單位應該附加在值清單的結尾。

下一步

現在您已擁有與 FarmBeats 整合的連接器 Docker 元件。 接下來,瞭解如何在 FarmBeats 中使用 Docker 映射 來取得天氣資料