PowerPlatform-DataverseClient-Python

Dataverse SDK for Python을 사용하면 파이썬 개발자가 익숙한 파이썬 문법으로 Microsoft Dataverse 비즈니스 데이터에 접근, 관리 및 조작할 수 있습니다. .NET 지식이 필요하지 않습니다. 이 라이브러리는 Dataverse Web API를 단일 타입 클라이언트로 래핑하여 테이블과 레코드를 네이티브 파이썬 딕셔너리 및 pandas DataFrame으로 처리합니다.

소스 코드 | 패키지 (PyPI) | API 참조 | 제품 문서 | 샘플

CRUD 및 대량 작업(bulk) — 단일 레코드 외에 네이티브 CreateMultiple, UpdateMultiple, UpsertMultiple, BulkDelete 지원.

.Fluent QueryBuilder — 타입 안정적인 col() 필터링; 읽기 전용 SQL 및 FetchXML도 가능.

.스키마 및 관계(Schema & relationships) — 테이블, 열, 1:N / N:N 관계 생성.

.pandas DataFrame — DataFrames와 Series로 레코드 읽기 및 쓰기 지원.

.파일 업로드(File uploads) — 파일 열에 대한 기능으로, 대용량 파일의 경우 자동 청크 분할(chunking) 처리.

.배치(Batch) — HTTP 요청당 여러 작업을 수행하며, 트랜잭션 변경 세트(transactional changesets) 지원.

.Azure Identity 인증 및 타입 오류(typed errors) — 모든 TokenCredential을 사용하여 어떤 종류의 인증도 가능하며, 재시도 가이드가 포함된 구조화된 예외 계층 구조를 제공합니다.

.비동기(Async) — AsyncDataverseClient는 동기 API를 미러링합니다.

• Python 3.10 이상 버전
• 적절한 권한이 부여된 Microsoft Dataverse 환경
• 애플리케이션에 대한 OAuth 인증 구성

pip install PowerPlatform-Dataverse-Client

pandas 라이브러리는 자동으로 설치되며 client.dataframe 네임스페이스를 구동합니다. 비동기 클라이언트는 선택적 추가 패키지(extra)가 필요합니다: pip install "PowerPlatform-Dataverse-Client[async]"

클라이언트는 모든 Azure Identity TokenCredential을 허용합니다. 로컬 개발에는 InteractiveBrowserCredential을 사용하고, 관리자가 없는 프로덕션 애플리케이션에는 ClientSecretCredential 또는 CertificateCredential을 사용하십시오. 앱 등록 및 모든 인증 유형에 대해서는 [Use OAuth with Dataverse]를 참조하십시오.

from azure.identity import InteractiveBrowserCredential
# 로컬 개발: 로그인하기 위해 브라우저를 엽니다
credential = InteractiveBrowserCredential()
...

아래 예제들은 이 credential을 DataverseClient에 전달합니다.

컨텍스트 매니저로 열어 사용합니다.

모든 작업은 클라이언트의 네임스페이스에 의존합니다: records는 CRUD(생성, 읽기, 업데이트, 삭제)용, query는 필터링된 읽기(filtered reads)용, tables는 스키마 및 메타데이터용, dataframe은 pandas용, files는 업로드용, 그리고 batch는 다중 작업 요청용입니다. 레코드는 열 스키마 이름으로 키가 지정된 일반 Python 딕셔너리이며, 사용자 정의 테이블과 열은 자체 커스터마이징 접두사(예: "new_")를 유지합니다. 아래 섹션들은 일반적으로 사용자가 접근하는 순서대로 기능을 다루며, 각 항목은 더 깊이 있는 내용을 담고 있는 Learn 아티클 및 실행 가능한 샘플로 연결됩니다.

연결을 풀링하고 정리할 수 있도록 클라이언트를 컨텍스트 매니저(context manager)로 사용하세요. create는 새 레코드의 GUID를 문자열로 반환하며, retrieve는 404 오류를 발생시키는 대신 레코드가 존재하지 않을 경우 None을 반환합니다.

from PowerPlatform.Dataverse.client import DataverseClient
with DataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
account_id = client.records.create("account", {"name": "Contoso Ltd"}) # -> GUID str
...

레코드 읽기 및 쓰기에 대한 자세한 내용은 Dataverse 데이터와 walkthrough.py 샘플을 참고하세요.

client.query.builder()는 타입 안전(type-safe)한 OData를 자동으로 구축해 줍니다. 필터링에는 표준 Python 연산자를 사용하여 col()로 사용하며, 값을 자동으로 이스케이프 처리합니다. 결과는 반복 가능(iterable)하여 .to_dataframe()을 통해 pandas에 바로 전달할 수 있습니다.

