Anpassen von Tabellen und Spalten

Das SDK unterstützt Erstellungs-, Aktualisierungs- und Löschvorgänge (CUD) für benutzerdefinierte Tabellen und Spalten, optionale Lösungszuordnung sowie Abrufen und Listentabellendefinitionen.

Sehen wir uns Beispielcode für die Arbeit mit einer benutzerdefinierten Tabelle an.

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

Unterstützte Spaltentypen

Die folgenden Typ-Strings werden von create() und add_columns() akzeptiert.

Typ	Akzeptierte Aliase
string	text
memo	multiline
int	integer
decimal	money
float	double
bool	boolean
datetime	date
file	—

Übergeben Sie für Optionsetspalten (Auswahlspalten) eine IntEnum Unterklasse (oder ein Enum Element mit ganzzahligen Werten) direkt als Spaltentypwert anstelle einer Zeichenfolge. Das SDK verwendet die Klassenmitglieder, um die Optionssatzwerte zu definieren.

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

Festlegen von Spalteneinschränkungen

Wenn Sie Einschränkungen wie Länge, numerischer Bereich, Genauigkeit, Format, erforderliche Ebene oder Anzeigename festlegen möchten, übergeben Sie ein Wörterbuch anstelle eines reinen Typ-Strings. Der type Schlüssel gibt den Spaltentyp an, und die verbleibenden Schlüssel legen die Einschränkungen fest.

Key	Gilt für:	Description
max_length	string, memo	Maximale Anzahl von Zeichen.
min_value, max_value	int, decimal, money, float	Zulässiger numerischer Bereich.
precision	decimal, money, float	Anzahl der Dezimalstellen.
format	string, int, datetime	Formatname für Textspalten (z. B. Email, Url oder Phone) oder das Format für ganze Zahlen und Datums-/Uhrzeitspalten.
required	alle	Erforderliche Ebene: None, Recommended oder ApplicationRequired.
display_name	alle	Anzeigebezeichnung, die im Maker-Portal und in Apps angezeigt wird.

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

Sie können Dict-Spezifikationen überall verwenden, wo ein Spaltentyp akzeptiert wird, einschließlich add_columns() und der Batch-Spaltenerstellung.

Spaltendefinitionen aktualisieren

Verwenden Sie update_column, um die Einschränkungen einer Spalte zu ändern, oder update_columns, um mehrere in einem einzelnen Aufruf zu ändern. Beide akzeptieren die gleichen Überschreibungsschlüssel wie create. Das SDK überprüft jede Spezifikation, bevor es eine Anfrage sendet, sodass ein ungültiger Eintrag den gesamten Aufruf fehlschlagen lässt, ohne frühere Spalten zu ändern.

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

Ein Update ruft die vollständige Spaltendefinition ab, wendet Ihre Änderungen an und sendet die vollständige Definition zurück an Dataverse mit der MSCRM.MergeLabels Kopfzeile. Bezeichnungen in anderen Sprachen bleiben erhalten, sodass das Ändern einer Eigenschaft (z. B. max_length) den Rest der Spalte unverändert lässt.

Eingegebene Spaltenmetadaten lesen

Standardmäßig geben list_columns und get_column die Basisattributemetadaten zurück. Übergeben Sie typed=True, um die typspezifische Definition in einer einzelnen Anforderung abzurufen, die Eigenschaften wie MaxLength für Textspalten oder MinValue und MaxValue für numerische Spalten enthält.

# 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

Der filter Parameter gilt nur für die Standardauflistung (typed=False) . Die Kombination von filter mit typed=True löst ein ValueError aus.

TableInfo-Rückgabeobjekt

Die client.tables.create() -Methode gibt ein TableInfo -Objekt zurück. Greifen Sie direkt auf die Eigenschaften zu, oder verwenden Sie die alte Dictionary-Key-Notation zur Wahrung der Abwärtskompatibilität.

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

Die add_columns()- und remove_columns()-Methoden geben die Liste der Namen der Spaltenschemas zurück, die sie erstellen oder entfernen. Die get() Methode gibt Tabellenmetadaten zurück oder None wenn die Tabelle nicht vorhanden ist, wodurch sie für Existenzprüfungen nützlich ist.

Alternativschlüssel

Ein alternativer Schlüssel identifiziert einen Datensatz anhand einer oder mehrerer geschäftlicher Spalten anstelle einer von Dataverse generierten GUID. Alternative Schlüssel sind für Upsert-Vorgänge erforderlich. Definieren Sie sie im Power Apps Maker-Portal unter Tabelle>Schlüssel oder programmgesteuert mithilfe von 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

Der Übergang von Pending zu Active erfolgt nicht sofort. Überprüfen Sie den Schlüsselstatus direkt nach der Erstellung und warten Sie, bis sein Status Active lautet, bevor Sie Upsert-Anfragen ausgeben. Ohne einen aktiven alternativen Schlüssel lehnt Dataverse Upsert-Anforderungen mit einem Fehler von 400 ab.

Important

Alle benutzerdefinierten Spaltennamen müssen den Präfixwert der Anpassung enthalten (z. B. "new_"). Diese Anforderung stellt eine explizite, vorhersagbare Benennung sicher und entspricht den Dataverse-Metadatenanforderungen.

Weitere Informationen zum Arbeiten mit benutzerdefinierten Tabellenmetadaten:

• tables.create gibt ein TableInfo Objekt zurück, das die neue Tabelle beschreibt. Es werden keine Datensatz-IDs zurückgegeben.
• tables.get gibt None zurück, wenn die Tabelle nicht existiert, sodass die Schema-Einrichtung idempotent wird.
• tables.add_columns und tables.remove_columns geben Sie die Liste der geänderten Spaltennamen zurück.
• tables.list_columns gibt Rohmetadaten-Wörterbücher für Attribute zurück, die die PascalCase-Eigenschaftsnamen der Web-API verwenden, wie LogicalName und AttributeType.

Informationen zum Erstellen, Lesen, Aktualisieren und Löschen von Datensätzen in einer Tabelle finden Sie unter "Arbeiten mit Daten".

Verwandte Informationen

• Tables
• SDK für Python-Codebeispiele
• SDK für Python README

Siehe auch

• Erste Schritte
• Kurzanleitung zu Dataverse