Trabalhar com chaves alternativas

Chaves alternativas no Microsoft Dataverse permitem identificar exclusivamente linhas de tabela usando colunas de negócios em vez de apenas uma chave primária GUID. Esses identificadores são a chave primária para cada tabela. Quando você precisar se integrar a um armazenamento de dados externo, poderá adicionar uma coluna às tabelas de banco de dados externas para conter uma referência ao identificador exclusivo de uma linha no Dataverse. No entanto, às vezes, você não pode modificar o banco de dados externo. Usando chaves alternativas, você pode definir uma coluna em uma tabela do Dataverse para corresponder a um identificador exclusivo (ou combinação exclusiva de colunas) usado pelo armazenamento de dados externo. Essa chave alternativa pode identificar exclusivamente uma linha no Dataverse no lugar da chave primária. Você deve ser capaz de definir quais colunas representam uma identidade exclusiva para suas linhas. Depois de identificar as colunas exclusivas da tabela, você poderá declará-las como chaves alternativas por meio da interface do usuário (interface do usuário) de personalização ou no código. Este artigo fornece informações sobre como definir chaves alternativas no modelo de dados.

Criar chaves alternativas

Você pode criar chaves alternativas programaticamente ou usando as ferramentas de personalização. Para obter mais informações sobre como usar as ferramentas de personalização, consulte Definir chaves alternativas usando o Power Apps.

Para definir chaves alternativas programaticamente, primeiro crie um objeto de tipo EntityKeyMetadata (ou use EntityKeyMetadata EntityType se estiver trabalhando com a API Web). Essa classe contém as colunas principais. Depois de definir as colunas de chave, use CreateEntityKey para criar as chaves de uma tabela. Essa mensagem usa o nome da tabela e EntityKeyMetadata os valores como entrada para criar a chave.

Lembre-se das seguintes restrições ao criar chaves alternativas:

• Colunas válidas em definições de tabela de chave

  Inclua somente colunas dos seguintes tipos em definições de tabela de chave alternativas:

  Tipo de coluna	Nome de Exibição
  DecimalAttributeMetadata	Número Decimal
  IntegerAttributeMetadata	Número Inteiro
  StringAttributeMetadata	Linha única de texto
  DateTimeAttributeMetadata	Data e Hora
  LookupAttributeMetadata	Buscar
  PicklistAttributeMetadata	Conjunto de opções

• Os atributos não devem ter a segurança em nível de campo aplicada

• Tamanho de chave válido

  Quando você cria uma chave, o sistema valida a chave, incluindo que o tamanho total da chave não viola restrições de índice baseadas em SQL, como 900 bytes por chave e 16 colunas por chave. Se o tamanho da chave não atender às restrições, uma mensagem de erro será exibida.

• Número máximo de definições de tabela de chave secundária para uma tabela

  Uma tabela em uma instância do Dataverse pode ter até dez definições de tabela de chave alternativas.

• Caracteres Unicode no valor da chave

  Se os dados em uma coluna usada em uma chave alternativa contiverem um dos seguintes caracteres /, <, >, *, %, &, :, \\, ?, +, então as ações de recuperação (GET), atualização ou upsert (PATCH) não funcionarão. Se você precisar apenas de exclusividade, essa abordagem funcionará, mas se você precisar usar essas chaves como parte da integração de dados, é melhor criar a chave em colunas que não têm dados com esses caracteres.

• Não há suporte em tabelas virtuais

  Não há suporte para chaves alternativas em tabelas virtuais porque o sistema não pode impor exclusividade quando os dados estão em outro sistema. Para obter mais informações, consulte Introdução às tabelas virtuais (entidades).

Recuperar e excluir chaves alternativas

Para recuperar ou excluir chaves alternativas, use a interface do usuário de personalização. Você não precisa escrever nenhum código. No entanto, o SDK fornece as duas seguintes mensagens para recuperar e excluir chaves alternativas programaticamente:

Para recuperar todas as chaves de uma tabela, use a Keys propriedade de EntityMetadata (EntityMetadata EntityType ou EntityMetadata classe). Ele obtém uma matriz de chaves para uma tabela.

Use essa consulta de API Web para exibir todas as tabelas e ver quais têm chaves alternativas:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$expand=Keys($select=KeyAttributes)

Alguns exemplos retornados por esta solicitação:

{
    "SchemaName": "Account",
    "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84",
    "Keys": [
        {
            "KeyAttributes": [
                "accountnumber"
            ],
            "MetadataId": "1dc7b1d2-6beb-ec11-bb3d-0022482ea769"
        }
    ]
},
{
    "SchemaName": "example_Table",
    "MetadataId": "8f521e41-8934-ec11-b6e6-002248242f3b",
    "Keys": [
        {
            "KeyAttributes": [
                "example_key1",
                "example_key2"
            ],
            "MetadataId": "2f16d0c6-88ea-ec11-bb3d-0022482ea769"
        }
    ]
}

Monitorar a criação de índice para chaves alternativas

As chaves alternativas usam índices de banco de dados para impor a exclusividade e otimizar o desempenho da pesquisa. Se uma tabela tiver muitos registros existentes, a criação de um índice poderá levar muito tempo. Para tornar a interface do usuário de personalização e a importação de solução mais responsivas, crie o índice em um processo em segundo plano. A EntityKeyMetadata.AsyncJob propriedade (EntityKeyMetadata EntityType ou EntityKeyMetadata) refere-se ao trabalho assíncrono que cria o índice. A propriedade EntityKeyMetadata.EntityKeyIndexStatus especifica o status da chave à medida que seu trabalho de criação de índice progride. O status pode ser qualquer um dos seguintes valores:

• Pendente
• Em Andamento
• Ativo
• Falha

Quando você cria uma chave alternativa usando a API e a criação do índice falha, você pode exibir detalhes sobre a causa da falha, corrigir os problemas e reativar a solicitação de chave usando a ReactivateEntityKey (Ação ReactivateEntityKey ou mensagem ReactivateEntityKeyRequest).

Se você excluir a chave alternativa enquanto um trabalho de criação de índice ainda estiver pendente ou em andamento, o trabalho será cancelado e o índice será excluído.

Consulte também

Usar uma chave alternativa para fazer referência a um registro
Use o controle de alterações para sincronizar dados com sistemas externos
Usar o Upsert para inserir ou atualizar um registro
Definir chaves alternativas para referenciar registros