from PowerPlatform.Dataverse.models import col
results = (client.query.builder("account")
.select("name", "revenue")
...

col()은 또한 .in_([...]) 및 .between(low, high)를 지원하며, 표현식들은 &로 조합됩니다. 대규모 결과 세트의 경우 페이지별 스트리밍을 위해 .page_size(n).execute_pages()를 호출하거나, 관련 행을 한 번의 요청으로 가져오려면 .expand("primarycontactid")를 사용하세요. 원시 SQL 및 FetchXML에 대해서는 Query data 섹션과 sql_examples.py 및 fetchxml.py 샘플을 참조하세요.

client.tables는 테이블, 열, 관계, 대체 키(alternate keys)를 생성하고 검사합니다. 열 유형은 간단한 문자열("string" , "int")입니다.

,
"decimal"

,
"money"

,
"datetime"

,
"bool"

,
"memo"
)
; choice 컬럼을 생성하려면 IntEnum 서브클래스를 전달하거나, 길이, 범위, 형식, 필수 여부 수준 또는 표시 이름과 같은 제약 조건을 설정하기 위해 딕셔너리 사양(예: {"type": "memo", "max_length": 2000})
을 전달합니다. tables.get은 테이블이 존재하지 않을 때 None을 반환하므로, 스키마 설정이 **멱등성(idempotent)**을 갖게 합니다. 모든 테이블에는 기본적으로 주 이름 컬럼(primary name column)인 <prefix>_Name이 자동으로 생성되지만, primary_column을 전달하는 경우에는 그렇지 않으므로 columns 목록에 포함하지 마십시오.

