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 da Identidade do Azure e delega operações HTTP a um PowerPlatform.Dataverse.data._odata._ODataClient 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

Construtor

DataverseClient(base_url: str, credential: TokenCredential, config: DataverseConfig | 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

Exemplos

Crie um cliente e execute operações básicas:


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

   credential = InteractiveBrowserCredential()
   client = DataverseClient(
       "https://org.crm.dynamics.com",
       credential
   )

   # Create a record
   record_id = client.records.create("account", {"name": "Contoso Ltd"})

   # Update a record
   client.records.update("account", record_id, {"telephone1": "555-0100"})

   # Query records
   for page in client.records.get("account", filter="name eq 'Contoso Ltd'"):
       for account in page:
           print(account["name"])

   # Delete a record
   client.records.delete("account", record_id)

Métodos

create

Observação

Preterido. Use create em seu lugar.

Crie um ou mais registros pelo nome da tabela.
create_columns

Observação

Preterido. Use add_columns em seu lugar.

Crie uma ou mais colunas em uma tabela existente usando um mapeamento de estilo de esquema.
create_table

Observação

Preterido. Use create em seu lugar.

Crie uma tabela personalizada simples com colunas especificadas.
delete

Observação

Preterido. Use delete em seu lugar.

Exclua um ou mais registros por GUID.
delete_columns

Observação

Preterido. Use remove_columns em seu lugar.

Exclua uma ou mais colunas de uma tabela.
delete_table

Observação

Preterido. Use delete em seu lugar.

Exclua uma tabela personalizada por nome.

Aviso

Essa operação é irreversível e excluirá todos os registros na tabela junto

com a definição da tabela. Utilize com cuidado.
flush_cache

Liberar metadados de cliente armazenados em cache ou estado.
get

Observação

Preterido. Use get em seu lugar.

Registro único por ID – client.records.get(table, record_id)

Consultar/filtrar vários registros – client.records.get(table, filter=..., select=...)

Buscar um único registro por ID ou consultar vários registros.

Quando record_id for fornecido, retornará um único dicionário de registros. Quando record_id é None, retorna um gerador que produz lotes de registros.
get_table_info

Observação

Preterido. Use get em seu lugar.

Obtenha metadados básicos para uma tabela se ela existir.
list_tables

Observação

Preterido. Use list em seu lugar.

Liste todas as tabelas não privadas no ambiente do Dataverse.
query_sql

Observação

Preterido. Use sql em seu lugar.

Execute uma consulta SQL somente leitura usando a funcionalidade da API ?sql Web do Dataverse.

A consulta SQL deve seguir o subconjunto com suporte: uma única instrução SELECT com WHERE opcional, TOP (literal inteiro), ORDER BY (somente nomes de coluna) e um alias de tabela simples após FROM.

Observação

O suporte ao SQL é limitado a consultas somente leitura. Não há suporte para junções complexas, subconsultas e determinadas funções SQL. Consulte a documentação do Dataverse para o conjunto de recursos atual.
update

Observação

Preterido. Use update em seu lugar.

Atualize um ou mais registros.

Esse método dá suporte a três padrões de uso:

  1. Atualização de registro único: update("account", "guid", {"name": "New Name"})

  2. Atualização de difusão: update("account", [id1, id2], {"status": 1}) – aplica as mesmas alterações a todas as IDs

  3. Atualizações emparelhadas: update("account", [id1, id2], [changes1, changes2]) – mapeamento um para um

Observação

As atualizações simples descartam a representação de resposta para melhorar o desempenho. Para atualizações de difusão ou emparelhadas, o método delega à lógica de atualização em lote do cliente interno.
upload_file

Observação

Preterido. Use upload em seu lugar.

Carregue um arquivo em uma coluna de arquivo do Dataverse.

create

Observação

Preterido. Use create em seu lugar.

Crie um ou mais registros pelo nome da tabela.

create(table_schema_name: str, records: Dict[str, Any] | List[Dict[str, Any]]) -> List[str]

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo "account", , "contact"ou "new_MyTestTable").
records
Obrigatório
dict ou list of dict

Um dicionário de registro único ou uma lista de dicionários de registros. Cada dicionário deve conter nomes de esquema de coluna como chaves.

Retornos

