Atualize e elimine linhas de tabela usando a API Web

As operações que modificam dados são uma parte central da Web API. Para além das simples operações de atualização e eliminação, pode realizar operações em colunas de tabela única (atributos de entidade) e compor pedidos upsert que atualizam ou inserem dados dependendo da sua existência.

Atualização básica

As operações de atualização usam o verbo HTTP PATCH . Passe um objeto JSON contendo as propriedades que você deseja atualizar para o URI que representa o registro. Se a atualização for bem-sucedida, a resposta devolve um estado de 204 No Content.

O If-Match: * cabeçalho garante que você não crie um novo registro executando acidentalmente uma operação de upsert. Para mais informações, consulte Impedir que se crie durante o upsert.

Importante

Ao atualizar uma entidade, inclua apenas as propriedades que você está alterando no corpo da solicitação. Ao atualizar uma entidade, incluindo todas as propriedades de uma entidade que foram recuperadas anteriormente, a operação atualiza cada propriedade, mesmo que o valor seja o mesmo. Esta atualização pode causar eventos do sistema que desencadeiam lógica de negócio que espera que os valores tenham mudado. Pode fazer com que as propriedades pareçam atualizadas nos dados de auditoria quando na verdade não mudaram.

Quando atualizar a statecode propriedade, defina sempre o valor desejado statuscode. Os statecode valores e statuscode dependem uns dos outros. Para um dado statecode valor, podem existir múltiplos valores válidos statuscode . No entanto, cada statecode coluna tem um único valor DefaultStatus configurado. Quando atualiza statecode sem especificar um statuscode, o sistema define o valor de estado predefinido. Além disso, se ativares a auditoria na tabela e na statuscode coluna, o valor alterado da statuscode coluna não é capturado nos dados de auditoria a menos que o especifiques na operação de atualização.

Observação

A definição de atributos inclui uma RequiredLevel propriedade. Quando esta propriedade está definida para SystemRequired, não pode definir estes atributos para um valor nulo. Para mais informações, consulte Nível de requisito de atributo.

Este exemplo atualiza um registro de conta existente com o accountid valor de 00000000-0000-0000-0000-000000000001.

Pedido:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Observação

Para informações sobre a associação e dissociação de entidades na atualização, veja Utilização de propriedades de navegação de valor único.

Atualização com dados retornados

Para recuperar dados de uma entidade que está a atualizar, componha o seu PATCH pedido de modo a que devolva dados do registo atualizado com um estado de 200 (OK). Para obter este resultado, use o Prefer: return=representation cabeçalho de pedido.

Para controlar quais as propriedades devolvidas, adicione a $select opção de consulta ao URL do conjunto de entidades. A $expand opção de consulta é ignorada se usada.

Este exemplo atualiza uma entidade de conta e retorna os dados solicitados na resposta.

Pedido:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Resposta:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Atualizar vários registros em uma única solicitação

A maneira mais rápida de atualizar vários registros do mesmo tipo em uma única solicitação é usar a ação UpdateMultiple. Nem todas as tabelas padrão suportam essa ação, mas todas as tabelas elásticas suportam.

Mais informações:

Atualizar um único valor de propriedade

Para atualizar o valor de uma única propriedade, utilize uma requisição PUT e acrescente o nome da propriedade ao URI da entidade.

O exemplo seguinte atualiza a propriedade name da linha existente account com o valor accountid de 00000000-0000-0000-0000-000000000001.

Pedido:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Excluir um único valor de propriedade

Para eliminar o valor de uma única propriedade, use um DELETE pedido com o nome da propriedade anexado ao URI da entidade.

O exemplo seguinte elimina o valor da propriedade description de uma entidade de conta com um valor accountid de 00000000-0000-0000-0000-000000000001.

Pedido:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Resposta:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Observação

Não pode usar esta abordagem com uma propriedade de navegação de valor único para dissociar duas entidades. Para uma abordagem alternativa, veja Dissociar usando uma propriedade de navegação de valor único.

Inserir/atualizar uma linha de tabela

Uma operação upsert é semelhante a uma atualização. Ele usa uma PATCH solicitação e usa um URI para fazer referência a um registro específico. A diferença é que, se o registro não existe, ele é criado. Se já existir, é atualizado.

O Upsert é valioso ao sincronizar dados entre sistemas externos. O sistema externo pode não conter referência à chave primária da tabela Dataverse, por isso pode configurar chaves alternativas para a tabela Dataverse usando valores do sistema externo que identificam de forma única o registo em ambos os sistemas. Para obter mais informações: Definir chaves alternativas para linhas de referência

