Gerenciar relações de tabela

As relações de tabela no Microsoft Dataverse definem como as linhas de tabela podem ser associadas a linhas de outras tabelas ou da mesma tabela. Há dois tipos de relacionamentos entre tabelas: um-para-muitos e muitos-para-muitos. Você pode criar relações entre tabelas usando as APIs de relação, conforme demonstrado na seção a seguir.

Mais informações: Relações de tabela do Microsoft Dataverse

from PowerPlatform.Dataverse.models import (
    CascadeConfiguration,
    Label,
    LocalizedLabel,
    LookupAttributeMetadata,
    ManyToManyRelationshipMetadata,
    OneToManyRelationshipMetadata,
)

# Create a one-to-many relationship: Department (1) -> Employee (N)
# This adds a "Department" lookup field to the Employee table
lookup = LookupAttributeMetadata(
    schema_name="new_DepartmentId",
    display_name=Label(localized_labels=[LocalizedLabel(label="Department", language_code=1033)]),
)

relationship = OneToManyRelationshipMetadata(
    schema_name="new_Department_Employee",
    referenced_entity="new_department",   # Parent table (the "one" side)
    referencing_entity="new_employee",    # Child table (the "many" side)
    referenced_attribute="new_departmentid",
)

result = client.tables.create_one_to_many_relationship(lookup, relationship)
print(f"Created lookup field: {result.lookup_schema_name}")

# Create a many-to-many relationship: Employee (N) <-> Project (N)
# Employees work on multiple projects; projects have multiple team members
m2m_relationship = ManyToManyRelationshipMetadata(
    schema_name="new_employee_project",
    entity1_logical_name="new_employee",
    entity2_logical_name="new_project",
)

result = client.tables.create_many_to_many_relationship(m2m_relationship)
print(f"Created M:N relationship: {result.relationship_schema_name}")

# Query relationship metadata
rel = client.tables.get_relationship("new_Department_Employee")
if rel:
    print(f"Found: {rel.relationship_schema_name}")

# List all relationships
rels = client.tables.list_relationships()
for rel in rels:
    print(f"{rel['SchemaName']} ({rel.get('RelationshipType')})")

# List relationships for a specific table (one-to-many + many-to-one + many-to-many)
account_rels = client.tables.list_table_relationships("account")
for rel in account_rels:
    print(f"{rel['SchemaName']} -> {rel.get('RelationshipType')}")

# Delete a relationship
client.tables.delete_relationship(result.relationship_id)

Para cenários mais simples, use o método de conveniência.

# Quick way to create a lookup field with sensible defaults
result = client.tables.create_lookup_field(
    referencing_table="contact",       # Child table gets the lookup field
    lookup_field_name="new_AccountId",
    referenced_table="account",        # Parent table being referenced
    display_name="Account",
)

Para obter um exemplo de trabalho completo, consulte exemplos/advanced/relationships.py.

Configurar o comportamento em cascata

CascadeConfiguration controla o que acontece com os registros filho quando você executa uma ação no registro pai em um relacionamento um-para-muitos. Os valores a seguir são válidos para cada propriedade em cascata (assign, , delete, merge, reparent, share, unshare).

Value Behavior
"Cascade" Execute a ação em todos os registros filho associados.
"NoCascade" Não aplique a ação a nenhum registro filho.
"RemoveLink" Remova o valor do campo de referência em todos os registros filhos quando o registro pai for excluído.
"Restrict" Impedir que o registro pai seja excluído quando houver registros filho.

Por padrão, delete é "RemoveLink" e todas as outras propriedades são "NoCascade". Você pode importar as constantes para usar os valores de cadeia de caracteres diretamente.

from PowerPlatform.Dataverse.common.constants import (
    CASCADE_BEHAVIOR_CASCADE,
    CASCADE_BEHAVIOR_NO_CASCADE,
    CASCADE_BEHAVIOR_REMOVE_LINK,
    CASCADE_BEHAVIOR_RESTRICT,
)

relationship = OneToManyRelationshipMetadata(
    schema_name="new_Department_Employee",
    referenced_entity="new_department",
    referencing_entity="new_employee",
    referenced_attribute="new_departmentid",
    cascade_configuration=CascadeConfiguration(delete=CASCADE_BEHAVIOR_REMOVE_LINK),
)

Objeto de retorno RelationshipInfo

Os métodos de criação de relação retornam um RelationshipInfo objeto com os campos a seguir.

Campo Description
relationship_id GUID dos metadados do relacionamento. Passe esse valor para delete_relationship.
relationship_schema_name Nome do esquema da relação.
relationship_type "one_to_many" ou "many_to_many".
lookup_schema_name Nome do esquema do campo de referência criado na tabela filha (somente um-para-muitos).
referenced_entity / referencing_entity Nomes lógicos da tabela pai e da tabela filho (um-para-muitos).
entity1_logical_name / entity2_logical_name Os dois nomes lógicos das tabelas (muitos para muitos).

Note

Se você não fornecer um(a) intersect_entity_name para uma relação muitos-para-muitos, a tabela de interseção usará o(a) schema_name da relação como nome.

opções de create_lookup_field

O create_lookup_field método de conveniência aceita os seguintes parâmetros opcionais.

Parâmetro Padrão Description
display_name Nome da tabela referenciada Nome de exibição exibido para o campo de pesquisa.
description None Descrição opcional para o campo de pesquisa.
required False Indica se o campo de pesquisa é obrigatório.
cascade_delete "RemoveLink" Excluir comportamento em cascata: "RemoveLink", "Cascade"ou "Restrict".
language_code 1033 Código de linguagem (LCID) para rótulos gerados.
solution None Nome exclusivo da solução à qual associar a relação. 
result = client.tables.create_lookup_field(
    referencing_table="new_order",
    lookup_field_name="new_AccountId",
    referenced_table="account",
    display_name="Account",
    required=True,
    cascade_delete="RemoveLink",
)

Importante

Excluir uma relação um-para-muitos também remove o campo de pesquisa associado da tabela filho. Essa operação é irreversível. Você deve excluir os relacionamentos antes de excluir as tabelas que eles conectam. list_table_relationships gerará um MetadataError se a tabela especificada não existir.

Consulte também

  • Last updated on