Tipo Description
list of str

Lista de GUIDs de registro criados. Retorna uma lista de elementos únicos para uma única entrada.

Exceções

Tipo Description
TypeError

Se records não for um ditado ou lista[dict], ou se o cliente interno retornar um tipo inesperado.

Exemplos

Crie um único registro:


   client = DataverseClient(base_url, credential)
   ids = client.create("account", {"name": "Contoso"})
   print(f"Created: {ids[0]}")

Crie vários registros:


   records = [
       {"name": "Contoso"},
       {"name": "Fabrikam"}
   ]
   ids = client.create("account", records)
   print(f"Created {len(ids)} accounts")

create_columns

Observação

Preterido. Use add_columns em seu lugar.

Crie uma ou mais colunas em uma tabela existente usando um mapeamento de estilo de esquema.

create_columns(table_schema_name: str, columns: Dict[str, Any]) -> List[str]

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo "new_MyTestTable").
columns
Obrigatório
dict mapping str to Any

Mapeamento de nomes de esquema de coluna (com valor de prefixo de personalização) para tipos com suporte. Todos os nomes de coluna personalizados devem incluir o valor do prefixo de personalização** (por exemplo). "new_Notes" Os tipos primitivos incluem "string" (alias: "text"), "int" (alias: "integer"), "decimal" (alias: "money"), "float" (alias: "double"), "datetime" (alias: "date"), "bool" (alias: "boolean") e "file". Subclasses de enumeração (intEnum preferencial) geram um conjunto de opções local e podem especificar rótulos localizados por meio de __labels__.

Retornos

Tipo Description
list of str

Nomes de esquema para as colunas que foram criadas.

Exemplos

Crie várias colunas na tabela personalizada:


   created = client.create_columns(
       "new_MyTestTable",
       {
           "new_Scratch": "string",
           "new_Flags": "bool",
           "new_Document": "file",
       },
   )
   print(created)  # ['new_Scratch', 'new_Flags', 'new_Document']

create_table

Observação

Preterido. Use create em seu lugar.

Crie uma tabela personalizada simples com colunas especificadas.

create_table(table_schema_name: str, columns: Dict[str, Any], solution_unique_name: str | None = None, primary_column_schema_name: str | None = None) -> Dict[str, Any]

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela com valor de prefixo de personalização (por exemplo "new_MyTestTable").
columns
Obrigatório
dict mapping str to Any

Nomes de coluna de mapeamento de dicionário (com valor de prefixo de personalização) para seus tipos. Todos os nomes de coluna personalizados devem incluir o valor do prefixo de personalização (por exemplo). "new_Title" Tipos com suporte:

  • Tipos primitivos: "string" (alias: "text"), "int" (alias: "integer"), "decimal" (alias: "money"), "float" (alias: "double"), "datetime" (alias: "date"), "bool" (alias: "boolean"), e "file"

  • Subclasse de enumeração (intEnum preferencial): cria um conjunto de opções local. Rótulos multilíngues opcionais podem ser fornecidos por meio __labels__ do atributo de classe, definido dentro da subclasse Enum:

    
   class ItemStatus(IntEnum):
       ACTIVE = 1
       INACTIVE = 2
       __labels__ = {
           1033: {"Active": "Active", "Inactive": "Inactive"},
           1036: {"Active": "Actif", "Inactive": "Inactif"}
       }
solution_unique_name
str

Nome exclusivo da solução opcional que deve ser o proprietário da nova tabela. Quando a tabela é omitida é criada na solução padrão.

Valor padrão: None
primary_column_schema_name
str

Nome do esquema de coluna de nome primário opcional com valor de prefixo de personalização (por exemplo). "new_MyTestTable" Se não for fornecido, o padrão será "{customization prefix value}_Name".

Valor padrão: None

Retornos

Tipo Description
dict

Dicionário que contém metadados de tabela, incluindo , , , e table_schema_nameentity_set_name. table_logical_namemetadata_idcolumns_created

Exceções

Tipo Description
MetadataError

Se a criação da tabela falhar ou o esquema for inválido.

Exemplos

