DataverseClient Classe

Cliente de alto nível para operações Microsoft Dataverse.

Este cliente fornece uma interface simples e estável para interagir com ambientes Dataverse através da Web API. Trata da autenticação via Azure Identity e delega operações HTTP a um cliente OData interno.

Principais capacidades:

Operações OData CRUD: criar, ler, atualizar, eliminar registos
Consultas SQL: executar SQL de apenas leitura através do parâmetro Web API ?sql
Metadados de tabelas: criar, inspecionar e eliminar tabelas personalizadas; Criar e eliminar colunas
Carregamentos de ficheiros: carregar ficheiros para colunas de ficheiros com suporte para chunkagem

Observação

O cliente inicializa preguiçosamente o seu cliente OData interno à primeira utilização, permitindo uma construção leve sem chamadas de rede imediatas.

Observação

Todos os métodos que comunicam com a API Web do Dataverse podem surgir

HttpError em não-bem-sucedidos

Respostas HTTP (por exemplo, 401, 403, 404, 429, 500). Método individual

Os docstrings documentam apenas exceções específicas de domínio.

As operações estão organizadas em espaços de nomes:

client.records – criar, atualizar, eliminar e obter registos (consultas únicas ou paginadas)
client.query – operações de consulta e pesquisa
client.tables – gestão de metadados de tabelas e colunas
client.files – operações de upload de ficheiros
client.dataframe – pandas DataFrame wrappers para CRUD de registo
client.batch – agrupar múltiplas operações num único pedido HTTP

Os métodos beta da v0 (client.create, client.query_sql, etc.) foram removidos na versão 1.0 GA. Chamar um agora surge AttributeError com uma mensagem que nomeia o substituto GA e o comando codemod – anteriormente estas chamadas geravam um bare AttributeError sem dica de migração, por isso depurar código meio migrado era doloroso. Veja _REMOVED_BETA_METHODS.

O cliente suporta o protocolo de gestor de contexto do Python para limpeza automática de recursos e pooling de ligações HTTP:

Construtor

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

Parâmetros

Name	Description
base_url Necessário	str A URL do seu ambiente Dataverse, por `"https://org.crm.dynamics.com"`exemplo. A barra final é automaticamente removida.
credential Necessário	TokenCredential Azure Identity credential para autenticação.
config	DataverseConfig ou None Configuração opcional para linguagem, timeouts e tentativas. Se não for fornecido, os valores predefinidos são carregados a partir de from_env. Default value: None
context Necessário	OperationContext ou None Objeto de contexto opcional definido pelo chamador anexado ao cabeçalho de saída `User-Agent` para atribuição de plugin/ferramenta. Não pode ser usado em conjunto com `config` – passar o contexto em vez disso DataverseConfig .

Parâmetros Só de Palavra-Chave

Name	Description
context	Default value: None

Exemplos

Recomendado – gestor de contexto (permite pooling de ligações 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 de vida manual:


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

Métodos

Fecha o cliente e liberta recursos.

Fecha a sessão HTTP (se existir), limpa caches internas e marca o cliente como fechado. É seguro ligar várias vezes. Após o fecho, qualquer operação aumentará RuntimeError.

É chamado automaticamente ao usar o cliente como gestor de contexto.

Example:


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

flush_cache

Limpar metadados ou estado do cliente armazenado em cache.

close