DataverseClient Classe

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

Esse cliente fornece uma interface simples e estável para interagir com ambientes do Dataverse por meio da API Web. Ele manipula a autenticação por meio de Azure Identity e delega operações HTTP a um cliente OData interno.

Principais capacidades:

Operações OData CRUD: criar, ler, atualizar, excluir registros
Consultas SQL: executar SQL somente leitura por meio do parâmetro da API ?sql Web
Metadados de tabela: criar, inspecionar e excluir tabelas personalizadas; criar e excluir colunas
Uploads de arquivo: carregar arquivos em colunas de arquivo com suporte de agrupamento

Observação

O cliente inicializa lentamente seu cliente OData interno no primeiro uso, permitindo a construção leve sem chamadas de rede imediatas.

Observação

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

HttpError em não-bem-sucedido

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

Docstrings documenta apenas exceções específicas do domínio.

As operações são organizadas em namespaces:

client.records – criar, atualizar, excluir e obter registros (consultas simples ou paginadas)
client.query – operações de consulta e pesquisa
client.tables – gerenciamento de metadados de tabela e coluna
client.files – operações de upload de arquivo
client.dataframe – wrappers dataframe pandas para crud de registro
client.batch – envio em lote de várias operações em uma única solicitação HTTP

Os métodos beta v0 (client.createetc client.query_sql.) foram removidos em GA 1.0. Chamar um agora é gerado AttributeError com uma mensagem nomeando a substituição de GA e o comando codemod – anteriormente, essas chamadas geravam uma dica de migração sem AttributeError nenhuma dica de migração, portanto, a depuração do código de meia migração era dolorosa. Veja _REMOVED_BETA_METHODS.

O cliente dá suporte ao protocolo do gerenciador de contexto do Python para limpeza automática de recursos e pool de conexões HTTP:

Construtor

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

Parâmetros

Nome	Description
base_url Obrigatório	str Sua URL de ambiente do Dataverse, por exemplo `"https://org.crm.dynamics.com"`. A barra à direita é removida automaticamente.
credential Obrigatório	TokenCredential Credencial de Identidade do Azure para autenticação.
config	DataverseConfig ou None Configuração opcional para idioma, tempos limite e novas tentativas. Se não for fornecido, os padrões serão carregados de from_env. Valor padrão: None
context Obrigatório	OperationContext ou None Objeto de contexto definido pelo chamador opcional acrescentado ao cabeçalho de saída `User-Agent` para atribuição de plug-in/ferramenta. Não é possível usar junto com `config` – passar o contexto por meio DataverseConfig de seu lugar.

Parâmetros somente de palavra-chave

Nome	Description
context	Valor padrão: None

Exemplos

Recomendado – gerenciador de contexto (habilita o pool de conexõ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

Feche o cliente e libere os recursos.

Fecha a sessão HTTP (se houver), limpa os caches internos e marca o cliente como fechado. É seguro ligar várias vezes. Após o fechamento, qualquer operação será acionada RuntimeError.

Chamado automaticamente ao usar o cliente como um gerenciador de contexto.

Exemplo:


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

flush_cache

Liberar metadados de cliente armazenados em cache ou estado.

close