Crie uma tabela com colunas simples:


   from enum import IntEnum

   class ItemStatus(IntEnum):
       ACTIVE = 1
       INACTIVE = 2

   columns = {
       "new_Title": "string",      # Note: includes 'new_' customization prefix value
       "new_Quantity": "int",
       "new_Price": "decimal",
       "new_Available": "bool",
       "new_Status": ItemStatus
   }

   result = client.create_table("new_MyTestTable", columns)
   print(f"Created table: {result['table_schema_name']}")
   print(f"Columns: {result['columns_created']}")

Crie uma tabela com um nome de coluna primária personalizado:


   result = client.create_table(
       "new_Product",
       {"new_Price": "decimal"},
       primary_column_schema_name="new_ProductName"
   )

delete

Observação

Preterido. Use delete em seu lugar.

Exclua um ou mais registros por GUID.

delete(table_schema_name: str, ids: str | List[str], use_bulk_delete: bool = True) -> str | None

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
ids
Obrigatório
str ou list of str

Cadeia de caracteres GUID única ou lista de cadeias de caracteres GUID a serem excluídas.
use_bulk_delete
bool

Quando True (padrão) e ids for uma lista, execute a ação BulkDelete e retorne seu identificador de trabalho assíncrono. Quando False cada registro é excluído sequencialmente.

Valor padrão: True

Retornos

Tipo Description
str,
None

ID do trabalho BulkDelete ao excluir vários registros via BulkDelete; caso contrário None.

Exceções

Tipo Description
TypeError

Se ids não for str ou list[str].
HttpError

Se a solicitação de exclusão da API Web subjacente falhar.

Exemplos

Excluir um único registro:


   client.delete("account", account_id)

Excluir vários registros:


   job_id = client.delete("account", [id1, id2, id3])

delete_columns

Observação

Preterido. Use remove_columns em seu lugar.

Exclua uma ou mais colunas de uma tabela.

delete_columns(table_schema_name: str, columns: str | List[str]) -> List[str]

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo "new_MyTestTable").
columns
Obrigatório
str ou list of str

Nome da coluna ou lista de nomes de coluna a serem removidos. Deve incluir o valor do prefixo de personalização (por exemplo "new_TestColumn").

Retornos

Tipo Description
list of str

Nomes de esquema para as colunas que foram removidas.

Exemplos

Remova duas colunas personalizadas pelo nome do esquema:

removed = client.delete_columns( "new_MyTestTable", ["new_Scratch", "new_Flags"],

) print(removed) # ['new_Scratch', 'new_Flags']

delete_table

Observação

Preterido. Use delete em seu lugar.

Exclua uma tabela personalizada por nome.

Aviso

Essa operação é irreversível e excluirá todos os registros na tabela junto

com a definição da tabela. Utilize com cuidado.

delete_table(table_schema_name: str) -> None

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo, "new_MyTestTable" ou "account").

Exceções

Tipo Description
MetadataError

Se a tabela não existir ou a exclusão falhar.

Exemplos

Excluir uma tabela personalizada:


   client.delete_table("new_MyTestTable")

flush_cache

Liberar metadados de cliente armazenados em cache ou estado.

flush_cache(kind) -> int

Parâmetros

Nome Description
kind
Obrigatório
str

Tipo de cache a ser liberado. Valores com suporte no momento:

  • "picklist": limpa o cache de rótulos de lista de seleção usado para conversão de rótulo para inteiro

Tipos futuros (por exemplo "entityset", , "primaryid") podem ser adicionados sem quebrar essa assinatura.

Retornos

Tipo Description
int

Número de entradas de cache removidas.

Exemplos

Desmarque o cache da lista de seleção:


   removed = client.flush_cache("picklist")
   print(f"Cleared {removed} cached picklist entries")

get

Observação

Preterido. Use get em seu lugar.

Registro único por ID – client.records.get(table, record_id)

Consultar/filtrar vários registros – client.records.get(table, filter=..., select=...)

Buscar um único registro por ID ou consultar vários registros.

Quando record_id for fornecido, retornará um único dicionário de registros. Quando record_id é None, retorna um gerador que produz lotes de registros.

get(table_schema_name: str, record_id: str | None = None, select: List[str] | None = None, filter: str | None = None, orderby: List[str] | None = None, top: int | None = None, expand: List[str] | None = None, page_size: int | None = None) -> Dict[str, Any] | Iterable[List[Dict[str, Any]]]

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
record_id
str

