Personnaliser des tables et des colonnes

Le Kit de développement logiciel (SDK) prend en charge les opérations de création, de mise à jour et de suppression (CUD) pour les tables et colonnes personnalisées , l’association facultative de solution, ainsi que la récupération et la liste des définitions de tables.

Examinons l’exemple de code permettant d’utiliser une table personnalisée.

# 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")

Types de colonne pris en charge

Les chaînes de type suivantes sont acceptées par create() et add_columns().

Type	Alias acceptés
`string`	`text`
`memo`	`multiline`
`int`	`integer`
`decimal`	`money`
`float`	`double`
`bool`	`boolean`
`datetime`	`date`
`file`	—

Pour les colonnes optionset (choix), passez une IntEnum sous-classe (ou une Enum dont les membres ont des valeurs entières) directement en tant que valeur de type de colonne au lieu d’une chaîne. Le Kit de développement logiciel (SDK) utilise les membres de classe pour définir les valeurs de l’ensemble d’options.

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

Définir des contraintes de colonne

Pour définir des contraintes telles que la longueur, la plage numérique, la précision, le format, le niveau requis ou le nom d’affichage, passez un dictionnaire au lieu d’une chaîne de type nu. La type clé contient le type de colonne et les clés restantes définissent les contraintes.

Clé	S’applique à	Description
`max_length`	`string`, `memo`	Nombre maximal de caractères.
`min_value`, `max_value`	`int`, `decimal`, `money`, `float`	Plage numérique autorisée.
`precision`	`decimal`, `money`, `float`	Nombre de décimales.
`format`	`string`, `int`, `datetime`	Nom du format pour les colonnes de texte (par exemple, `Email`, `Url`ou `Phone`) ou le format des colonnes d’entier et de date/heure.
`required`	all	Niveau requis : `None`, `Recommended`ou `ApplicationRequired`.
`display_name`	all	Libellé d’affichage affiché dans le portail Maker et les applications.

# 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"},
})

Vous pouvez utiliser des spécifications de dictionnaire partout où un type de colonne est accepté, y compris add_columns() et la création de colonnes par lots.

Mettre à jour les définitions de colonnes

Utilisez update_column pour modifier les contraintes d’une colonne, ou update_columns pour en modifier plusieurs en un seul appel. Les deux acceptent les mêmes clés de remplacement que create. Le Kit de développement logiciel (SDK) valide chaque spécification avant d’envoyer une requête, donc une entrée non valide fait échouer l’ensemble de l’appel sans laisser les colonnes antérieures modifiées.

# 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"},
})

Une mise à jour récupère la définition de colonne complète, applique vos modifications et renvoie la définition complète à Dataverse avec l’en-tête MSCRM.MergeLabels . Les étiquettes dans d’autres langues sont conservées. Par conséquent, la modification d’une propriété (par exemple, max_length) laisse le reste de la colonne inchangée.

Lire les métadonnées de colonne typées

Par défaut, list_columns et get_column retournent les métadonnées d’attribut de base. Passez typed=True pour récupérer la définition spécifique au type dans une seule requête, qui inclut des propriétés telles que MaxLength pour les colonnes de texte ou MinValue et MaxValue pour les colonnes numériques.

# 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

Le filter paramètre s’applique uniquement à la liste par défaut (typed=False). Combiner typed=True avec filter entraîne un ValueError.

Objet de retour TableInfo

La méthode client.tables.create() retourne un objet TableInfo. Accédez directement à ses propriétés, ou utilisez l’ancienne notation par clé de dictionnaire pour assurer la rétrocompatibilité.

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"])

Les méthodes add_columns() et remove_columns() retournent la liste des noms de schéma de colonnes qu’elles créent ou suppriment. La get() méthode retourne des métadonnées de table, ou None si la table n’existe pas, ce qui le rend utile pour les vérifications d’existence.

Clés secondaires

Une autre clé identifie un enregistrement par une ou plusieurs colonnes métier au lieu d’un GUID généré par Dataverse. Les clés alternatives sont nécessaires pour les opérations d’upsert. Définissez-les dans le portail de création Power Apps sous Table>, ou par programmation à l’aide de 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 transition de Pending vers Active n’est pas immédiate. Vérifiez l’état de la clé juste après sa création et attendez qu’il passe à Active avant d’envoyer des requêtes d’upsert. Sans clé alternative active, Dataverse rejette les requêtes upsert avec une erreur 400.

Important

Tous les noms de colonnes personnalisés doivent inclure la valeur du préfixe de personnalisation (par exemple, « new_ »). Cette exigence garantit un nommage explicite, prévisible et s’aligne sur les exigences de métadonnées Dataverse.

Pour plus d’informations sur l’utilisation des métadonnées de table personnalisées :

tables.create retourne un TableInfo objet qui décrit la nouvelle table. Il ne retourne pas d’ID d’enregistrement.
tables.get retourne None lorsque la table n’existe pas, ce qui rend idempotent la configuration du schéma.
tables.add_columns et tables.remove_columns retourne la liste des noms de colonnes qui ont changé.
tables.list_columns retourne des dictionnaires de métadonnées d’attribut brut qui utilisent les noms de propriétés PascalCase de l’API Web, tels que LogicalName et AttributeType.

Pour créer, lire, mettre à jour et supprimer des enregistrements dans une table, consultez Utiliser des données.

Voir aussi

Commentaires

Est-ce que cette page vous a été utile?

Dernière mise à jour : 2026-10-08