bibliothèque cliente Azure FarmBeats pour Python - version 1.0.0b2

Article
04/05/2023

FarmBeats est une offre PaaS B2B de Microsoft qui permet aux entreprises agroalimentaires de créer facilement des solutions d’agriculture numérique intelligentes sur Azure. FarmBeats permet aux utilisateurs d’acquérir, d’agréger et de traiter des données agricoles provenant de diverses sources (équipement agricole, météo, satellite) sans avoir à investir dans des ressources d’ingénierie des données approfondies.  Les clients peuvent créer des solutions SaaS sur FarmBeats et tirer parti d’une prise en charge de première classe pour la génération de modèles pour générer des insights à grande échelle.

Utilisez la bibliothèque cliente FarmBeats pour Python pour effectuer les opérations suivantes.

Créez & des parties de mise à jour, des batteries de serveurs, des champs, des champs saisonniers et des limites.
Ingérer des données satellites et météorologiques pour les zones d’intérêt.
Ingérer des données d’exploitation agricole couvrant le labourage, la plantation, la récolte et l’application d’intrants agricoles.

| Code source Package (PyPi) | Documentation de référence sur les | API | Documentation produit Changelog

Prise en main

Prérequis

Pour utiliser ce package, vous devez disposer des éléments suivants :

Abonnement Azure - Créer un compte gratuit
ressource Azure FarmBeats - Installer FarmBeats
3.6 ou version ultérieure - Installer Python

Installer le package

Installez la bibliothèque cliente Azure FarmBeats pour Python avec pip :

pip install azure-agrifood-farming

Authentifier le client

Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenue à partir de la bibliothèque azure-identity .

Pour vous authentifier auprès d’AAD, vous devez d’abord installer azure-identity et activer l’authentification AAD sur votre ressource FarmBeats. Si vous avez suivi les documents d’installation lors de la création de la ressource FarmBeats, cela est déjà couvert.

Après l’installation, vous pouvez choisir le type d’informations d’identification d’azure.identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client :

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Utilisez les informations d’identification de jeton retournées pour authentifier le client :

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)

Concepts clés

La compréhension de base des termes ci-dessous vous aidera à démarrer avec la bibliothèque cliente FarmBeats.

Hiérarchie de batterie de serveurs

La hiérarchie de batterie est une collection d’entités ci-dessous.

Partie - est le dépositaire de toutes les données agronomiques.
Batterie de serveurs : collection logique de champs et/ou de champs saisonniers. Ils n’ont aucune zone associée à eux.
Champ : est une zone à plusieurs polygones. On s’attend à ce que ce soit stable au fil des saisons.
Champ saisonnier : est une zone à plusieurs polygones. Pour définir une limite saisonnière, nous avons besoin des détails de la zone (limite), de l’heure (saison) et de la culture. On s’attend à ce que de nouveaux champs saisonniers soient créés pour chaque saison de croissance.
Limite : est la zone multi polygonale réelle exprimée sous forme de géométrie (dans geojson). Il est normalement associé à un champ ou à un champ saisonnier. Les données satellites, météorologiques et agricoles sont liées à une limite.
Suppression en cascade : les données agronomiques sont stockées hiérarchiquement avec partie comme racine. La hiérarchie inclut Party -> Batteries de serveurs -> Champs - Champs -> Champs saisonniers -> Limites -> Données associées (satellite, météo, exploitations agricoles). La suppression en cascade fait référence au processus de suppression d’un nœud et de sa sous-arborescence.

Scènes

Les scènes font référence aux images normalement ingérées à l’aide d’API satellite. Cela inclut les bandes brutes et les bandes dérivées (ex : NDVI). Les scènes peuvent également inclure des sorties spatiales d’un modèle d’inférence ou d’IA/ML (ex : LAI).

Exploitations de la batterie de serveurs

Les opérations de fam comprennent des détails relatifs au labourage, à la plantation, à l’application de pesticides & nutritifs et à la récolte. Cela peut être envoyé manuellement dans FarmBeats à l’aide d’API ou les mêmes informations peuvent être extraites de fournisseurs de services d’équipement agricole comme John Deere.

Exemples

Créer une partie

Une fois que vous avez authentifié et créé l’objet client comme indiqué dans la section Authentifier le client , vous pouvez créer une partie dans la ressource FarmBeats comme suit :

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

Créer une batterie de serveurs

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

Créer une saison

Création d’un objet Season, d’avril à août 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
        }
    )

Créer une limite

Création d’une limite pour le champ saisonnier créé dans l’exemple précédent.

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

Ingérer des images satellites

Déclenchement d’un travail d’ingestion de données satellites pour la limite créée ci-dessus, afin d’ingérer des données d’index de zone feuille pour le mois de janvier 2020. Il s’agit d’une opération de longue durée (également appelée « travail »), qui retourne un objet Poller. L’appel de la .result() méthode sur l’objet poller attend que l’opération se termine et retourne l’état final.

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

Obtenir des scènes satellites ingérées

Interrogation des scènes créées par le travail dans l’exemple précédent.

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

Dépannage

Général

Le client FarmBeats déclenche des exceptions définies dans [Azure Core][azure_core] si vous appelez .raise_for_status() vos réponses.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée de niveau DEBUG, comprenant le corps de la demande et/ou de la réponse et les en-têtes non rédigés, peut être activée sur un client à l’aide de l’argument de mot clé 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)

De même, logging_enable peut activer la journalisation détaillée pour un seul appel, même si elle n’est pas activée pour le client :

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

Étapes suivantes

Documentation complémentaire

Pour obtenir une documentation plus complète sur les FarmBeats, consultez la documentation FarmBeats sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Partager via