GUID opcional para buscar um registro específico. Se Nenhum, consulta vários registros.

Valor padrão: None
select
list of str

Lista opcional de nomes lógicos de atributo a serem recuperados. Os nomes de coluna não diferenciam maiúsculas de minúsculas e são automaticamente reduzidos (por exemplo, ["new_Title", "new_Amount"] torna-se "new_title,new_amount").

Valor padrão: None
filter
str

Cadeia de caracteres de filtro OData opcional, por exemplo "name eq 'Contoso'" , ou "new_quantity gt 5". Os nomes de coluna em expressões de filtro devem usar nomes lógicos minúsculos exatos (por exemplo "new_quantity", não "new_Quantity"). A cadeia de caracteres de filtro é passada diretamente para a API Web do Dataverse sem transformação.

Valor padrão: None
orderby
list of str

Lista opcional de atributos a serem classificados por, por exemplo. ["name asc", "createdon desc"]. Os nomes de coluna são automaticamente em letras minúsculas.

Valor padrão: None
top
int

Número máximo opcional de registros a serem retornados.

Valor padrão: None
expand
list of str

Lista opcional de propriedades de navegação a serem expandidas, por exemplo. ["primarycontactid"]. Os nomes das propriedades de navegação diferenciam maiúsculas de minúsculas e devem corresponder exatamente aos nomes definidos pelo servidor. Eles NÃO são transformados automaticamente. Consulte os metadados da entidade para o uso correto.

Valor padrão: None
page_size
int

Número opcional de registros por página para paginação.

Valor padrão: None

Retornos

Tipo Description
dict,
Iterable of list of dict

Se for fornecido um único ditado record_id de registro, caso contrário, um gerador produzirá listas de dicionários de registros (uma lista por página).

Exceções

Tipo Description
TypeError

Se record_id for fornecido, mas não uma cadeia de caracteres.

Exemplos

Buscar um único registro:


   record = client.get("account", record_id=account_id, select=["name", "telephone1"])
   print(record["name"])

Consultar vários registros com filtragem (observação: nomes lógicos exatos no filtro):


   for batch in client.get(
       "account",
       filter="statecode eq 0 and name eq 'Contoso'",  # Must use exact logical names (lower-case)
       select=["name", "telephone1"]
   ):
       for account in batch:
           print(account["name"])

Consulta com expansão da propriedade de navegação (observação: nome da propriedade que diferencia maiúsculas de minúsculas):


   for batch in client.get(
       "account",
       select=["name"],
       expand=["primarycontactid"],  # Case-sensitive! Check metadata for exact name
       filter="statecode eq 0"
   ):
       for account in batch:
           print(f"{account['name']} - Contact: {account.get('primarycontactid', {}).get('fullname')}")

Consulta com classificação e paginação:


   for batch in client.get(
       "account",
       orderby=["createdon desc"],
       top=100,
       page_size=50
   ):
       print(f"Batch size: {len(batch)}")

get_table_info

Observação

Preterido. Use get em seu lugar.

Obtenha metadados básicos para uma tabela se ela existir.

get_table_info(table_schema_name: str) -> Dict[str, Any] | None

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo, "new_MyTestTable" ou "account").

Retornos

Tipo Description
dict,
None

Dicionário que contém metadados de tabela com chavestable_schema_name, table_logical_nameentity_set_namee metadata_id. Retorna Nenhum se a tabela não for encontrada.

Exemplos

Recuperar metadados de tabela:


   info = client.get_table_info("new_MyTestTable")
   if info:
       print(f"Logical name: {info['table_logical_name']}")
       print(f"Entity set: {info['entity_set_name']}")

list_tables

Observação

Preterido. Use list em seu lugar.

Liste todas as tabelas não privadas no ambiente do Dataverse.

list_tables() -> list[dict[str, Any]]

Retornos

Tipo Description
list of dict

Lista de dicionários de metadados EntityDefinition.

Exemplos

Liste todas as tabelas não privadas e imprima seus nomes lógicos:


   tables = client.list_tables()
   for table in tables:
       print(table["LogicalName"])

query_sql

Observação

Preterido. Use sql em seu lugar.

