Python SDK, CLI 또는 MCP 도구를 사용하여 Dataverse 테이블에 레코드 단위 CRUD, 대량 작업 및 CSV 가져오기를 수행합니다.
- GitHub 스타
- 257
- 파일
- 4
- 마지막 커밋
- 2026년 11월 11일
- 라이선스
- MIT
- 허용된 도구
- —
dv-data skill은 무엇을 하나요?
Python SDK, CLI 또는 MCP 도구를 사용하여 Dataverse 테이블에 레코드 단위 CRUD, 대량 작업 및 CSV 가져오기를 수행합니다.
skill의 SKILL.md에서 생성된 요약입니다.
dv-data skill 정보
이 SKILL은 개발자와 데이터 엔지니어가 직접 조작을 통해 Dataverse 레코드를 관리할 수 있도록 지원합니다. 공식 Microsoft Power Platform Dataverse Client Python SDK, Dataverse CLI 또는 대화형 MCP 도구를 사용하여 생성, 업데이트, 삭제 및 upsert 작업을 수행할 수 있는 방법을 제공합니다. 사용자는 MCP 도구를 사용하여 호출당 최대 25개의 레코드까지 소규모 대화형 작업을 처리하거나, 레코드 연결 또는 파일 업로드와 같은 헤드리스 원라이너 명령을 위해 CLI를 사용할 수 있습니다.
더 큰 데이터 세트의 경우, 이 SKILL은 CreateMultiple, UpdateMultiple 및 서버 측 대량 삭제와 같은 대량 작업을 용이하게 합니다. 또한 CSV 파일에서 데이터를 가져오거나 pandas DataFrame에서 직접 데이터를 쓰는 기능도 지원합니다. 복잡한 데이터 변환이나 대량의 가져오기가 필요한 경우 Python SDK가 기본 인터페이스 역할을 하며, 페이로드 크기와 타임아웃을 관리하기 위한 적응형 청킹을 제공합니다. 이 SKILL은 데이터 쓰기 워크플로우를 위해 특별히 설계되었으며, 레코드 쿼리 또는 메타데이터 관리를 위한 전문 도구를 대체하지 않습니다.
agent가 수행할 수 있는 작업
- 1대량 데이터 가져오기 실행개발자는 안정성을 위해 적응형 청킹이 필요한 대규모 대량 생성 또는 업데이트를 수행할 때 Python SDK를 사용할 수 있습니다.
- 2DataFrame에서 데이터 동기화client 네임스페이스를 통해 pandas DataFrame을 사용하여 Dataverse 레코드를 직접 쓰거나 업데이트할 수 있습니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
dv-data skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 dv-data skill 설치
/plugin marketplace add microsoft/Dataverse-skills /plugin install dataverse@dataverse-skills
Claude Code에 dv-data skill 설치
~/.claude/skills/dv-data/SKILL.md
$ npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data ~/.claude/skills/dv-dataClaude Code (project)에 dv-data skill 설치
.claude/skills/dv-data/SKILL.md
$ npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data .claude/skills/dv-dataCodex에 dv-data skill 설치
~/.agents/skills/dv-data/SKILL.md
$ npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data ~/.agents/skills/dv-dataGemini CLI에 dv-data skill 설치
~/.gemini/skills/dv-data/SKILL.md
$ npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data ~/.gemini/skills/dv-dataClaude.ai에 dv-data skill 설치
npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data dv-data && zip -r dv-data.zip dv-data # claude.ai → Customize → Skills → + → Create skill → Upload a skill → dv-data.zip
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식
- 소스 저장소 연결 및 접근 가능microsoft/dataverse-skills/.github/plugins/dataverse/skills/dv-data is public and reachablegithub.com/microsoft/dataverse-skills/tree/HEAD/.github/plug ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-11github.com/microsoft/dataverse-skills/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/microsoft/dataverse-skills/blob/HEAD/.github/plug ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/microsoft/dataverse-skills/blob/HEAD/.github/plug ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 405 linesgithub.com/microsoft/dataverse-skills/blob/HEAD/.github/plug ↗통과
SKILL.md
GitHub에서 보기Skill: Data — Create, Update, Delete, and Bulk Import
This skill uses Python and the Dataverse CLI. Do not use Node.js, JavaScript, or any other language for Dataverse scripting. If you are about to run
npm installor write a.jsfile, STOP — you are going off-rails. See the overview skill's Hard Rules.
ERP exception, including planning-only requests: load dv-overview, then read references/erp-writes.md. ERP writes and DMF imports do not use the Dataverse SDK guidance below. A request not to execute operations still permits loading skills and reading local references.
Use the official Microsoft Power Platform Dataverse Client Python SDK for all data write operations.
Official SDK: https://github.com/microsoft/PowerPlatform-DataverseClient-Python
PyPI package: PowerPlatform-Dataverse-Client (this is the only official one — do not use dataverse-api or other unofficial packages)
Status: GA (1.1.0, Production/Stable)
Skill boundaries
| Need | Use instead |
|---|---|
| Query or read records | dv-query |
| Create tables, columns, relationships, forms, views | dv-metadata |
| Export or deploy solutions | dv-solution |
| ERP writes | See references/erp-writes.md |
Choosing MCP, CLI, or SDK for writes
CLI fast path: If dataverse auth who shows an active profile, CLI commands (data create/update/delete/upsert/associate/upload) work immediately — no .env, auth.py, or pip needed. SDK and bulk operations still need workspace setup.
If MCP tools are available (create_record, update_record, delete_record), they are the quickest path for a small, interactive set of writes — up to 25 records per call, no script needed. The Dataverse CLI (dataverse data create/update/upsert/delete) handles single-record writes, associate/disassociate, and file uploads as headless one-liners. The SDK is the default for bulk writes beyond 25, data transformation, retry logic, CSV import, or SDK-only operations (upsert with alternate keys — MCP has no upsert tool). Pick the surface that fits the volume and shape of the work.
When you script a write, use the SDK — not hand-rolled HTTP
The MCP/CLI/SDK choice is capability-based (above; and see the overview's Tool Capabilities / Hard Rule 2). This section is narrower: once you've decided to write via a script, use the SDK for anything in its "supports" list rather than hand-rolled urllib/requests — the SDK carries the auth, paging, and retry those re-implement. For the rare operation the SDK doesn't cover, use the dataverse api escape hatch — not hand-rolled urllib.
Correct import (always preceded by sys.path.insert in a full script — see Setup below):
from auth import get_client
WRONG for SDK-supported operations:
from auth import get_token, load_env # WRONG for SDK-supported ops
import requests # WRONG for SDK-supported ops
get_token() and requests exist ONLY for genuine gaps with no managed path (global option sets, unbound actions) — and even then prefer the managed dataverse api escape hatch. Forms/views, aggregation, and N:N reads are all covered by the SDK; see dv-query and dv-metadata.
What This SDK Supports (Data Operations)
- Record writes: create, update, delete
- Record reads within write workflows (e.g., lookup resolution) — for standalone queries see dv-query
- Upsert (with alternate key support)
- Bulk operations:
CreateMultiple,UpdateMultiple,UpsertMultiple, bulk delete (records.delete(table, [ids])runs the server-side BulkDelete action), multi-operation batching (client.batch) - File column uploads (chunked for files >128MB)
- Context manager with HTTP connection pooling
What This SDK Does NOT Support
Forms/views (systemform/savedquery) are ordinary records — create/modify them with client.records.* (see dv-metadata), and read N:N with records.list(expand=...). For the genuine gaps below, prefer the managed dataverse api escape hatch over raw urllib:
- Global option sets — see dv-metadata
- N:N record association — CLI
dataverse data associate, orPOST /api/data/v9.2/<entity>(<id>)/<nav-property>/$ref $applyaggregation — useclient.query.fetchxml(); see dv-query- Unbound actions (e.g.,
PublishXml,InstallSampleData) —dataverse api request/invoke
Dataverse CLI data examples (copy-paste ready)
All dataverse commands take --context for skill attribution (global flag).
# Create a record (--table is the EntitySet name)
dataverse data create --table accounts --data '{"name":"Contoso"}' --return --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Update by GUID
dataverse data update --table accounts --id <guid> --data '{"name":"Contoso (updated)"}' --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Upsert by alternate key (idempotent — safe to re-run)
dataverse data upsert --table accounts --key "accountnumber='ACC-001'" --data '{"name":"Contoso Ltd"}' --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Delete (--no-confirm skips the prompt)
dataverse data delete --table accounts --id <guid> --no-confirm --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Associate two records (N:N or lookup)
dataverse data associate --table accounts --id <guid> --relationship contact_customer_accounts --related contacts --related-id <contact-guid> --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Disassociate (N:N — pass --related-id; clear a lookup — omit --related-id)
dataverse data disassociate --table accounts --id <guid> --relationship contact_customer_accounts --related-id <contact-guid> --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Upload a file to a file column (--table takes LogicalName, not EntitySet)
dataverse data upload --table account --id <guid> --column new_document --file report.pdf --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Describe entity schema (attributes, relationships, actions)
dataverse data describe --table account --include all --json --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Invoke a discovered custom API by name (use 'api list' to find names)
dataverse api invoke <CustomApiName> --target dataverse --param Input=value --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
# Raw API escape hatch for built-in actions (--target is required)
dataverse api request --target dataverse --path "/api/data/v9.2/WhoAmI" --context "app=dataverse-skills/<ver>;skill=dv-data;agent=<agent>"
Setup
import os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client
# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-data")
get_client(skill) handles auth, environment URL, and plugin attribution (User-Agent tagging). See scripts/auth.py.
For scripts that run to completion: wrap in with DataverseClient(...) as client: for automatic connection cleanup (recommended). For notebooks and interactive sessions, the explicit client above is simpler.
Field Name Casing Rule
Getting this wrong causes 400 errors.
| Property type | Convention | Example | When used |
|---|---|---|---|
| Structural (columns) | LogicalName — always lowercase | new_name, new_priority |
Record payload keys |
| Navigation (lookups) | Navigation Property Name — case-sensitive, matches $metadata |
new_AccountId |
@odata.bind keys |
The SDK lowercases structural keys automatically but preserves @odata.bind key casing.
Create a Record
guid = client.records.create("new_ticket", {
"new_name": "Ticket 001",
"new_priority": 100000002, # choice column — integer value, not string
"new_AccountId@odata.bind": "/accounts(<account-guid>)",
})
print(f"Created: {guid}")
@odata.bind notes:
- Key is the Navigation Property Name:
new_AccountId@odata.bind(the SDK preserves casing automatically, but matching the schema name is still the correct form) - Value is
"/<EntitySetName>(<guid>)"— e.g.,"/accounts(<guid>)" - If you just created the lookup column, wait 5–10 seconds before inserting. Metadata propagation delays cause "Invalid property" errors.
- Choice columns use integer values, not strings:
"new_priority": 100000002(not"High")
Common @odata.bind patterns
| Lookup | Correct key | Wrong |
|---|---|---|
Custom: new_AccountId |
new_AccountId@odata.bind |
new_accountid@odata.bind |
System polymorphic: customerid |
customerid_account@odata.bind |
customerid@odata.bind |
System: parentcustomerid |
parentcustomerid_account@odata.bind |
_parentcustomerid_value@odata.bind |
Find the Navigation Property Name
After creating a lookup via SDK: result.lookup_schema_name is the navigation property name.
For existing system tables, query:
GET /api/data/v9.2/EntityDefinitions(LogicalName='<entity>')/ManyToOneRelationships
?$select=ReferencingEntityNavigationPropertyName,ReferencedEntity
Update a Record
client.records.update("new_ticket", "<record-guid>",
{"new_status": 100000001})
Delete a Record
# Single record
client.records.delete("new_ticket", "<record-guid>")
# Bulk delete — pass a list of ids; runs the server-side BulkDelete action (one async job, not N calls)
job_id = client.records.delete("new_ticket", [id1, id2, id3])
# use_bulk_delete=False deletes each id sequentially instead
Bulk Create (SDK uses CreateMultiple internally)
records = [{"new_name": f"Ticket {i}", "new_priority": 100000000} for i in range(500)]
guids = client.records.create("new_ticket", records)
print(f"Created {len(guids)} records")
Volume guidance: CLI dataverse data create for one-off records. MCP create_record batches up to 25 per call. SDK CreateMultiple for larger bulk.
Important: The SDK sends all records in a single POST to CreateMultiple. It does not chunk automatically. Dataverse has no fixed record count limit — the constraints are payload size and request timeout (SDK default: 120s for POST). For larger datasets, you must chunk in your script. The bulk_upsert and bulk_create helpers below use adaptive chunking: start at 1,000, double on success (up to 4,000), halve on payload/timeout failure, and cap at the last successful size. Tables with few columns can handle larger chunks than tables with many columns.
Bulk Update
# Broadcast same change to multiple records
client.records.update("new_ticket",
[id1, id2, id3],
{"new_status": 100000001})
DataFrame Write-Back
To create or update records from a pandas DataFrame, use the client.dataframe namespace (create/update). This is documented in dv-query but is a write operation — include it in your data write workflow:
# Update records — DataFrame must include the primary key column
client.dataframe.update("opportunity", df_updates, id_column="opportunityid")
# Create records — returns a Series of new GUIDs
guids = client.dataframe.create("opportunity", df_new_records)
See dv-query for the full client.dataframe write reference; for reads use client.query.builder(...).execute().to_dataframe().
Upsert (Alternate Keys)
Idempotent — re-running the same import does not create duplicates. The alternate key must be defined on the table first — see dv-metadata.
Do NOT include alternate key columns in the record body. The alternate key identifies the record; the record body contains the data to set. If the same column appears in both, UpsertMultiple fails with "An unexpected error occurred" (single upsert tolerates it, bulk does not).
from PowerPlatform.Dataverse.models.upsert import UpsertItem
client.records.upsert("account", [
UpsertItem(
alternate_key={"accountnumber": "ACC-001"},
record={"name": "Contoso Ltd", "description": "Primary account"},
),
UpsertItem(
alternate_key={"accountnumber": "ACC-002"},
record={"name": "Fabrikam Inc"},
),
])
Bulk Import from CSV
For imports that may be re-run (most real-world cases), use
UpsertItemwith alternate keys instead ofcreate()— seereferences/multi-table-fk-import.md. Thecreate()pattern here is for one-shot loads only.
| Volume | Tool | Why |
|---|---|---|
| 1 record | CLI dataverse data create or MCP create_record |
No script needed |
| 2–25 records | MCP create_record |
Batches up to 25 per call |
| 25+ records | SDK client.records.create(table, list) |
Uses CreateMultiple; chunk large datasets (start at 1K, adapt) |
import csv, os, sys
sys.path.insert(0, os.path.join(os.getcwd(), "scripts"))
from auth import get_client
# get_client sets a plugin attribution context on the User-Agent header.
# Do not modify the context value — it is a closed schema for server-side
# telemetry (app/skill/agent). Never include secrets or PII.
client = get_client("dv-data")
with open("data/customers.csv", newline="", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
records = [{"new_name": row["name"], "new_email": row["email"]} for row in rows]
# SDK sends all in one POST — chunk to avoid payload/timeout limits
# Start at 1000; for narrow tables (few columns) you can go higher
chunk_size = 1000
for i in range(0, len(records), chunk_size):
guids = client.records.create("new_customer", records[i:i + chunk_size])
print(f"Imported {i + len(guids)}/{len(records)} customers", flush=True)
Lookup resolution during import
If the CSV has a human-readable key (e.g., customer_email) but Dataverse needs a GUID, pre-resolve with a lookup dict:
# Build email -> GUID map first
email_to_guid = {}
for r in client.records.list("new_customer", select=["new_customerid", "new_email"]):
email_to_guid[r["new_email"]] = r["new_customerid"]
# Use it during import
records = []
for row in rows:
customer_guid = email_to_guid.get(row["customer_email"])
if not customer_guid:
print(f"Skipping row — unknown email: {row['customer_email']}")
continue
records.append({
"new_channel": row["channel"],
"new_CustomerId@odata.bind": f"/new_customers({customer_guid})", # verify entity set name via EntityDefinitions
})
guids = client.records.create("new_interaction", records)
Required field discovery for system tables
Before bulk-creating in a system table (account, contact, opportunity):
- Create a single test record with your intended minimal payload
- If
HttpError400 is raised, the error message names the missing required field - Some required fields are plugin-enforced and not visible in
describe - Delete the test record, then proceed with bulk create
Multi-Table Import with FK Dependencies
When importing data across multiple tables with foreign key relationships, the import must run in dependency order with UpsertItem + alternate keys (idempotent, safe for re-runs).
Quick reference:
- Create tables with source ID columns + alternate keys + lookup relationships (see dv-metadata).
- Import Level 0 (no FK deps) tables in parallel via
ThreadPoolExecutor. Sequential chunks within each table (concurrent writes deadlock). - Build source-ID → GUID maps by querying back (upsert doesn't return GUIDs).
- Repeat per dependency level — Level 1 needs Level 0's maps for
@odata.bind.
For the full pattern — adaptive bulk_upsert helper, composite-key handling, post-import verification, and the first-time bulk_create variant — see references/multi-table-fk-import.md.
Key invariants (apply even without reading the reference):
- Parallelize across tables at the same level, sequential between levels, sequential chunks within a table.
- Alternate key columns must NOT also appear in the record body —
UpsertMultiplefails. - Catch per-table failures in the executor — one table failing must not kill the others.
- Start
chunk_size=1000; the helper ramps up adaptively.
Error Handling
from PowerPlatform.Dataverse.core.errors import HttpError
try:
guid = client.records.create("new_ticket", {"new_name": "Test"})
except HttpError as e:
print(f"Status {e.status_code}: {e.message}")
if e.details:
print(f"Details: {e.details}")
# 400 — bad field name, @odata.bind format, or missing required field
# 403 — check security roles
# 404 — table or record not found
# 429 — rate limited; SDK retries automatically, reduce batch size if persistent
Writing ERP data
On ERP-linked envs, writes to ERP entities do not go through the Python SDK. See references/erp-writes.md.
Windows Scripting Notes
- ASCII only in
.pyfiles — curly quotes and em dashes causeSyntaxErroron Windows. - No
python -cfor multiline code — write a.pyfile instead. - Generate GUIDs in scripts:
str(uuid.uuid4()), not shell backtick substitution.
Sample Data Generation
Generate realistic sample records inline — schema-driven, table-agnostic, PII-safe defaults (@example.com emails, 555-01xx phones).
Quick reference: confirm environment + count + table → query EntityDefinitions(LogicalName='<table>')/Attributes?$filter=AttributeOf eq null for required columns → dispatch by AttributeType (String / Memo / Integer / DateTime / Picklist / etc.) → client.records.create() (use CreateMultiple for count >= 10).
For the schema-driven fake() template, the EntityDefinitions query, and the safety rules, see references/sample-data-generation.md.
Key invariants:
- Skip Lookup, Uniqueidentifier, State, Status, Owner, Customer fields unless the user explicitly provides values.
UserLocalizedLabelmay be null — dereference safely.
Confirmation-flow examples
Generate N sample records (destructive — preview the snippet, ask for env):
- ❌ "Which environment should I target? Please provide the Dataverse URL."
- ✅ "I'll run the Sample Data Generation snippets with
TABLE=\"contact\",COUNT=20. UsesCreateMultiple,.example.comemails,555-01xxphones, against the activepac auth listenvironment. Confirm to proceed, or specify a different environment."
Sample data on a custom entity (schema unknown — prose is enough):
- ❌ "I need more info about the entity. What are the required fields?"
- ✅ "Custom entity — I'll query
EntityDefinitionsforcr123_projectto discover required columns, then generate 5 records inline mapping each column to a generator byAttributeTypeand callclient.records.create(\"cr123_project\", records). Confirm to proceed, or tell me a different count."
이 스킬의 파일
4dv-data skill 질문
Claude Code에 dv-data skill을 어떻게 설치하나요?
npx degit microsoft/Dataverse-skills/.github/plugins/dataverse/skills/dv-data ~/.claude/skills/dv-data를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
dv-data skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
Dataverse 스크립팅에는 어떤 언어를 사용해야 하나요?
Python과 Dataverse CLI를 사용해야 합니다. Dataverse 스크립팅에 Node.js, JavaScript 또는 기타 언어를 사용하지 마십시오.
MCP나 CLI 대신 SDK를 사용해야 하는 경우는 언제인가요?
25개 이상의 레코드 대량 쓰기, 데이터 변환, 재시도 로직, CSV 가져오기 또는 대체 키를 사용한 upsert와 같은 작업에는 SDK를 사용하십시오.
타임아웃을 방지하기 위해 대규모 대량 가져오기를 어떻게 처리하나요?
대규모 데이터 세트의 경우 스크립트에서 데이터를 청크 단위로 나누어야 합니다. SDK의 bulk helper는 페이로드 크기와 타임아웃을 관리하기 위해 적응형 청킹(adaptive chunking)을 사용합니다.