Partilhar via

Atualizar e excluir linhas da tabela usando a API da Web

As operações para modificar dados são uma parte central da API da Web. Além de operações simples de atualização e exclusão, pode-se executar operações em colunas individuais de tabelas (atributos de entidade) e compor solicitações de upsert que atualizarão ou inserirão dados, caso já existam ou não.

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. Uma resposta com um status de 204 No Content será retornada se a atualização for bem-sucedida.

O If-Match: * cabeçalho garante que você não crie um novo registro executando acidentalmente uma operação de upsert. Mais informações: Impedir criação na atualização/inserção.

Importante

Ao atualizar uma entidade, inclua apenas as propriedades que você está alterando no corpo da solicitação. Basta atualizar as propriedades de uma entidade que você recuperou anteriormente e, incluir esse JSON em sua solicitação, atualizará cada propriedade, mesmo que o valor seja o mesmo. Isso pode causar eventos do sistema que podem acionar a lógica de negócios que espera que os valores tenham sido alterados. Isso pode fazer com que as propriedades pareçam ter sido atualizadas nos dados de auditoria quando, na verdade, elas não foram alteradas.

Ao atualizar a statecode propriedade, é importante sempre definir o desejado statuscode. statecode e statuscode têm valores dependentes. Pode haver vários valores válidos statuscode para um determinado statecode valor, mas cada statecode coluna tem um único valor DefaultStatus configurado. Quando você atualiza statecode sem especificar um statuscode, o valor de status padrão será definido pelo sistema. Além disso, quando a auditoria estiver habilitada na tabela e na statuscode coluna, o valor alterado para a statuscode coluna não será capturado nos dados de auditoria, a menos que seja especificado na operação de atualização.

Observação

A definição de atributos inclui uma RequiredLevel propriedade. Quando isso é definido como SystemRequired, você não pode definir esses atributos como um valor nulo. Para obter mais informações: 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

Consulte Usando propriedades de navegação de valor único para obter informações sobre como associar e desassociar entidades na atualização.

Atualização com dados retornados

Para recuperar dados de uma entidade que você está atualizando, você pode compor sua PATCH solicitação para que os dados do registro criado sejam retornados com um status de 200 (OK). Para obter esse resultado, você deve usar o cabeçalho da Prefer: return=representation solicitação.

Para controlar quais propriedades são retornadas, acrescente a $select opção de consulta à 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. No momento em que este documento foi redigido, 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

Quando quiser atualizar apenas um único valor de propriedade, use uma PUT solicitação com o nome da propriedade anexado ao Uri da entidade.

O exemplo a seguir atualiza a name propriedade de uma linha existente account com o accountid valor 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 excluir o valor de uma única propriedade, use uma DELETE solicitação com o nome da propriedade anexado ao Uri da entidade.

O exemplo a seguir exclui o valor da propriedade description de uma entidade de conta com o 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

Isso não pode ser usado com uma propriedade de navegação de valor único no sentido de desassociar duas entidades. Para uma abordagem alternativa, consulte Desassociar uma propriedade de navegação com 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 uma referência à chave primária da tabela Dataverse, portanto, você pode configurar chaves alternativas para a tabela Dataverse usando valores do sistema externo que identificam exclusivamente o registro 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, você 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. Com esse cabeçalho, você obtém uma 201 Created resposta quando um registro é criado e uma 200 OK resposta quando o registro é 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, você não deve incluir os valores de chave alternativos no corpo da solicitação.

  • 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 registro, você permitirá que o sistema atribua um valor GUID para a chave primária. Esta é uma prática recomendada porque o sistema gera chaves que são otimizadas para o índice e isso 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

Às vezes, há situações em que você deseja executar um upsert, mas deseja impedir uma das operações potenciais: criar ou atualizar. Você pode fazer isso usando os If-Match cabeçalhos 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 exclui uma entidade de conta com o valor de chave accountid primária 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

A maneira mais rápida de excluir vários registros do mesmo tipo em uma única solicitação é usar a DeleteMultiple ação. No momento em que este artigo foi escrito, a DeleteMultiple ação é um recurso de visualização. As tabelas padrão não suportam essa ação, mas todas as tabelas elásticas suportam.

Observação

Para tabelas padrão, recomendamos o uso da ação BulkDelete, que permite a exclusão assíncrona de registros que correspondem a uma consulta. Para obter mais informações: Apagar dados em massa

Mais informações:

Atualizar e excluir documentos em partições de armazenamento

Se você estiver atualizando ou excluindo dados de tabelas elásticas armazenados em partições, certifique-se de especificar a chave de partição ao acessar esses dados.

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

Consulte também

Exemplo de operações básicas da API Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Executar operações usando a API da Web
Compor solicitações Http e lidar com erros
Consultar dados usando a API da Web
Criar uma linha de tabela usando a API da Web
Recuperar uma linha de tabela usando a API da Web
Associar e desassociar linhas da tabela usando a API da Web
Usar funções da API da Web
Usar ações da API da Web
Executar operações em lote usando a API da Web
Represente outro usuário usando a API da Web
Executar operações condicionais usando a API da Web

  • Last updated on