biblioteka klienta Azure FarmBeats dla języka Python — wersja 1.0.0b2

Artykuł
04/05/2023

FarmBeats to oferta B2B PaaS firmy Microsoft, która ułatwia firmom AgriFood tworzenie inteligentnych rozwiązań rolnictwa cyfrowego na platformie Azure. Usługa FarmBeats umożliwia użytkownikom pozyskiwanie, agregowanie i przetwarzanie danych rolnych z różnych źródeł (sprzęt farmy, pogoda, satelita) bez konieczności inwestowania w głębokie zasoby inżynieryjne danych.  Klienci mogą tworzyć rozwiązania SaaS na podstawie usługi FarmBeats i korzystać z najwyższej klasy obsługi tworzenia modeli w celu generowania szczegółowych informacji na dużą skalę.

Użyj biblioteki klienta FarmBeats dla języka Python, aby wykonać następujące czynności.

Twórz & strony aktualizacji, gospodarstwa, pola, pola sezonowe i granice.
Pozyskiwanie danych satelitarnych i pogodowych dla obszarów zainteresowania.
Pozyskiwanie danych operacyjnych gospodarstw obejmujących uprawy, sadzenia, zbierania i stosowania danych wejściowych gospodarstw rolnych.

Kod | źródłowy Pakiet (PyPi) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Changelog

Wprowadzenie

Wymagania wstępne

Aby użyć tego pakietu, musisz mieć następujące elementy:

Subskrypcja platformy Azure — można utworzyć bezpłatne konto
zasób Azure FarmBeats — instalowanie programu FarmBeats
3.6 lub nowsza wersja — instalowanie języka Python

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure FarmBeats dla języka Python przy użyciu narzędzia pip:

pip install azure-agrifood-farming

Uwierzytelnianie klienta

Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki azure-identity .

Aby uwierzytelnić się w usłudze AAD, musisz najpierw zainstalować azure-identity narzędzie pip i włączyć uwierzytelnianie usługi AAD w zasobie FarmBeats. Jeśli podczas tworzenia zasobu FarmBeats wykonano czynności opisane w dokumentacji instalacji , zostało to już omówione.

Po skonfigurowaniu możesz wybrać typ poświadczeń z pliku azure.identity do użycia. Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta:

Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i klucza tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Użyj zwróconego poświadczenia tokenu, aby uwierzytelnić klienta:

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)

Kluczowe pojęcia

Podstawowa wiedza na temat poniższych terminów pomoże rozpocząć pracę z biblioteką klienta FarmBeats.

Hierarchia farmy

Hierarchia farmy to kolekcja poniższych jednostek.

Strona - jest opiekunem wszystkich danych agronomii.
Farma — jest logiczną kolekcją pól i/lub pól sezonowych. Nie mają z nimi żadnego obszaru.
Pole — jest obszarem wielokąta. Oczekuje się, że będzie to stabilne w różnych sezonach.
Pole sezonowe - jest obszarem wielokąta. Aby zdefiniować granicę sezonową, potrzebujemy szczegółów obszaru (granica), czasu (sezon) i upraw. Oczekuje się, że nowe pola sezonowe będą tworzone dla każdego sezonu rosnącego.
Granica — jest rzeczywistym obszarem wielokątnym wyrażonym jako geometria (w formacie geojson). Zwykle jest on związany z polem lub polem sezonowym. Dane dotyczące operacji satelitarnych, pogodowych i rolnych są połączone z granicą.
Usuwanie kaskadowe — dane agronomiiczne są przechowywane hierarchicznie z elementem głównym. Hierarchia obejmuje Strony —> Farmy —> Pola —> Pola sezonowe —> Granice —> Skojarzone dane (satelita, pogoda, operacje na farmie). Usuwanie kaskadowe odnosi się do procesu usuwania dowolnego węzła i jego poddrzewa.

Sceny

Sceny odnoszą się do obrazów zwykle pozyskiwanych przy użyciu interfejsów API satelickich. Dotyczy to nieprzetworzonych pasm i pochodnych pasm (np. NDVI). Sceny mogą również obejmować dane wyjściowe przestrzenne wnioskowania lub modelu sztucznej inteligencji/uczenia maszynowego (np. LAI).

Operacje farmy

Operacje Fam obejmują szczegóły dotyczące uprawy, sadzenia, stosowania składników odżywczych pestycydów & i zbiorów. Można to ręcznie wypchnąć do usługi FarmBeats przy użyciu interfejsów API lub te same informacje można pobrać od dostawców usług sprzętu farmy, takich jak John Deere.

Przykłady

Tworzenie strony

Po uwierzytelnieniu i utworzeniu obiektu klienta, jak pokazano w sekcji Uwierzytelnianie klienta , możesz utworzyć jednostkę w ramach zasobu FarmBeats w następujący sposób:

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

Tworzenie farmy

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

Tworzenie sezonu

Tworzenie obiektu Season obejmującego od kwietnia do sierpnia 2021 roku.

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

Tworzenie granicy

Tworzenie granicy dla pola sezonowego utworzonego w poprzednim przykładzie.

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

Pozyskiwanie zdjęć satelitarnych

Wyzwolenie zadania pozyskiwania danych satelitarnych dla utworzonej powyżej granicy w celu pozyskania danych indeksu obszaru liścia w miesiącu stycznia 2020 r. Jest to długotrwała operacja (nazywana również "zadaniem") i zwraca obiekt Poller. .result() Wywołanie metody w obiekcie poller oczekuje na zakończenie operacji i zwraca stan końcowy.

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

Pobieranie pozyskiwanych scen satelitarnych

Wykonywanie zapytań o sceny utworzone przez zadanie w poprzednim przykładzie.

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

Rozwiązywanie problemów

Ogólne

Klient FarmBeats zgłosi wyjątki zdefiniowane w [Azure Core][azure_core], jeśli wywołasz .raise_for_status() odpowiedzi.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem słowa kluczowego 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 Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczego wywołania, nawet jeśli nie jest włączone dla klienta:

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

Następne kroki

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi FarmBeats, zobacz dokumentację farmbeats dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Udostępnij za pośrednictwem