Compartilhar via

Atualizar e excluir linhas de tabela usando a API Web

As operações que modificam 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 compor solicitações upsert que atualizam ou inserem 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. Se a atualização for bem-sucedida, a resposta retornará um status de 204 No Content.

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

Importante

Ao atualizar uma entidade, inclua apenas as propriedades que você está alterando no corpo da solicitação. Se você atualizar uma entidade incluindo todas as propriedades de uma entidade recuperada anteriormente, a operação atualizará cada propriedade mesmo que o valor seja o mesmo. Essa atualização pode causar eventos do sistema que disparam a lógica de negócios que espera que os valores tenham sido alterados. Isso pode fazer com que as propriedades pareçam ser atualizadas na auditoria de dados quando elas não foram realmente alteradas.

Ao atualizar a statecode propriedade, sempre defina o desejado statuscode. Os statecode valores e os valores statuscode dependem uns dos outros. Para um determinado statecode valor, pode haver vários valores válidos statuscode . No entanto, cada statecode coluna tem um único valor DefaultStatus configurado. Quando você atualiza statecode sem especificar um statuscode, o sistema define o valor de status padrão. Além disso, se você habilitar a auditoria na tabela e na statuscode coluna, o valor alterado para a statuscode coluna não será capturado nos dados de auditoria, a menos que você a especifique na operação de atualização.

Observação

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

Para obter informações sobre como associar e desassociar entidades na atualização, consulte Usando propriedades de navegação com valor único.

Atualizar com os dados retornados

Para recuperar dados de uma entidade que você está atualizando, redigir sua PATCH solicitação para que ela retorne dados do registro atualizado com um status de 200 (OK). Para obter esse resultado, use o cabeçalho da solicitação Prefer: return=representation .

Para controlar quais propriedades são retornadas, acrescente a opção $select de consulta à URL do 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. 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

Para atualizar um único valor de propriedade, use uma PUT solicitação e adicione o nome da propriedade ao Uri da entidade.

O exemplo a seguir atualiza a propriedade name de uma linha existente account com o valor accountid de 00000000-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 da conta com o valor accountid 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

Você não pode usar essa abordagem com uma propriedade de navegação de valor único para desassociar duas entidades. Para ver uma abordagem alternativa, consulte Desassociar usando 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 . Usando 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, não inclua 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ê permite que o sistema atribua um valor GUID para a chave primária. Essa prática é melhor porque o sistema gera chaves otimizadas para o índice e essa opção 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, você deseja executar um upsert, mas impedir uma das operações potenciais: criar ou atualizar. Você pode impedir essas operações 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 00000000-0000-0000-0000-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

Para excluir vários registros do mesmo tipo em uma única solicitação, use a ação DeleteMultiple . As tabelas padrão não dão suporte a essa ação, mas todas as tabelas elásticas dão suporte a essa ação DeleteMultiple .

Observação

Para tabelas padrão, use a ação BulkDelete. Essa ação permite a exclusão assíncrona de registros que correspondem a uma consulta. Para obter mais informações, consulte 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