Azure FarmBeats Python客户端库

FarmBeats是微软提供的一种B2B PaaS服务，使AgriFood公司能够在Azure上轻松构建智能数字农业解决方案。FarmBeats允许用户从各种来源（农业设备、天气、卫星）获取、聚合和处理农业数据，而无需投资深度数据工程资源。客户可以在FarmBeats之上构建SaaS解决方案，并利用一流的模型构建支持，以规模生成洞察。

使用Python客户端库进行以下操作。

• 创建和更新当事人、农场、田地、季节性田地和边界。
• 获取感兴趣区域的卫星和天气数据。
• 获取涵盖耕作、种植、收获和农田投入应用的农业运营数据。

源代码 | 包（PyPi） | API参考文档 | 产品文档 | 变更日志

入门指南

先决条件

要使用此包，您必须具备

• Azure订阅 - 创建免费账户
• Azure FarmBeats资源 - 安装FarmBeats
• 3.6或更高版本 - 安装Python

安装包

使用

pip

安装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）表示。它通常与字段或季节性字段相关联。卫星、天气和农场运营数据与边界相关联。
• 级联删除 - 农学数据以层次结构方式存储，当事人作为根。该层次结构包括当事人 -> 农场 -> 字段 -> 季节性字段 -> 边界 -> 相关数据（卫星、天气、农场运营）。级联删除是指删除任何节点及其子树的过程。

场景

场景通常是指通过卫星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月。

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对象。在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级别记录。

启用详细DEBUG级别日志记录，包括请求/响应正文和未编辑的标头，可以使用带有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开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过opencode@microsoft.com联系以获取任何额外的问题或评论。

发行历史

1.0.0b2 (2023-02-23)

新增功能

• 添加了用于传感器集成的客户端，包括对DeviceDataModels、Devices、SensorDataModels、Sensors、SensorMappings、SensorPartnerIntegration的crud操作，并获取传感器事件。
• 添加了STAC搜索和获取功能的新API
• 将breedingMethods和Measurements作为Crop实体的部分添加
• 将geographicIdentifier作为Season实体的部分添加
• 将trait、relativeMeasurements和treatments作为CropVariety实体的部分添加
• 将type、crs、centroid和bbox（几何形状的边界框）作为Boundary实体的部分添加
• 在Farmer、Farm、Field、Seasonal Field、Boundary、Crop、Crop variety、Season和Attachment中添加Source字段
• 所有实体的CreatedBy和ModifiedBy
• Prescription & Crop中的Measure重命名为measurements
• Boundary中的Acreage重命名为area
• Sentinel 2 L2A和Sentinel 2 L1C STAC集合的Get Feature和Search Feature API
• 添加Weather Data API以获取IBM天气数据

重大更改

• 从Field和Seasonal Field中删除primaryBoundaryId & boundaryIds
• 从边界移除isPrimary标志
• 从季节性字段移除avgYields
• 将Farmer重命名为Party
• 将CropVariety重命名为CropProduct
• 更新依赖关系从azure-core<2.0.0,>=1.2.2到azure-core<2.0.0,>=1.24.0

其他更改

• Python 2.7不再受支持。请使用Python 3.6或更高版本。

1.0.0b1 (2021-05-25)

• 这是Azure AgriFood Farming库的初始版本。