DataverseClient Classe

Client di alto livello per le operazioni di Microsoft Dataverse.

Questo client fornisce un'interfaccia semplice e stabile per interagire con gli ambienti Dataverse tramite l'API Web. Gestisce l'autenticazione tramite Azure Identity e delega le operazioni HTTP a un client OData interno.

Funzionalità principali:

Operazioni CRUD OData: creare, leggere, aggiornare, eliminare record
Query SQL: eseguire SQL di sola lettura tramite il parametro api ?sql Web
Metadati della tabella: creare, esaminare ed eliminare tabelle personalizzate; creare ed eliminare colonne
Caricamenti di file: caricamento di file in colonne di file con supporto per la suddivisione in blocchi

Annotazioni

Il client inizializza in modo differinte il client OData interno al primo utilizzo, consentendo la costruzione leggera senza chiamate di rete immediate.

Annotazioni

Tutti i metodi che comunicano con l'API Web Dataverse possono generare

HttpError in caso di esito negativo

Risposte HTTP (ad esempio 401, 403, 404, 429, 500). Metodo individuale

Docstrings documenta solo eccezioni specifiche del dominio.

Le operazioni sono organizzate in spazi dei nomi:

client.records : creare, aggiornare, eliminare e ottenere record (query singole o impaginate)
client.query : operazioni di query e ricerca
client.tables : gestione dei metadati di tabella e colonna
client.files – operazioni di caricamento di file
client.dataframe – wrapper del dataframe pandas per il record CRUD
client.batch : eseguire il batch di più operazioni in una singola richiesta HTTP

I metodi beta v0 (client.create, client.query_sqle così via) sono stati rimossi nella versione 1.0 ga. La chiamata di una genera ora AttributeError con un messaggio che denomina la sostituzione ga e il comando codemod. In precedenza queste chiamate generavano un bare AttributeError senza hint di migrazione, quindi il debug di codice di metà migrazione era doloroso. Vedere _REMOVED_BETA_METHODS.

Il client supporta il protocollo di gestione del contesto di Python per la pulizia automatica delle risorse e il pool di connessioni HTTP:

Costruttore

DataverseClient(base_url: str, credential: TokenCredential, config: DataverseConfig | None = None, *, context: OperationContext | None = None)

Parametri

Nome	Descrizione
base_url Necessario	str URL dell'ambiente Dataverse, ad esempio `"https://org.crm.dynamics.com"`. La barra finale viene rimossa automaticamente.
credential Necessario	TokenCredential Credenziali di Identità di Azure per l'autenticazione.
config	DataverseConfig oppure None Configurazione facoltativa per lingua, timeout e tentativi. Se non specificato, i valori predefiniti vengono caricati da from_env. Valore predefinito: None
context Necessario	OperationContext oppure None Oggetto contesto facoltativo definito dal chiamante aggiunto all'intestazione in uscita `User-Agent` per l'attribuzione di plug-in/tool. Non può essere usato insieme a `config` : passare invece il contesto tramite DataverseConfig .

Parametri di sole parole chiave

Nome	Descrizione
context	Valore predefinito: None

Esempio

Consigliato: gestione del contesto (abilita il pool di connessioni HTTP):


   from azure.identity import InteractiveBrowserCredential
   from PowerPlatform.Dataverse.client import DataverseClient

   credential = InteractiveBrowserCredential()

   with DataverseClient("https://org.crm.dynamics.com", credential) as client:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
       client.records.update("account", record_id, {"telephone1": "555-0100"})
   # Session closed, caches cleared automatically

Ciclo di vita manuale:


   client = DataverseClient("https://org.crm.dynamics.com", credential)
   try:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
   finally:
       client.close()

Metodi

Chiudere il client e rilasciare le risorse.

Chiude la sessione HTTP (se presente), cancella le cache interne e contrassegna il client come chiuso. Sicuro di chiamare più volte. Dopo la chiusura, qualsiasi operazione genererà RuntimeError.

Viene chiamato automaticamente quando si usa il client come gestore del contesto.

Esempio:


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()

flush_cache

Scarica i metadati o lo stato del client memorizzati nella cache.

close