Personalizar tabelas e colunas

O SDK dá suporte a operações de criação, atualização e exclusão (CUD) para tabelas personalizadas e colunas, associação opcional a soluções, além de recuperar e listar definições de tabelas.

Vamos examinar o código de exemplo para trabalhar com uma tabela personalizada.

# Create a custom table, including the customization prefix value in the schema names for the table and columns.
table_info = client.tables.create("new_Product", {
    "new_Code": "string",
    "new_Description": "memo",
    "new_Price": "decimal",
    "new_Active": "bool"
})

# Create with custom primary column name and solution assignment
table_info = client.tables.create(
    "new_Product",
    columns={
        "new_Code": "string",
        "new_Price": "decimal"
    },
    solution="MyPublisher",  # Optional: add to specific solution
    primary_column="new_ProductName",  # Optional: custom primary column (default is "{customization prefix value}_Name")
)

# Get table information
info = client.tables.get("new_Product")
print(f"Logical name: {info['table_logical_name']}")
print(f"Entity set: {info['entity_set_name']}")

# List all tables
tables = client.tables.list()
for table in tables:
    print(table)

# Add columns to existing table (columns must include customization prefix value)
client.tables.add_columns("new_Product", {"new_Category": "string"})

# Remove columns
client.tables.remove_columns("new_Product", ["new_Category"])

# List all columns (attributes) for a table to discover schema
columns = client.tables.list_columns("account")
for col in columns:
    print(f"{col['name']} ({col.get('AttributeType')})")

# List only specific properties
columns = client.tables.list_columns(
    "account",
    select=["LogicalName", "SchemaName", "AttributeType"],
    filter="AttributeType eq 'String'",
)

# Clean up
client.tables.delete("new_Product")

Tipos de coluna suportados

As cadeias de caracteres de tipo a seguir são aceitas por create() e add_columns().

Tipo Aliases aceitos
string text
memo multiline
int integer
decimal money
float double
bool boolean
datetime date
file —

Para colunas do tipo optionset (escolha), passe diretamente uma subclasse de IntEnum (ou um Enum cujos membros tenham valores inteiros) como valor do tipo da coluna, em vez de uma string. O SDK usa os membros da classe para definir os valores do conjunto de opções.

from enum import IntEnum

class Priority(IntEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

table_info = client.tables.create("new_Task", {
    "new_Title": "string",
    "new_Priority": Priority,   # optionset column
})

Objeto de retorno TableInfo

O client.tables.create() método retorna um TableInfo objeto. Acesse suas propriedades diretamente ou use a notação de chave de ditado herdada para compatibilidade com versões anteriores.

table_info = client.tables.create("new_Product", {"new_Code": "string"})

print(table_info.schema_name)       # new_Product
print(table_info.logical_name)      # new_product
print(table_info.entity_set_name)   # new_products
print(table_info.columns_created)   # ['new_Code', ...]

# Legacy dict-key access still works
print(table_info["table_schema_name"])

Os métodos add_columns() e remove_columns() retornam a lista de nomes dos esquemas de colunas que criam ou removem. O get() método retorna metadados de tabela ou None se a tabela não existe, o que a torna útil para verificações de existência.

Chaves alternativas

Uma chave alternativa identifica um registro por meio de uma ou mais colunas de negócio, em vez de um GUID gerado pelo Dataverse. Chaves alternativas são necessárias para operações upsert . Defina-os no portal do maker do Power Apps em Tabela> ou programaticamente usando client.tables.create_alternate_key.

# Create an alternate key on the accountnumber column
key = client.tables.create_alternate_key(
    "account",
    "account_accountnumber_ak",
    ["accountnumber"],
    display_name="Account Number",
)
print(f"Created key {key.schema_name} ({key.metadata_id}), status={key.status}")

# The key status transitions from Pending to Active asynchronously - poll before upserting
for k in client.tables.get_alternate_keys("account"):
    if k.schema_name == "account_accountnumber_ak":
        print(f"{k.schema_name}: {k.status}")

Importante

A transição de Pending para Active não é imediata. Verifique o status da chave logo após a criação e aguarde até que ele esteja em Active antes de emitir solicitações de upsert. Sem uma chave alternativa ativa, o Dataverse rejeita solicitações upsert com um erro 400.

Importante

Todos os nomes de coluna personalizados devem incluir o valor do prefixo de personalização (por exemplo, "new_"). Esse requisito garante uma nomenclatura explícita e previsível e se alinha aos requisitos de metadados do Dataverse.

Para obter mais informações sobre como trabalhar com metadados de tabela personalizados:

  • create sempre retorna uma lista de GUIDs (length=1 para entrada única).
  • update e delete retorne None para interfaces simples e múltiplas.
  • A passagem de uma lista das cargas úteis para create dispara uma criação em massa e retorna list[str] de IDs.
  • get dá suporte à recuperação de um único registro com ID de registro ou paginação por meio de conjuntos de resultados (é preferível selecionar para limitar as colunas).
  • Para métodos CRUD que recebem um ID de registro, passe a string GUID (com hífens, de 36 caracteres). Parênteses ao redor do GUID são aceitos, mas não são necessários.

Consulte também

  • Last updated on