Personalización de tablas y columnas

El SDK admite operaciones de creación, actualización y eliminación (CUD) para tablas y columnas personalizadas, asociación de soluciones opcionales, además de definiciones de tabla de recuperación y lista.

Echemos un vistazo al código de ejemplo para trabajar con una tabla 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['LogicalName']} ({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 columna compatibles

Las cadenas de tipo siguientes son aceptadas por create() y add_columns().

Type	Alias aceptados
string	text
memo	multiline
int	integer
decimal	money
float	double
bool	boolean
datetime	date
file	—

Para las columnas de conjunto de opciones (choice), pase directamente una subclase de IntEnum (o un Enum cuyos miembros tengan valores enteros) como valor del tipo de columna en lugar de una cadena. El SDK usa los miembros de clase para definir los valores del conjunto de opciones.

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
})

Establecimiento de restricciones de columna

Para establecer restricciones como longitud, intervalo numérico, precisión, formato, nivel necesario o nombre para mostrar, pase un diccionario en lugar de una cadena de tipo simple. La type key contiene el tipo de columna y las keys restantes establecen las restricciones.

Key	Se aplica a	Description
max_length	string, memo	Número máximo de caracteres.
min_value, max_value	int, decimal, , money, float	Intervalo numérico permitido.
precision	decimal, money, float	Número de decimales.
format	string, int, datetime	Nombre de formato para las columnas de texto (por ejemplo, Email, Url o Phone), o el formato para las columnas de enteros y de fecha/hora.
required	todo	Nivel requerido: None, Recommendedo ApplicationRequired.
display_name	todo	Etiqueta mostrada en el portal del creador y en las aplicaciones.

# Pass a dict spec to set constraints; a bare type string still works for simple columns.
client.tables.create("new_Feedback", {
    "new_Rating":  {"type": "int",  "min_value": 1, "max_value": 5},
    "new_Comment": {"type": "memo", "max_length": 2000, "display_name": "Comment"},
})

Puede usar especificaciones dict en cualquier lugar en que se acepte un tipo de columna, incluidos add_columns() y la creación de columnas por lotes.

Actualizar definiciones de columna

Usa update_column para cambiar las restricciones de una columna o update_columns para cambiar varias en una sola llamada. Ambos aceptan las mismas claves de sobrescritura que create. El SDK valida todas las especificaciones antes de enviar cualquier solicitud, por lo que una entrada no válida hace que falle toda la llamada sin dejar las columnas anteriores modificadas.

# Widen one column
client.tables.update_column("new_Feedback", "new_Comment", {"max_length": 4000})

# Update several columns at once
client.tables.update_columns("new_Feedback", {
    "new_Rating":  {"max_value": 10},
    "new_Comment": {"display_name": "Customer Comment"},
})

Una actualización recupera la definición de columna completa, aplica los cambios y devuelve la definición completa a Dataverse con el MSCRM.MergeLabels encabezado . Las etiquetas de otros lenguajes se conservan, por lo que cambiar una propiedad (por ejemplo, max_length) deja sin cambios el resto de la columna.

Leer metadatos tipados de columna

De forma predeterminada, list_columns y get_column devuelven los metadatos del atributo base. Proporcione typed=True para recuperar la definición específica del tipo en una sola solicitud, que incluye propiedades como MaxLength para columnas de texto o MinValue y MaxValue para columnas numéricas.

# One column, with its type-specific fields
col = client.tables.get_column("new_Feedback", "new_Comment", typed=True)
print(col["MaxLength"])   # 4000

# All columns, each with type-specific fields
cols = client.tables.list_columns("new_Feedback", typed=True)

Note

El filter parámetro solo se aplica a la lista predeterminada (typed=False). Combinar filter con typed=True genera un ValueError.

Objeto devuelto TableInfo

El método client.tables.create() devuelve un objeto TableInfo. Acceda directamente a sus propiedades o use la notación de clave dict heredada para la compatibilidad con versiones 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"])

Los add_columns() métodos y remove_columns() devuelven la lista de nombres de esquema de columna que crean o quitan. El get() método devuelve metadatos de tabla o None si la tabla no existe, lo que hace que sea útil para las comprobaciones de existencia.

Claves alternativas

Una clave alternativa identifica un registro mediante una o varias columnas empresariales en lugar de un GUID generado por Dataverse. Se requieren claves alternativas para las operaciones upsert . Defínalos en el portal para creadores de Power Apps, en Tabla>, o mediante programación con 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}")

Important

La transición de Pending a Active no es inmediata. Compruebe el estado de la clave justo después de su creación y espere hasta que su estado sea Active antes de emitir solicitudes de inserción o actualización. Sin una clave alternativa activa, Dataverse rechaza las solicitudes upsert con un error 400.

Important

Todos los nombres de columna personalizados deben incluir el valor de prefijo de personalización (por ejemplo, "new_"). Este requisito garantiza la nomenclatura explícita y predecible y se alinea con los requisitos de metadatos de Dataverse.

Para obtener más información sobre cómo trabajar con metadatos de tabla personalizados:

• tables.create devuelve un TableInfo objeto que describe la nueva tabla. No devuelve identificadores de registro.
• tables.get devuelve None cuando la tabla no existe, lo que hace que la configuración del esquema sea idempotente.
• tables.add_columns y tables.remove_columns devuelven la lista de nombres de columna que cambiaron.
• tables.list_columns devuelve diccionarios de metadatos de atributos sin procesar que usan los nombres de propiedad en PascalCase de la Web API, como LogicalName y AttributeType.

Para crear, leer, actualizar y eliminar registros en una tabla, consulte Trabajar con datos.

Información relacionada

• Tablas
• Ejemplos de código del SDK para Python
• SDK para Python README

Consulte también

• Introducción
• Guía rápida de Dataverse