Você pode ver quaisquer chaves alternativas definidas para uma tabela nas anotações para o tipo de entidade no documento de serviço $metadata. Mais informações: Chaves alternativas.

No exemplo a seguir, há uma tabela com o nome sample_thing que tem uma chave alternativa que se refere a duas colunas: sample_key1 e sample_key2, ambas definidas para armazenar valores inteiros.

Pedido:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

Para ambas as operações de criação ou atualização, obtém a mesma resposta. Repare como o cabeçalho de resposta OData-EntityId utiliza os valores das chaves em vez do identificador GUID da chave primária para o registo.

Resposta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Como a resposta é a mesma, não é possível saber se a operação representou uma Create ou Update operação.

Se precisar de saber, pode usar o cabeçalho do pedido Prefer: return=representation. Ao usar este cabeçalho, recebe uma 201 Created resposta quando um registo é criado e uma 200 OK resposta quando o registo é atualizado. Esta opção adiciona uma Retrieve operação, que tem um impacto no desempenho. Se utilizar o cabeçalho de solicitação Prefer: return=representation, certifique-se de que o seu $select inclua a quantidade mínima de dados, de preferência apenas a coluna de chave primária. Para obter mais informações: Atualizar com dados retornados e Criar com dados retornados.

Ao usar chaves alternativas, não inclua os valores das chaves alternativas no corpo do pedido.

Quando um upsert representa um Update, esses valores de chave alternativos são ignorados. Não é possível atualizar valores de chave alternativos ao usá-los para identificar o registro.
Quando um upsert representa um Create, os valores de chave no URL são definidos para o registo se não estiverem presentes no corpo. Portanto, não há necessidade de incluí-los no corpo da solicitação.

Para obter mais informações: Usar o Upsert para criar ou atualizar um registro

Observação

Normalmente, ao criar um novo registo, deixas o sistema atribuir um valor GUID para a chave primária. Esta prática é a melhor porque o sistema gera chaves otimizadas para o índice e esta escolha melhora o desempenho. Mas se você precisar criar um registro com um valor de chave primária específico, como quando o valor GUID da chave é gerado por um sistema externo, a upsert operação fornece uma maneira de fazer isso.

Impedir a criação ou atualização com atualização/inserção

Por vezes, queres realizar um upsert mas impedir uma das operações potenciais: criar ou atualizar. Pode evitar estas operações usando os cabeçalhos If-Match ou If-None-Match. Para obter mais informações, consulte Limitar operações de atualização/inserção.

Eliminação básica

Uma operação de exclusão é simples. Use o verbo DELETE com o URI da entidade que você deseja excluir. Esta mensagem de exemplo elimina uma entidade de conta cujo valor primário da chave accountid é igual a 00000000-0000-0000-0000-000000000001.

Pedido:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Resposta:

Se a entidade existir, você receberá uma resposta normal com status 204 para indicar que a exclusão foi bem-sucedida. Se a entidade não for encontrada, você receberá uma resposta com o status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Verificar se há registros duplicados

Para obter mais informações sobre como verificar registros duplicados durante uma operação de atualização, consulte Detetar duplicatas durante a operação de atualização usando a API da Web.

Excluir vários registros em uma única solicitação

Para eliminar vários registos do mesmo tipo num único pedido, use a DeleteMultiple ação. As tabelas padrão não suportam a ação DeleteMultiple, mas todas as tabelas elásticas suportam.

Observação

Para tabelas padrão, use o comando BulkDelete. Esta ação permite a eliminação assíncrona de registos que correspondam a uma consulta. Para mais informações, consulte Eliminar dados em massa.

Mais informações:

Atualizar e excluir documentos em partições de armazenamento

Se estiveres a atualizar ou eliminar os dados das tabelas elásticas armazenados nas partições, especifica a chave de partição quando acedes a esses dados.

Para mais informações: Escolher um valor para PartitionId

Consulte também

Feedback

Esta página foi útil?

Last updated on 2026-01-10

Partilhar via

Atualize e elimine linhas de tabela usando a API Web

Atualização básica

Atualização com dados retornados

Atualizar vários registros em uma única solicitação

Atualizar um único valor de propriedade

Excluir um único valor de propriedade

Inserir/atualizar uma linha de tabela

Impedir a criação ou atualização com atualização/inserção

Eliminação básica

Verificar se há registros duplicados

Excluir vários registros em uma única solicitação

Atualizar e excluir documentos em partições de armazenamento

Consulte também

Feedback

Recursos adicionais