Actualizar y eliminar entidades mediante la API web

  • Artículo

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Las operaciones para modificar datos son una parte básica de la API web. Además de una simple actualización y eliminación, puede realizar operaciones en atributos individuales y crear solicitudes upsert que actualizarán o insertarán una entidad en función de si existe.

Nota

Los metadatos que definen las entidades se actualizan de otra manera.Más información:Crear y actualizar definiciones de entidad mediante la API web

En este tema

Actualización básica

Actualizar con datos devueltos

Actualizar un solo valor de propiedad

Eliminar un solo valor de propiedad

Aplicar Upsert a una entidad

Eliminación básica

Actualización básica

Las operaciones de actualización usan el verbo HTTP PATCH. Pase un objeto JSON que contenga las propiedades que desee actualizar a la URI que representa la entidad. Se devolverá una respuesta con un estado de 204 si la actualización es correcta.

Este ejemplo actualiza un registro de cuenta existente con el valor accountid de 00000000-0000-0000-0000-000000000001.

Importante

Al actualizar una entidad, incluya únicamente las propiedades que está modificando en el cuerpo de la solicitud. Actualizando simplemente las propiedades de una entidad que recuperó anteriormente, e incluyendo ese JSON en su solicitud, se actualizará cada propiedad aunque el valor sea el mismo. Esto puede hacer que parezca que las propiedades se han actualizado en auditoría de datos cuando de hecho no han cambiado realmente.

  • Solicitud

    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
}

  • Respuesta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Nota

Vea Asociar entidades en la actualización para obtener información acerca de la asociación de entidades al actualizar.

Actualizar con datos devueltos

Nota

Esta funcionalidad se agregó con Actualización de diciembre de 2016 para Dynamics 365 (online y local).

Para recuperar datos de una entidad que está actualizando puede crear la solicitud PATCH de forma que los datos del registro creado sean devueltos con un estado de 200 (OK). Para obtener su resultado, debe usar la preferencia return=representation en los encabezados de solicitud.

Para controlar qué propiedades se devuelven, anexe la opción de consulta $select a la dirección URL del conjunto de entidades. Se ignorará la opción de consulta $expand si se utiliza.

Este ejemplo actualiza una entidad de cuenta y devuelve los datos solicitados en la respuesta.

  • Solicitud

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

  • Respuesta

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

Actualizar un solo valor de propiedad

Cuando desee actualizar únicamente un solo valor de propiedad, utilice una solicitud PUT con el nombre de propiedad anexado a la Uri de la entidad.

El siguiente ejemplo actualiza la propiedad name de una entidad de cuenta existente con el valor accountid de 00000000-0000-0000-0000-000000000001.

  • Solicitud

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

  • Respuesta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Eliminar un solo valor de propiedad

Para eliminar el valor de una sola propiedad, utilice una solicitud DELETE con el nombre de propiedad anexado a la Uri de la entidad.

El siguiente ejemplo elimina el valor de la propiedad description de una entidad de cuenta existente con el valor accountid de 00000000-0000-0000-0000-000000000001.

  • Solicitud

    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

  • Respuesta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Nota

Esto no se puede usar con una propiedad de navegación de un solo valor para anular la asociación de dos entidades. Para un enfoque alternativo, consulte Quite una referencia a una entidad.

Aplicar Upsert a una entidad

Una operación upsert es exactamente igual que una actualización. Usa una solicitud PATCH y usa una URI para hacer referencia a una entidad específica. La diferencia es que si la entidad no existe, se creará. Si ya existe, será actualizada. Normalmente al crear una nueva entidad usted deja que el sistema asigne un identificador único. Esta es una práctica recomendada. Pero si necesita crear un registro con un valor id específico, una operación upsert proporciona una forma de hacerlo. Esto puede ser útil en una situación en la que esté sincronizando datos en sistemas distintos.

A veces, hay situaciones donde desea realizar upsert, pero desea evitar una de las acciones potenciales predeterminadas: crear o actualizar. Puede lograrlo mediante la adición encabezados If-Match o If-None-Match. Para obtener más información, vea Limitar operaciones de upsert.

Eliminación básica

Una operación de eliminación es muy sencilla. Use el verbo DELETE con la URI de la entidad que desea eliminar. Este mensaje de ejemplo elimina una entidad de cuenta con el valor de clave principal accountid igual a 00000000-0000-0000-0000-000000000001.

  • Solicitud

    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

  • Respuesta
    Si ya existe la entidad, recibirá una respuesta normal con estado 204 para indicar que la eliminación fue correcta. Si no se encuentra la entidad, recibirá una respuesta con estado 404.

    HTTP/1.1 204 No Content
OData-Version: 4.0

Ver también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de operaciones básicas de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos utilizando la API web
Cree una entidad usando API web
Recuperar una entidad usando API web
Asociar y anular la asociación de entidades mediante la API web
Usar funciones de la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright