Freigeben über

Azure FarmBeats Clientbibliothek für Python – Version 1.0.0b2

  • Artikel

FarmBeats ist ein B2B-PaaS-Angebot von Microsoft, das es AgriFood-Unternehmen leicht macht, intelligente digitale Landwirtschaftslösungen in Azure zu erstellen. FarmBeats ermöglicht es Benutzern, landwirtschaftliche Daten aus verschiedenen Quellen (Landmaschinen, Wetter, Satellit) zu erfassen, zu aggregieren und zu verarbeiten, ohne in umfassende Datentechnikressourcen investieren zu müssen.  Kunden können SaaS-Lösungen auf Basis von FarmBeats erstellen und erstklassige Unterstützung für die Modellerstellung nutzen, um Erkenntnisse im großen Stil zu generieren.

Verwenden Sie die FarmBeats-Clientbibliothek für Python, um die folgenden Schritte auszuführen.

  • Erstellen Sie & Aktualisierungsparteien, Farmen, Felder, saisonale Felder und Grenzen.
  • Erfassen Sie Satelliten- und Wetterdaten für bereiche von Interesse.
  • Erfassen sie Betriebsdaten zu Bodenbearbeitung, Pflanzung, Ernte und Anwendung von Betriebsmitteln.

Quellcode | Paket (PyPi) | API-Referenzdokumentation | Produktdokumentation | Changelog

Erste Schritte

Voraussetzungen

Um dieses Paket verwenden zu können, benötigen Sie Folgendes:

Installieren des Pakets

Installieren Sie die Azure FarmBeats-Clientbibliothek für Python mit pip:

pip install azure-agrifood-farming

Authentifizieren des Clients

Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine Instanz des gewünschten Anmeldeinformationstyps an, der aus der Azure-Identity-Bibliothek abgerufen wird.

Um sich mit AAD zu authentifizieren, müssen Sie zuerst pip installieren azure-identity und die AAD-Authentifizierung für Ihre FarmBeats-Ressource aktivieren. Wenn Sie beim Erstellen der FarmBeats-Ressource die Installationsdokumentation befolgt haben, ist dies bereits abgedeckt.

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren:

Legen Sie die Werte der Client-ID, Mandanten-ID und geheimen Clientschlüssel der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Verwenden Sie die zurückgegebenen Tokenanmeldeinformationen, um den Client zu authentifizieren:

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)

Wichtige Begriffe

Grundlegende Kenntnisse der folgenden Begriffe helfen ihnen bei den ersten Schritten mit der FarmBeats-Clientbibliothek.

Farmhierarchie

Die Farmhierarchie ist eine Auflistung der folgenden Entitäten.

  • Partei - ist der Verwahrer aller agronomischen Daten.
  • Farm: Ist eine logische Sammlung von Feldern und/oder saisonalen Feldern. Ihnen ist kein Bereich zugeordnet.
  • Feld : Ist ein Bereich mit mehreren Polygonen. Es wird erwartet, dass dies saisonübergreifend stabil ist.
  • Saisonales Feld: Ist ein Bereich mit mehreren Polygonen. Um eine saisonale Grenze zu definieren, benötigen wir die Details zu Bereich (Grenze), Zeit (Saison) und Zuschnitt. Es wird erwartet, dass für jede Wachstumssaison neue saisonale Felder erstellt werden.
  • Begrenzung: Ist der tatsächliche Bereich mit mehreren Polygonen, der als Geometrie (in geojson) ausgedrückt wird. Es ist normalerweise einem Feld oder einem saisonalen Feld zugeordnet. Satelliten-, Wetter- und Farmbetriebsdaten sind mit einer Grenze verknüpft.
  • Kaskadierendes Löschen: Agronomische Daten werden hierarchisch mit der Partei als Stamm gespeichert. Die Hierarchie umfasst Partei -> Farmen -> Felder -> Saisonale Felder -> Grenzen -> Zugeordnete Daten (Satellit, Wetter, Farmvorgänge). Kaskadierendes Löschen bezieht sich auf den Vorgang zum Löschen eines Knotens und seiner Unterstruktur.

Szenen

Szenen beziehen sich auf Bilder, die normalerweise mithilfe von Satelliten-APIs erfasst werden. Dies umfasst Rohbänder und abgeleitete Bands (z. B. NDVI). Szenen können auch räumliche Ausgaben eines Rückschlusses oder eines AI/ML-Modells (z. B. LAI) enthalten.

Farmbetrieb

Fam-Vorgänge umfassen Details zu Bodenbearbeitung, Pflanzung, Anwendung von Pestiziden & Nährstoffen und Ernte. Dies kann entweder manuell über APIs in FarmBeats gepusht werden, oder die gleichen Informationen können von Dienstanbietern für Landmaschinen wie John Deere abgerufen werden.

Beispiele

Erstellen einer Partei

Nachdem Sie das Clientobjekt authentifiziert und erstellt haben, wie im Abschnitt Authentifizieren des Clients gezeigt, können Sie eine Partei in der FarmBeats-Ressource wie folgt erstellen:

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

Erstellen einer Farm

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

Erstellen einer Saison

Erstellen eines Season-Objekts zwischen April und August 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
        }
    )

Erstellen einer Grenze

Erstellen einer Grenze für das saisonale Feld, das im vorherigen Beispiel erstellt wurde.

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

Erfassen von Satellitenbildern

Auslösen eines Auftrags zur Satellitendatenerfassung für die oben erstellte Grenze, um Blattbereichsindexdaten für den Monat Januar 2020 zu erfassen. Dies ist ein Vorgang mit langer Ausführung (auch als "Auftrag" bezeichnet) und gibt ein Poller-Objekt zurück. Beim Aufrufen der .result() Methode für das Abfrageobjekt wird gewartet, bis der Vorgang beendet wird, und gibt den endgültigen Status zurück.

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

Abrufen von erfassten Satellitenszenen

Abfragen nach den Szenen, die vom Auftrag im vorherigen Beispiel erstellt wurden.

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

Problembehandlung

Allgemein

Der FarmBeats-Client löst die in [Azure Core][azure_core] definierten Ausnahmen aus, wenn Sie Ihre Antworten aufrufen .raise_for_status() .

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine ausführliche Protokollierung auf der Ebene DEBUG, einschließlich Anforderungs-/Antworttexten und vollständiger Header, kann auf einem Client mit dem Schlüsselwortargument logging_enable aktiviert werden:

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 Auf ähnliche Weise kann die detaillierte Protokollierung für einen einzelnen Aufruf aktiviert werden, auch wenn er für den Client nicht aktiviert ist:

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

Nächste Schritte

Zusätzliche Dokumentation

Ausführlichere Dokumentationen zu FarmBeats finden Sie in der FarmBeats-Dokumentation auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.