Compartilhar via

Atualizar e excluir entidades que usam a API Web

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

As operações de modificação de dados são uma parte principal da API Web. Além de uma atualização e exclusão simples, você pode executar operações em atributos simples e compor solicitações de upsert que atualizarão ou inserirão uma entidade dependendo de sua existência.

Observação

Os metadados que definem entidades são atualizados de uma maneira diferente.Para obter mais informações:Criar e atualizar definições de entidade usando API da Web

Neste tópico

Atualização básica

Atualização com dados retornados

Atualizar o valor de uma única propriedade

Excluir o valor de uma única propriedade

Upsert de uma entidade

Exclusão básica

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

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

Importante

Ao atualizar uma entidade, inclua somente as propriedades que você está alterando no corpo da solicitação. A simples atualização das propriedades de uma entidade que você recuperou anteriormente e a inclusão desse JSON em sua solicitação atualizarão cada propriedade embora o valor seja o mesmo. Isso pode fazer com que as propriedades pareçam ter sido atualizadas nos dados de auditoria quando, na verdade, elas não foram realmente alteradas.

  • Solicitação

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "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

Confira Associar entidades na atualização para obter informações sobre como associar propriedades na atualização.

Atualização com dados retornados

Observação

Esse recurso foi adicionado no Atualização de dezembro de 2016 para Dynamics 365 (online e local).

Para recuperar dados de uma entidade que você esteja atualizando, redija sua solicitação PATCH de modo que os dados do registro criado sejam retornados com um status 200 (OK). Para atingir seu resultado, você precisa usar a preferência return=representation nos cabeçalhos da solicitação.

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

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

  • Solicitação

    PATCH cc_WebAPI_ServiceURI/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

{"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": "cc_WebAPI_ServiceURI/$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 o valor de uma única propriedade

Quando desejar atualizar o valor de uma única propriedade, use uma solicitação PUT com o nome da propriedade acrescentado ao Uri da entidade.

O exemplo a seguir atualiza a propriedade name de uma entidade conta existente com o valor de accountid de 00000000-0000-0000-0000-000000000001.

  • Solicitação

    PUT cc_WebAPI_ServiceURI/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 o valor de uma única propriedade

Para excluir o valor de uma única propriedade, use uma solicitação DELETE com o nome da propriedade acrescentado ao Uri da entidade.

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

  • Solicitação

    DELETE cc_WebAPI_ServiceURI/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 com valor único para desassociar duas entidades. Para ver uma abordagem alternativa, consulte Remover uma referência a uma entidade.

Upsert de uma entidade

Uma operação de upsert é exatamente igual a uma atualização. Ela usa uma solicitação de PATCH e usa um URI para fazer referência a uma entidade específica. A diferença é que, se a entidade não existir, ela será criada. Se já existir, ela será atualizada. Geralmente, ao criar uma nova entidade, você deixa que o sistema atribua um identificador exclusivo. Essa é uma prática recomendada. Mas se for necessário criar um registro com um valor de id específico, uma operação de upsert fornecerá uma maneira para fazer isso. Isso pode ser útil em situações em que você está sincronizando dados em outros sistemas.

Mas há situações em que você quer usar upsert, mas quer evitar uma das ações potenciais padrão: criar ou atualizar. Você pode atingir isso por meio da adição de cabeçalhos If-Match ou If-None-Match. Para obter mais informações, consulte Limite de operações de upsert.

Exclusão básica

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

  • Solicitação

    DELETE cc_WebAPI_ServiceURI/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 já existir, você receberá 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 normal com o status 404.

    HTTP/1.1 204 No Content
OData-Version: 4.0

Confira Também

Amostra de operações básicas API da Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Criar uma entidade usando a API da Web
Recuperar uma entidade usando a API Web
Associar e desassociar entidades usando a API Web
Usar funções da API Web
Use ações API da Web
Executar operações em lote usando a API da WEB
Representar outro usuário usando API da Web
Executar operações condicionais usando A API

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais