Python용 Azure FarmBeats 클라이언트 라이브러리 - 버전 1.0.0b2

아티클
04/05/2023

FarmBeats는 AgriFood 회사가 Azure에서 지능형 디지털 농업 솔루션을 쉽게 빌드할 수 있도록 하는 Microsoft의 B2B PaaS 제품입니다. FarmBeats를 사용하면 심층 데이터 엔지니어링 리소스에 투자할 필요 없이 다양한 원본(농장 장비, 날씨, 위성)에서 농업 데이터를 획득, 집계 및 처리할 수 있습니다.  고객은 FarmBeats를 기반으로 SaaS 솔루션을 빌드하고 모델 빌드에 대한 최고 수준의 지원을 활용하여 대규모 인사이트를 생성할 수 있습니다.

Python용 FarmBeats 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

업데이트 파티, 팜, 필드, 계절 필드 및 경계를 만듭니 & 다.
관심 영역에 대한 위성 및 날씨 데이터를 수집합니다.
농장 입력의 경작, 심기, 수확 및 적용을 포함하는 팜 작업 데이터를 수집합니다.

소스 코드 | 패키지(PyPi) | API 참조 설명서 | 제품 설명서 | Changelog

시작

필수 조건

이 패키지를 사용하려면 다음이 있어야 합니다.

Azure 구독 -체험 계정 만들기
Azure FarmBeats 리소스 - FarmBeats 설치
3.6 이상 - Python 설치

패키지 설치

pip를 사용하여 Python용 Azure FarmBeats 클라이언트 라이브러리를 설치합니다.

pip install azure-agrifood-farming

클라이언트 인증

AAD(Azure Active Directory) 토큰 자격 증명을 사용하려면 azure-identity 라이브러리에서 가져온 원하는 자격 증명 형식의 인스턴스를 제공합니다.

AAD를 사용하여 인증하려면 먼저 FarmBeats 리소스에서 AAD 인증을 설치 azure-identity 하고 사용하도록 설정해야 합니다. 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). 일반적으로 필드 또는 계절 필드와 연결됩니다. 위성, 날씨 및 팜 작업 데이터는 경계에 연결됩니다.
Cascade delete - Agronomic 데이터는 파티와 함께 계층적으로 루트로 저장됩니다. 계층 구조에는 파티 - 팜 -> 필드 ->> 계절 필드 - 경계 ->> 연결된 데이터(위성, 날씨, 팜 작업)가 포함됩니다. Cascade 삭제는 노드 및 해당 하위 트리를 삭제하는 프로세스를 나타냅니다.

장면

장면은 위성 API를 사용하여 일반적으로 수집되는 이미지를 나타냅니다. 여기에는 원시 밴드 및 파생 밴드(예: NDVI)가 포함됩니다. 장면에는 유추 또는 AI/ML 모델(예: LAI)의 공간 출력도 포함될 수 있습니다.

팜 작업

Fam 작업에는 경작, 심기, 농약 & 영양분의 적용 및 수확과 관련된 세부 사항이 포함됩니다. 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월까지의 Season 개체 만들기

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월의 리프 영역 인덱스 데이터를 수집합니다. 이는 장기 실행 작업('Job'이라고도 함)이며 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 수준에서 기록됩니다.

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을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

다음을 통해 공유