Azure FarmBeats適用于 Python 的用戶端程式庫 - 1.0.0b2 版

發行項
04/05/2023

FarmBeats 是 Microsoft 提供的 B2B PaaS 供應專案，可讓您輕鬆地在 Azure 上建立智慧型數位農業解決方案。 FarmBeats 可讓使用者從各種來源取得、匯總及處理各種來源的農業資料， (伺服器陣列設備、天氣、衛星) ，而不需要投資深層資料工程資源。  客戶可以在 FarmBeats 之上建置 SaaS 解決方案，並運用模型建置的第一級支援，以大規模產生見解。

使用適用于 Python 的 FarmBeats 用戶端程式庫來執行下列動作。

建立 & 更新物件、伺服器陣列、欄位、季節性欄位和界限。
擷取相關區域的衛星和天氣資料。
擷取伺服器陣列作業資料，涵蓋直到、植物、收集及套用伺服器陣列輸入。

| 原始程式碼套件 (PyPi) | API 參考檔 | 產品檔 | Changelog

開始使用

Prerequisites

若要使用此套件，您必須具備：

Azure 訂用帳戶 - 建立免費帳戶
Azure FarmBeats資源 -安裝 FarmBeats
3.6 或更新版本 - 安裝 Python

安裝套件

使用pip安裝適用于 Python 的Azure FarmBeats用戶端程式庫：

pip install azure-agrifood-farming

驗證用戶端

若要使用 Azure Active Directory (AAD) 權杖認證，請提供從 azure 身分識別程式庫取得所需認證類型的實例。

若要使用 AAD 進行驗證，您必須先在 FarmBeats 資源上安裝 azure-identity 並啟用 AAD 驗證。如果您在建立 FarmBeats 資源時遵循安裝檔，則已涵蓋這一點。

安裝之後，您可以選擇要使用的 azure.identity 認證類型。例如， DefaultAzureCredential 可用來驗證用戶端：

將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

使用傳回的權杖認證來驗證用戶端：

from azure.agrifood.farming import FarmBeatsClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

重要概念

以下詞彙的基本瞭解有助於開始使用 FarmBeats 用戶端程式庫。

伺服器陣列階層

伺服器陣列階層是下列實體的集合。

