Home / dataverse / dataverse-metadata-data-model.md

Microsoft Dataverse: možnosti práce s metadaty a datovým modelem pro Hermes/AI agenta

Cíl: shrnout praktické způsoby, jak může Hermes/agent číst, analyzovat a případně měnit metadata, datový model a data v Microsoft Dataverse.

Krátký závěr:

1. Dataverse Web API

Oficiální zdroje:

Typický endpoint:

https://{environment}.crm.dynamics.com/api/data/v9.2/

Metadata read

Důležité endpointy:

GET /api/data/v9.2/EntityDefinitions
GET /api/data/v9.2/EntityDefinitions(LogicalName='account')
GET /api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes
GET /api/data/v9.2/EntityDefinitions(LogicalName='account')/ManyToOneRelationships
GET /api/data/v9.2/EntityDefinitions(LogicalName='account')/OneToManyRelationships
GET /api/data/v9.2/EntityDefinitions(LogicalName='account')/ManyToManyRelationships
GET /api/data/v9.2/RelationshipDefinitions
GET /api/data/v9.2/GlobalOptionSetDefinitions
GET /api/data/v9.2/$metadata

Co lze zjistit:

Doporučení:

Metadata write

Web API umí vytvářet/upravovat/mazat podporované custom komponenty:

Omezení:

Data read/write

Příklady:

GET    /api/data/v9.2/accounts?$select=name,accountid&$top=10
GET    /api/data/v9.2/accounts({id})
POST   /api/data/v9.2/accounts
PATCH  /api/data/v9.2/accounts({id})
DELETE /api/data/v9.2/accounts({id})

Dataverse podporuje OData query, FetchXML, actions/functions a $batch.

Pro agenta je bezpečný pattern:

  1. nejdřív načíst metadata,
  2. ověřit tabulku, sloupce, required fields, typy, choice hodnoty a lookup targety,
  3. teprve potom plánovat data write.

2. Organization Service SDK pro .NET

Oficiální zdroje:

Hlavní knihovna:

Microsoft.PowerPlatform.Dataverse.Client

Klíčové typy:

Metadata requesty:

Kdy dává smysl:

Pro obecného Hermes agenta je Web API praktičtější, protože je jazykově neutrální.

3. Power Platform CLI (pac)

Oficiální zdroje:

Auth a prostředí

pac auth create --url https://ORG.crm.dynamics.com
pac auth list
pac auth select --index <n>
pac org list
pac org select --environment <environment-id-or-url>

Pro CI/CD je vhodnější service principal / application user, pokud to konkrétní scénář a CLI konfigurace podporují.

Solution export/import/unpack/pack

pac solution export --name <solutionUniqueName> --path ./solution.zip --managed false
pac solution unpack --zipfile ./solution.zip --folder ./solution-src --packagetype Unmanaged
pac solution pack --folder ./solution-src --zipfile ./solution.zip --packagetype Unmanaged
pac solution import --path ./solution.zip

Co lze číst:

Limity:

pac modelbuilder

pac modelbuilder build --outdirectory ./Models --namespace Contoso.Dataverse --serviceContextName DataverseContext

Vhodné pro generování .NET early-bound tříd. Jako primární schema export pro AI je to méně vhodné než Web API metadata, ale výstup může být dobrý doplňkový signál.

pac data

pac data export --schemaFile schema.xml --dataFile data.zip
pac data import --dataFile data.zip

Vhodné pro konfigurační/reference data, ne pro plný metadata model.

4. SolutionPackager / ALM export

Oficiální zdroj:

Moderní cesta je často přes pac solution unpack/pack, historicky přes SolutionPackager.exe.

Silné stránky:

Slabé stránky:

Doporučení pro agenta:

5. Maker portal, classic solution explorer, admin UI

Oficiální zdroje:

Možnosti:

Pro agenta:

6. Power Platform connectors / Power Automate

Oficiální zdroje:

Dataverse connector umí hlavně:

Admin/maker connectors umí spíš:

Limity:

Pro Hermes:

7. TDS / SQL endpoint

Oficiální zdroj:

Typicky:

server: org.crm.dynamics.com,5558
auth: Microsoft Entra ID

Možnosti:

Limity:

Pro agenta:

8. XrmToolBox a komunitní nástroje

Zdroj:

Užitečné pluginy:

Poznámka: není to oficiální Microsoft API ani headless automation surface. Je to výborný desktop nástroj pro developera/admina, ale pro Hermes agenta spíš zdroj inspirace nebo manuální troubleshooting.

9. Autentizace a oprávnění

Oficiální auth zdroj:

Běžné modely:

  1. Delegated user auth
  2. interaktivní uživatel,
  3. vhodné pro vývoj a ruční nástroje,

  4. méně vhodné pro unattended agenta.

  5. Client credentials / service principal

  6. Entra ID app registration,
  7. Dataverse application user,
  8. security roles v Dataverse,

  9. nejlepší pro server/agent automation.

  10. Managed identity

  11. vhodné v podporovaných Azure scénářích,
  12. také potřebuje Dataverse application user / role.

Důležité:

10. Limity, throttling, výkon

Oficiální zdroj:

Typické caveaty:

11. Doporučená architektura pro Hermes agenta

Read-only metadata discovery

  1. Přihlásit se jako service principal / application user.
  2. Načíst metadata přes Web API:
  3. EntityDefinitions,
  4. Attributes,
  5. relationships,
  6. keys,
  7. GlobalOptionSetDefinitions.
  8. Normalizovat do interního JSON modelu:
  9. table logical/schema/display name,
  10. primary key/name,
  11. ownership,
  12. columns: type, required, max length, precision, lookup targets, choices,
  13. relationships,
  14. custom/system flags,
  15. solution/managed indikace, pokud dostupná.
  16. Uložit cache s verzí/timestampem.
  17. Při změnách použít RetrieveMetadataChanges nebo refresh po solution import/publish.

ALM/offline analýza

  1. pac auth create/select
  2. pac solution export
  3. pac solution unpack
  4. Parsovat XML do dokumentace / diffu / graphu.
  5. Kombinovat s Web API pro úplný environment inventory.

Data access

  1. Nejprve metadata validation.
  2. Potom dotazovat data přes Web API nebo TDS.
  3. Minimalizovat PII a počet řádků.
  4. Používat explicitní filtr/scope.

Write/schéma změny

Povinné guardrails:

Destruktivní operace vyžadující explicitní potvrzení:

12. Praktické pořadí voleb

Scénář Nejlepší cesta Poznámka
Kompletní schema inventory prostředí Web API metadata Nejlepší pro agenta
.NET aplikace / early-bound typy Organization Service SDK / pac modelbuilder Dobré pro developer tooling
ALM/source control solution pac solution export + unpack Výborné pro diff/review
Offline dokumentace solution SolutionPackager / unpacked solution Jen komponenty v solution
SQL analýza dat TDS endpoint Read-only
CRUD řádků v automatizaci Web API Validovat proti metadatům
Flow/business orchestrace Dataverse connector / Power Automate Ne jako metadata API
Ruční kontrola Maker portal / classic UI / XrmToolBox Ne headless primární cesta

13. Doporučení pro implementaci v Hermes

Minimální robustní modul pro Dataverse by měl mít:

Výchozí strategie:

  1. Read-only metadata přes Web API.
  2. Volitelně solution export pro ALM kontext.
  3. Data sampling jen na explicitní žádost.
  4. Write operace jen přes plán + diff + potvrzení.

Ověřené zdroje

Vybrané Microsoft Learn URL byly během přípravy ověřeny HTTP odpovědí 200: