Compartilhar via

Atualizar e excluir linhas de tabela usando a API Web

As operações para modificar dados são uma parte central da API Web. Além das operações simples de atualização e exclusão, você pode executar operações em colunas de tabela única (atributos de entidade) e redigir solicitações upsert que atualizarão ou inserirão dados, dependendo de existirem.

Atualização básica

As operações de atualização usam o verbo HTTP PATCH . Passe um objeto JSON que contém 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 cabeçalho If-Match: * garante que você não crie um novo registro executando acidentalmente uma operação upsert. Mais informações: Impedir criação no upsert.

Importante

Ao atualizar uma entidade, inclua apenas as propriedades que você está alterando no corpo da solicitação. Simplesmente 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 disparar 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 na auditoria de dados quando, na verdade, elas não foram realmente alteradas.

Quando você atualiza 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ê atualizar 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. Mais informações: Nível de requisito de atributo

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

Pedir:

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 com valor único para obter informações sobre como associar e desassociar entidades na atualização.

Atualizar com os dados retornados

Para recuperar dados de uma entidade que você está atualizando, você pode redigir 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 solicitação Prefer: return=representation .

Para controlar quais propriedades são retornadas, acrescente a opção $select de consulta à URL ao conjunto de entidades. A opção $expand de consulta será ignorada se usada.

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

Pedir:

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 desta escrita, a ação UpdateMultiple. Nem todas as tabelas padrão dão suporte a essa ação, mas todas as tabelas elásticas dão suporte.

Mais informações:

Atualizar um único valor de propriedade

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

O exemplo a seguir atualiza a name propriedade de uma linha existente account com o accountid valor de 000000000-0000-0000-0000-000000000001.

Pedir:

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 acrescentado ao Uri da entidade.

O exemplo a seguir exclui o valor da propriedade description de uma entidade de conta com o accountid valor de 00000000-0000-0000-0000-000000000001.

Pedir:

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 para desassociar duas entidades. Para obter uma abordagem alternativa, consulte Desassociar com uma propriedade de navegação de valor único.

Executar upsert em uma linha na tabela

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

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. Mais informações: Definir chaves alternativas para linhas de referência

Você pode ver quaisquer chaves alternativas definidas para uma tabela nas anotações do tipo de entidade no documento de serviço denominado $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, que são definidas para armazenar valores inteiros.

Pedir:

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 operações de criação ou atualização, você obtém a mesma resposta. Observe como o cabeçalho de resposta OData-EntityId usa os valores de chave em vez do identificador primário de GUID para o registro.

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, você não consegue saber se a operação representou uma operação Create ou uma operação Update.

Se você precisar saber, poderá usar o cabeçalho da solicitação 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. Essa opção adiciona uma operação Retrieve, que afeta o desempenho. Se você usar o cabeçalho de solicitação Prefer: return=representation, certifique-se de que $select inclua a quantidade mínima de dados, de preferência apenas a coluna de chave primária. Mais informações: atualize com os dados retornados e crie com os 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-chave na URL serão definidos para o registro se eles não estiverem presentes no corpo. Portanto, não é necessário incluí-los no corpo da solicitação.

Mais informações: Usar 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. Essa é uma prática recomendada porque o sistema gera chaves otimizadas para o índice e isso melhora o desempenho. No entanto, se você precisar criar um registro com um valor de chave primária específico, como quando o valor de chave GUID é gerado por um sistema externo, a upsert operação fornece uma maneira de fazer isso.

Impedir a criação ou atualização com upsert

Às vezes, há situações em que você deseja executar um upsert, mas você deseja impedir uma das operações em potencial: criar ou atualizar. Você pode fazer isso usando os cabeçalhos If-Match ou If-None-Match. Para obter mais informações, consulte Limitar operações de upsert.

Exclusão básica

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

Pedir:

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ê obterá uma resposta normal com o 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 se há registros duplicados durante uma operação de atualização, consulte Detectar duplicatas durante a operação De atualização usando a API 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 ação DeleteMultiple . No momento desta escrita, a ação DeleteMultiple é um recurso de pré-visualização. As tabelas padrão não dão suporte a essa ação, mas todas as tabelas elásticas dão suporte.

Observação

Para tabelas padrão, é recomendável usar a ação BulkDelete, que permite a exclusão assíncrona de registros que correspondem a uma consulta. Mais informações: Excluir dados em massa

Mais informações:

Atualizar e excluir documentos em partições de armazenamento

Se você estiver atualizando ou excluindo dados de tabela elástica armazenados em partições, especifique a chave de partição ao acessar esses dados.

Mais informações: Escolhendo um valor 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 Web
Redigir solicitações Http e manipular erros
Consultar dados usando a API Web
Criar uma linha de tabela usando a API Web
Recuperar uma linha de tabela usando a API Web
Associar e desassociar linhas de tabela usando a API Web
Usar funções de API Web
Use ações API da Web
Executar operações em lote usando a API Web
Representar outro usuário usando a API Web
Executar operações condicionais usando a API Web

  • Last updated on