Python 用Azure FarmBeats クライアント ライブラリ - バージョン 1.0.0b2

  • [アーティクル]

FarmBeats は、AgriFood 企業が Azure でインテリジェントなデジタル農業ソリューションを簡単に構築できるようにする、Microsoft の B2B PaaS オファリングです。 FarmBeats を使用すると、ユーザーは、深いデータ エンジニアリング リソースに投資することなく、さまざまなソース (農業機器、気象、衛星) から農業データを取得、集計、および処理できます。  お客様は、FarmBeats の上に SaaS ソリューションを構築し、モデル構築に対するファースト クラスのサポートを利用して、大規模な分析情報を生成できます。

Python 用 FarmBeats クライアント ライブラリを使用して、次の操作を行います。

  • 更新パーティ、ファーム、フィールド、季節フィールド、境界を作成 & します。
  • 関心のある領域の衛星データと気象データを取り込む。
  • 耕作、植え付け、収穫、および農場の入力の適用をカバーする農場の操作データを取り込む。

ソースコード | パッケージ (PyPi) | API リファレンス ドキュメント | 製品ドキュメント | Changelog

作業の開始

前提条件

このパッケージを使用するには、次が必要です。

パッケージをインストールする

pip を使用して Python 用Azure FarmBeats クライアント ライブラリをインストールします。

pip install azure-agrifood-farming

クライアントを認証する

Azure Active Directory (AAD) トークン資格情報を使用するには、azure-identity ライブラリから取得した目的の資格情報の種類のインスタンスを指定します。

AAD で認証するには、まず pip をインストール azure-identity し、FarmBeats リソースで AAD 認証を有効にする必要があります。 FarmBeats リソースの作成時に インストール ドキュメント に従った場合は、既に説明されています。

セットアップ後、使用する azure.identity から 資格情報 の種類を選択できます。 たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。

AAD アプリケーションのクライアント ID、テナント ID、クライアント シークレットの値を環境変数として設定します(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 クライアント ライブラリの使用を開始するのに役立ちます。

ファーム階層

ファーム階層は、以下のエンティティのコレクションです。

  • パーティ - すべての農業データのカストディアンです。
  • ファーム - フィールドや季節フィールドの論理コレクションです。 それらに関連付けられている領域がありません。
  • フィールド - マルチポリゴン領域です。 これは季節を越えて安定することが期待されます。
  • 季節フィールド - マルチポリゴンエリアです。 季節の境界を定義するには、領域 (境界)、時間 (季節)、およびトリミングの詳細が必要です。 新しい季節のフィールドは、成長する季節ごとに作成される予定です。
  • 境界 - ジオメトリとして表現される実際のマルチポリゴン領域 (geojson 内)。 通常、フィールドまたは季節フィールドに関連付けられます。 衛星、気象、および農場の運用データは境界にリンクされます。
  • 連鎖削除 - 農業データは、パーティをルートとして階層的に格納されます。 階層には、パーティ -> ファーム - フィールド -> 季節フィールド -> 境界 ->> 関連データ (サテライト、気象、ファーム操作) が含まれます。 連鎖削除は、ノードとそのサブツリーを削除するプロセスを指します。

Scenes

シーンは、通常、サテライト API を使用して取り込まれた画像を指します。 これには、生バンドと派生バンド (例: NDVI) が含まれます。 シーンには、推論または AI/ML モデル (例: LAI) の空間出力が含まれる場合もあります。

ファーム操作

ファムの事業には、耕作、植栽、農薬 & 栄養素の適用、収穫に関する詳細が含まれます。 これは、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() poller オブジェクトで メソッドを呼び出すと、操作が終了するまで待機し、最終的な状態が返されます。

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}")

トラブルシューティング

全般

FarmBeats クライアントは、応答で を呼び出 .raise_for_status() すと、[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 クライアントで有効になっていない場合でも、1 回の呼び出しに対して詳細なログ記録を有効にすることができます。

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

次のステップ

その他のドキュメント

FarmBeats の詳細なドキュメントについては、docs.microsoft.com に関 する FarmBeats のドキュメントを参照してください 。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。