合作物件 - 是所有氣象資料的監管人。
伺服器陣列 - 是欄位和/或季節性欄位的邏輯集合。它們沒有任何與其相關聯的區域。
Field - 是多多邊形區域。這預期會在各種不同時間保持穩定。
季節性欄位 - 是多多邊形區域。若要定義季節性界限，我們需要區域 (界限) 、時間 () 和裁剪的詳細資料。新的季節性欄位預期會針對每個成長的季建立。
界限 - 是在 geojson) 中以幾何 (表示的實際多多邊形區域。它通常與欄位或季節性欄位相關聯。衛星、天氣和伺服器陣列作業資料會連結至界限。
串聯刪除 - 以階層方式儲存多方做為根目錄的元組資料。階層包含合作物件 - 伺服器陣列 - > 欄位 > - > 季節性欄位 - > 界限 - > 相關資料 (衛星、天氣、伺服器陣列作業) 。串聯刪除是指刪除任何節點及其子樹的程式。

場景

場景是指通常會使用衛星 API 內嵌的影像。這包括原始訊號和衍生的頻 (例如：NDVI) 。場景也可能包含推斷或 AI/ML 模型的空間輸出 (，例如：LAI) 。

伺服器陣列作業

Fam 作業包含有關除法、植物、植物應用 & 及收集的詳細資料。這可以使用 API 手動推送至 FarmBeats，或從 John Deere 等伺服器陣列設備服務提供者提取相同的資訊。

範例

建立合作物件

驗證並建立用戶端物件之後，如驗證用戶端一節所示，您可以在 FarmBeats 資源內建立合作物件，如下所示：

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

party_id = "party-1"

party = client.parties.create_or_update(
    party_id=party_id,
    party={
        "name": party_name,
        "description": party_description
    }
)

建立伺服器陣列

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

party_id = "party-1" # Using party from previous example

farm = client.farms.create_or_update(
    party_id=party_id,
    farm_id="farm-1",
    farm={
        "name": farm_name,
        "description": farm_description
    }
)

建立季

建立從 2021 年 4 月到 8 月的 Season 物件。

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

season_id = "contoso-season"
season_name = "contoso-season-name"
season_description = "contoso-season-description"
year = "2021"
start_date_time = "2021-01-01T20:08:10.137Z"
end_date_time = "2021-06-06T20:08:10.137Z"

season = client.seasons.create_or_update(
        season_id=season_id,
        season={
            "name": season_name,
            "year": year,
            "startDateTime": start_date_time,
            "endDateTime": end_date_time,
            "description": season_description
        }
    )

建立界限

為在上述範例中建立的季節性欄位建立界限。

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

party_id = "party-1"
boundary_id = "boundary-1"

boundary = client.boundaries.create_or_update(
    party_id=party_id,
    boundary_id=boundary_id,
    boundary={
        "geometry": {
            "type": "Polygon",
            "coordinates":
                [
                    [
                        [73.70457172393799, 20.545385304358106],
                        [73.70457172393799, 20.545385304358106],
                        [73.70448589324951, 20.542411534243367],
                        [73.70877742767334, 20.541688176010233],
                        [73.71023654937744, 20.545083911372505],
                        [73.70663166046143, 20.546992723579137],
                        [73.70457172393799, 20.545385304358106],
                    ]
                ]
        },
        "status": "<string>",
        "name": "<string>",
        "description": "<string>"
    }
)

擷取衛星影像

針對上面建立的界限觸發附屬資料擷取作業，以擷取 2020 年 1 月的分葉區域索引資料。這是長時間執行的作業 (也稱為「作業」) ，並傳回 Poller 物件。 .result()在輪詢器物件上呼叫方法會等候作業終止，並傳回最終狀態。

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

from isodate.tzinfo import Utc
from datetime import datetime

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

party_id = "party-1"
boundary_id = "westlake-boundary-1"
start_date_time = "2021-01-01T20:08:10.137Z"
end_date_time = "2021-06-06T20:08:10.137Z"

# Queue the job
satellite_job_poller = client.scenes.begin_create_satellite_data_ingestion_job(
    job_id=job_id,
    job={
        "boundaryId": boundary_id,
        "endDateTime": end_date_time,
        "partyId": party_id,
        "startDateTime": start_date_time,
        "provider": "Microsoft",
        "source": "Sentinel_2_L2A",
        "data": {
            "imageNames": [
                "NDVI"
            ],
            "imageFormats": [
                "TIF"
            ],
            "imageResolution": [10]
        },
        "name": "<string>",
        "description": "<string>"
    }
)

# Wait for the job to terminate
satellite_job = satellite_job_poller.result()
job_status = satellite_job_poller.status()

取得擷取的衛星場景

查詢上一個範例中作業所建立的場景。

from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient

from datetime import datetime

credential = DefaultAzureCredential()
client = FarmBeatsClient(endpoint="https://<my-account-name>.farmbeats.azure.net", credential=credential)

party_id = "party-1"
boundary_id = "boundary-1"

scenes = client.scenes.list(
    party_id=party_id,
    boundary_id=boundary_id,
    start_date_time=start_date_time,
    end_date_time=end_date_time,
    provider="Microsoft",
    source="Sentinel_2_L2A"
)

for scene in scenes:
    bands = [image_file["name"] for image_file in scene["imageFiles"]]
    bands_str = ", ".join(bands)
    print(f"Scene has the bands {bands_str}")

疑難排解

一般

如果您在回應上呼叫 .raise_for_status() ，FarmBeats 用戶端將會引發 [Azure Core][azure_core] 中定義的例外狀況。

記錄

此程式庫會使用標準記錄程式庫進行記錄。 HTTP 會話的基本資訊 (URL、標頭等) 會記錄在 INFO 層級。

您可以在具備 logging_enable 關鍵字引數的用戶端啟用詳細的「偵錯」層級記錄，包括要求/回應本文和未刪改的標頭：

import sys
import logging
from azure.identity import DefaultAzureCredential
from azure.agrifood.farming import FarmBeatsClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
endpoint = "https://<my-account-name>.farmbeats.azure.net"
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = FarmBeatsClient(endpoint=endpoint, credential=credential, logging_enable=True)

同樣地， logging_enable 也可以啟用單一呼叫的詳細記錄，即使用戶端未啟用它：

client.crops.get(crop_id="crop_id", logging_enable=True)

下一步

其他文件

如需 FarmBeats 的詳細資訊檔，請參閱有關 docs.microsoft.com 的 FarmBeats 檔。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 cla.microsoft.com。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為