Azure FarmBeats klientbibliotek för Python – version 1.0.0b2

Artikel
04/05/2023

FarmBeats är ett B2B PaaS-erbjudande från Microsoft som gör det enkelt för AgriFood-företag att skapa intelligenta digitala jordbrukslösningar på Azure. FarmBeats gör det möjligt för användare att hämta, aggregera och bearbeta jordbruksdata från olika källor (jordbruksutrustning, väder, satellit) utan att behöva investera i djupa datateknikresurser.  Kunder kan skapa SaaS-lösningar ovanpå FarmBeats och utnyttja förstklassigt stöd för modellskapande för att generera insikter i stor skala.

Använd FarmBeats-klientbiblioteket för Python för att göra följande.

Skapa & uppdateringsfester, grupper, fält, säsongsfält och gränser.
Mata in satellit- och väderdata för intressanta områden.
Mata in driftdata för servergruppen som omfattar jordfräsning, plantering, avverkning och tillämpning av indata från jordbruksföretaget.

| Källkod Paket (PyPi) | API-referensdokumentation | Produktdokumentation | Ändringsloggen

Komma igång

Förutsättningar

Om du vill använda det här paketet måste du ha:

Azure-prenumeration – Skapa ett kostnadsfritt konto
Azure FarmBeats resurs – Installera FarmBeats
3.6 eller senare – Installera Python

Installera paketet

Installera Azure FarmBeats-klientbiblioteket för Python med pip:

pip install azure-agrifood-farming

Autentisera klienten

Om du vill använda en AAD-tokenautentisering (Azure Active Directory) anger du en instans av önskad typ av autentiseringsuppgifter som hämtats från biblioteket azure-identity .

Om du vill autentisera med AAD måste du först installera azure-identity och aktivera AAD-autentisering på din FarmBeats-resurs. Om du följde installationsdokumenten när du skapade FarmBeats-resursen omfattas detta redan.

Efter installationen kan du välja vilken typ av autentiseringsuppgifter från azure.identity som ska användas. Till exempel kan DefaultAzureCredential användas för att autentisera klienten:

Ange värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Använd den returnerade tokenautentiseringsuppgiften för att autentisera klienten:

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)

Viktiga begrepp

Grundläggande förståelse av villkoren nedan hjälper dig att komma igång med FarmBeats-klientbiblioteket.

Grupphierarki

Servergruppshierarkin är en samling med nedanstående entiteter.

Part – är förmyndare för alla agronomiska data.
Servergrupp – är en logisk samling fält och/eller säsongsfält. De har inget område som är associerat med dem.
Field – är ett område med flera polygoner. Detta förväntas vara stabilt över säsonger.
Säsongsfält – är ett område med flera polygoner. För att definiera en säsongsgräns behöver vi information om arean (gränsen), tiden (säsongen) och grödan. Nya säsongsfält förväntas skapas för varje odlingssäsong.
Gräns – är det faktiska multipolygonområdet uttryckt som en geometri (i geojson). Det är vanligtvis associerat med ett fält eller ett säsongsfält. Data om satellit-, väder- och gårdsåtgärder är kopplade till en gräns.
Kaskadborttagning – Agronomiska data lagras hierarkiskt med part som rot. Hierarkin innehåller Party -> Farms -> Fields -> Seasonal Fields -> Boundaries -> Associated data (satellite, weather, farm operations). Kaskadborttagning syftar på processen att ta bort en nod och dess underträd.

Scener

Scener refererar till bilder som normalt matas in med hjälp av satellit-API:er. Detta inkluderar råband och härledda band (t.ex. NDVI). Scener kan också innehålla rumsliga utdata från en slutsatsdragning eller AI/ML-modell (t.ex. LAI).

Servergruppsåtgärder

Fam-verksamheten innehåller information om jordfräsning, plantering, tillämpning av bekämpningsmedelsnäring & och skörd. Detta kan antingen skickas manuellt till FarmBeats med hjälp av API:er eller så kan samma information hämtas från leverantörer av servergruppsutrustningstjänster som John Deere.

Exempel

Skapa en part

När du har autentiserat och skapat klientobjektet enligt beskrivningen i avsnittet Autentisera klienten kan du skapa en part i FarmBeats-resursen så här:

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

Skapa en servergrupp

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

Skapa en säsong

Skapa ett Season-objekt som sträcker sig från april till augusti 2021.

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

Skapa en gräns

Skapa en gräns för det säsongsbaserade fältet som skapades i föregående exempel.

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

Mata in satellitbilder

Utlöser ett satellitdatainmatningsjobb för gränsen som skapades ovan för att mata in lövområdesindexdata för januari 2020. Det här är en tidskrävande åtgärd (kallas även ett jobb) och returnerar ett Poller-objekt. .result() Om du anropar metoden i pollerobjektet väntar du på att åtgärden ska avslutas och returnerar den slutliga statusen.

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()

Hämta inmatade satellitscener

Fråga efter de scener som skapades av jobbet i föregående exempel.

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

Felsökning

Allmänt

FarmBeats-klienten genererar undantag som definierats i [Azure Core][azure_core] om du anropar .raise_for_status() på dina svar.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade rubriker, kan aktiveras på en klient med nyckelordsargumentet 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 På samma sätt kan aktivera detaljerad loggning för ett enda anrop, även om det inte är aktiverat för klienten:

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

Nästa steg

Ytterligare dokumentation

Mer omfattande dokumentation om FarmBeats finns i FarmBeats-dokumentationen på docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Share via