# 타입 지정된 컬럼으로 사용자 정의 테이블 생성
if client.tables.get("new_Project") is None:
client.tables.create("new_Project", {
...

컬럼은 제약 조건을 가질 수 있고, 그 자리에서 업데이트될 수 있으며, 단일 요청으로 해당 타입별 메타데이터와 함께 읽어올 수 있습니다:

# 제약 조건이 있는 컬럼 생성 -- 일반 타입을 전달하는 대신 딕셔너리 사양을 전달합니다.
# 키: max_length, min_value, max_value, precision, format, required, display_name.
client.tables.create("new_Feedback", {
...

관계(Relationship) 메서드는 논리적 이름(logical names)을 사용하며, 이는 항상 소문자로 된 스키마 이름입니다. choice 컬럼, 다대다 관계(many-to-many relationships), 그리고 대체 키(alternate keys)에 대해서는 '테이블 및 컬럼 사용자 정의'와 '테이블 관계 관리'를 참조하십시오.

create()에 리스트를 전달하면 Dataverse의 기본 CreateMultiple을 사용합니다. 단일 변경 딕셔너리를 ID 목록에 적용하려면 UpdateMultiple을, 리스트 삭제에는 BulkDelete를 사용하며, 이는 작업 ID(job ID)를 반환하고 백그라운드에서 레코드를 제거합니다. 개별적으로 삭제하려면 use_bulk_delete=False를 전달하십시오. upsert()는 대체 키를 사용하여 각 레코드를 생성하거나 업데이트하므로, **멱등적 동기화(idempotent syncs)**에 이상적입니다. 이 키는 이미 테이블에 존재해야 하며 해당 인덱스가 Active 상태에 도달했어야 합니다. 이를 위해 client.tables.create_alternate_key로 하나를 생성하고, client.tables.get_alternate_keys를 폴링하여 활성화될 때까지 기다리십시오.

데이터프레임 기반 로드(DataFrame-driven loads)의 경우, client.dataframe.create(table, df)는 전체 pandas DataFrame을 한 번의 호출로 작성합니다. 자세한 내용은 dataframe_operations.py 및 alternate_keys_upsert.py 샘플을 참고하세요.

client.files.upload는 로컬 파일을 파일 열에 작성하며, 대용량 파일은 자동으로 청크(chunking) 처리합니다. client.batch는 여러 작업을 하나의 HTTP 요청으로 묶어주고, batch.changeset()은 이들을 그룹화하여 함께 커밋하거나 롤백되도록 합니다.

client.files.upload("account", account_id, "new_Attachment", "report.pdf")
batch = client.batch.new()
batch.records.create("account", {"name": "Company A"})
...

file_upload.py 및 batch.py 샘플을 참고하세요.

AsyncDataverseClient( [async] 추가 모듈에서 가져옴)는 동기(sync) 클라이언트와 동일한 네임스페이스와 메서드를 노출하며, 각 메서드는 awaitable합니다. 따라서 독립적인 작업들을 asyncio.gather()를 사용하여 동시에 실행할 수 있습니다.

import asyncio
from azure.identity.aio import DefaultAzureCredential
from PowerPlatform.Dataverse.aio import AsyncDataverseClient
...

비동기 클라이언트 작업 및 examples/aio 디렉터리를 참고하세요.

SDK는 DataverseError에서 파생된 타입화된 예외 계층(typed exception hierarchy)을 발생시킵니다. HttpError는 status_code와 is_transient를 노출하므로, 제한되거나 일시적인 실패(throttled or transient failures)에 대해 재시도할 수 있으며 나머지 모든 오류는 기본 클래스로 처리됩니다.

from PowerPlatform.Dataverse.core.errors import (
DataverseError, # 기본 클래스 -- 폴백으로 마지막에 포착
ValidationError, # 클라이언트 측 입력 유효성 검사 실패 (지원되지 않는 SQL 포함)
...

재시도 패턴(retry patterns), 타임아웃, HTTP 진단 로깅은 Handle errors 및 enable HTTP diagnostics를 참고하세요.
Microsoft Learn이 권위 있는 참조 자료이며, 각 기능에 대한 가이드는 위 섹션에서 링크됩니다. SDK가 처음이신가요? 여기서 시작하세요:

examples/ 디렉토리에는 관계(relationships), 배치 변경 세트(batch changesets), 파일 업로드, SQL 및 FetchXML 쿼리, DataFrames 등 고급 시나리오를 포함한 모든 작업에 대한 완전하고 실행 가능한 스크립트가 있으며, 전체 비동기(async) 미러도 제공됩니다. 제안된 학습 진행 순서를 위해 examples 가이드를 먼저 확인해 보세요.

본 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 사용자가 해당 기여를 사용할 권리가 있으며 실제로 그 권리를 부여한다는 내용의 기여자 라이선스 계약(Contributor License Agreement, CLA)에 동의할 것을 요구합니다. 자세한 내용은 Contributor License Agreements를 방문해 주세요.

풀 리퀘스트(pull request)를 제출하면 CLA 봇이 사용자가 CLA를 제공해야 하는지 자동으로 판단하고 PR을 적절하게 꾸며줍니다 (예: 상태 검사, 댓글). 단순히 봇이 제공하는 지침을 따르면 됩니다. 이 CLA는 저희가 사용하는 모든 레포지토리에서 단 한 번만 수행하시면 됩니다.

본 프로젝트는 Microsoft Open Source Code of Conduct를 채택했습니다. 더 많은 정보는 Code of Conduct FAQ를 참조하거나 [email protected]으로 추가 질문이나 의견이 있을 경우 문의해 주세요.

이 SDK에 새로운 기능을 기여할 때는 다음 지침을 따라주세요:

작업 네임스페이스의 공개 메서드(Public methods in operation namespaces) - 새로운 공개 메서드는 operations/ 아래 적절한 네임스페이스 모듈에 추가합니다. 공개 타입과 상수는 자체 모듈에 존재합니다 (예: models/metadata.py, common/constants.py).
공개 메서드를 위한 README 예제 추가 - 공개 API 메서드에 대한 사용 예제를 이 README에 추가하세요.
공개 API 문서화 - 모든 공개 메서드에 대해 매개변수 설명과 예제가 포함된 Sphinx 스타일의 docstring을 포함하세요.
기능 추가 시 문서 업데이트 - README와 SKILL 파일(각 스킬은 2개의 사본이 있음)을 동기화 상태로 유지하세요.
내부 대 공개 명명 규칙 (Internal vs public naming) - 공개 API의 일부가 아니어야 하는 모듈, 파일 및 함수는 _ 접두사(예: _odata.py, _relationships.py)를 사용해야 합니다. 접두사가 없는 파일(예: constants.py, metadata.py)은 공개적이며 SDK 소비자가 가져올 수 있습니다.

이 프로젝트에는 프로젝트, 제품 또는 서비스의 상표나 로고가 포함될 수 있습니다. Microsoft 상표나 로고를 승인받아 사용하는 것은 Microsoft의 상표 및 브랜드 가이드라인을 준수해야 합니다. 이 프로젝트의 수정된 버전에 Microsoft 상표나 로고를 사용할 경우 혼란을 야기하거나 Microsoft의 후원을 암시해서는 안 됩니다. 제3자 상표나 로고의 사용은 해당 제3자의 정책을 따릅니다.