Execute uma consulta SQL somente leitura usando a funcionalidade da API ?sql Web do Dataverse.

A consulta SQL deve seguir o subconjunto com suporte: uma única instrução SELECT com WHERE opcional, TOP (literal inteiro), ORDER BY (somente nomes de coluna) e um alias de tabela simples após FROM.

Observação

O suporte ao SQL é limitado a consultas somente leitura. Não há suporte para junções complexas, subconsultas e determinadas funções SQL. Consulte a documentação do Dataverse para o conjunto de recursos atual.

query_sql(sql: str) -> List[Dict[str, Any]]

Parâmetros

Nome Description
sql
Obrigatório
str

Instrução SQL SELECT com suporte.

Retornos

Tipo Description
list of dict

Lista de dicionários de linha de resultados. Retorna uma lista vazia se nenhuma linha corresponder.

Exceções

Tipo Description
SQLParseError

Se a consulta SQL usar uma sintaxe sem suporte.
HttpError

Se a API Web retornar um erro.

Exemplos

Consulta SQL básica:


   sql = "SELECT TOP 10 accountid, name FROM account WHERE name LIKE 'C%' ORDER BY name"
   results = client.query_sql(sql)
   for row in results:
       print(row["name"])

Consulta com alias:


   sql = "SELECT a.name, a.telephone1 FROM account AS a WHERE a.statecode = 0"
   results = client.query_sql(sql)

update

Observação

Preterido. Use update em seu lugar.

Atualize um ou mais registros.

Esse método dá suporte a três padrões de uso:

  1. Atualização de registro único: update("account", "guid", {"name": "New Name"})

  2. Atualização de difusão: update("account", [id1, id2], {"status": 1}) – aplica as mesmas alterações a todas as IDs

  3. Atualizações emparelhadas: update("account", [id1, id2], [changes1, changes2]) – mapeamento um para um

Observação

As atualizações simples descartam a representação de resposta para melhorar o desempenho. Para atualizações de difusão ou emparelhadas, o método delega à lógica de atualização em lote do cliente interno.

update(table_schema_name: str, ids: str | List[str], changes: Dict[str, Any] | List[Dict[str, Any]]) -> None

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
ids
Obrigatório
str ou list of str

Cadeia de caracteres GUID única ou lista de cadeias de caracteres GUID a serem atualizadas.
changes
Obrigatório
dict ou list of dict

Dicionário de alterações para modo de transmissão/único ou lista de dicionários para modo emparelhado. Quando ids é uma lista e changes é um único ditado, as mesmas alterações são transmitidas para todos os registros. Quando ambas são listas, elas devem ter tamanho igual para o mapeamento um-para-um.

Exceções

Tipo Description
TypeError

Se ids não for str ou list[str], ou se changes o tipo não corresponder ao padrão de uso.

Exemplos

Atualização de registro único:


   client.update("account", account_id, {"telephone1": "555-0100"})

Difunda as mesmas alterações para vários registros:


   client.update("account", [id1, id2, id3], {"statecode": 1})

Atualize vários registros com valores diferentes:


   ids = [id1, id2]
   changes = [
       {"name": "Updated Name 1"},
       {"name": "Updated Name 2"}
   ]
   client.update("account", ids, changes)

upload_file

Observação

Preterido. Use upload em seu lugar.

Carregue um arquivo em uma coluna de arquivo do Dataverse.

upload_file(table_schema_name: str, record_id: str, file_name_attribute: str, path: str, mode: str | None = None, mime_type: str | None = None, if_none_match: bool = True) -> None

Parâmetros

Nome Description
table_schema_name
Obrigatório
str

Nome do esquema da tabela.
record_id
Obrigatório
str

GUID do registro de destino.
file_name_attribute
Obrigatório
str

Nome do esquema do atributo de coluna de arquivo.
path
Obrigatório
str

Caminho do sistema de arquivos local para o arquivo.
mode
str

Estratégia de upload: "auto" (padrão) "small"ou "chunk".

Valor padrão: None
mime_type
str

Tipo MIME explícito a ser armazenado com o arquivo.

Valor padrão: None
if_none_match
bool

Quando True (padrão), só terá êxito se a coluna estiver vazia no momento.

Valor padrão: True