Realizar operaciones condicionales mediante la API web

 

Publicado: enero de 2017

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

Microsoft Dynamics 365 ofrece compatibilidad con un conjunto de operaciones condicionales que dependen del mecanismo de control de versiones de recursos HTTP estándar conocido como ETags.

En este tema

ETags

Encabezados If-Match e If-None-Match

Recuperaciones condicionales

Limitar operaciones de upsert

Aplicar simultaneidad optimista

ETags

El protocolo HTTP define una etiqueta de entidad, o ETag, para identificar versiones específicas de un recurso. Las ETags son identificadores opacos cuyos valores exactos dependen de la implementación. Los valores de ETag se producen en dos variedades: validación segura y débil. La validación segura indica que un recurso único, identificado mediante un URI específico, será idéntico en el nivel binario si su valor de ETag correspondiente no se modifica. La validación débil solo garantiza que la representación del recurso equivale semánticamente al mismo valor de ETag.

Dynamics 365 genera una propiedad @odata.etag de validación débil para todas las instancias de entidad y esta propiedad se devuelve automáticamente con cada registro de entidad recuperado. Para obtener más información, vea Recuperar una entidad usando API web.

Encabezados If-Match e If-None-Match

Use los encabezados If-Match yIf-None-Match con valores ETag para comprobar si la versión actual de un recurso coincide con la recuperada por última vez, coincide con cualquier versión anterior o no coincide con ninguna versión. Estas comparaciones conforman la base de la compatibilidad de operaciones condicional. Dynamics 365 proporciona ETags para admitir las recuperaciones condicionales, la simultaneidad optimista y las operaciones upsert limitadas.

Advertencia

El código de cliente no debe proporcionar ningún significado al valor específico de una ETag, ni a ninguna relación aparente entre las ETags más allá de la igualdad o la desigualdad. Por ejemplo, no se garantiza que un valor de ETag para una versión más reciente de un recurso sea mayor que el valor de ETag para una versión anterior. Además, el algoritmo usado para generar nuevos valores de ETag puede cambiar desigualdad entre las versiones de un servicio.

Recuperaciones condicionales

Las Etags le permiten optimizar recuperaciones de registros siempre que tenga acceso al mismo registro varias veces. Si ha recuperado previamente un registro, puede pasar el valor de ETag con el encabezado If-None-Match para solicitar que se recuperen datos solo si han cambiado desde la última vez que se recuperaron. Si los datos han cambiado, la solicitud devuelve un estado HTTP de 200 (OK) con los datos más recientes en el cuerpo de la solicitud. Si los datos no han cambiado, se devuelve el código de estado HTTP 304 (Not Modified) para indicar que la entidad no se ha modificado. El siguiente par de mensajes de ejemplo devuelve datos de una entidad de cuenta con el accountid igual a 00000000-0000-0000-0000-000000000001 cuando los datos no se han modificado desde que se recuperaron por última vez.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue   HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  If-None-Match: W/"468026"
  

• Respuesta

  HTTP/1.1 304 Not Modified
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  

Limitar operaciones de upsert

Una operación upsert funciona normalmente creando una entidad si no existe; de lo contrario, actualiza una entidad existente. Sin embargo, las ETags se pueden usar para restringir más upserts para evitar creaciones o actualizaciones.

Evitar crear en upsert

Si actualiza datos y hay alguna posibilidad de que se eliminó la entidad forma intencionada, no resulta conveniente volver a crear la entidad. Para evitar este problema, agregue un encabezado If-Match a la solicitud con un valor de "*".

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

• Respuesta
  Si se encuentra la entidad, recibirá una respuesta normal con estado 204 (No Content). Cuando no se encuentra la entidad, recibirá la siguiente respuesta con estado 404 (Not Found).

  HTTP/1.1 404 Not Found
  OData-Version: 4.0
  Content-Type: application/json; odata.metadata=minimal
  
  {
   "error": {
    "code": "",
    "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
    "innererror": {
     "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
     "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
     "stacktrace": <stack trace removed for brevity>
    }
   }
  }
  

Evitar actualizar en upsert

Si está insertando datos, hay posibilidad de que un registro con el mismo valor id ya exista en el sistema y es posible que no desee actualizarlo. Para evitarlo, agregue un encabezado If-None-Match a la solicitud con un valor de "*".

• 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
  If-None-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
  }
  

• Respuesta
  Si no se encuentra la entidad, recibirá una respuesta normal con estado 204 (No Content). Cuando se encuentra la entidad, recibirá la siguiente respuesta con estado 412 (Precondition Failed).

  HTTP/1.1 412 Precondition Failed
  OData-Version: 4.0
  Content-Type: application/json; odata.metadata=minimal
  
  {
    "error":{
     "code":"",
     "message":"A record with matching key values already exists.",
     "innererror":{
      "message":"Cannot insert duplicate key.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
      "stacktrace":<stack trace removed for brevity>
      }
    }
  }
  

Aplicar simultaneidad optimista

Puede usar simultaneidad optimista para detectar si ha modificado una entidad desde que se recuperó por última vez. Si la entidad que piensa actualizar o eliminar ha cambiado en el servidor desde que la recuperó, no le conviene completar la operación de actualización o eliminación. Aplicando el patrón mostrado aquí puede detectar esta situación, recuperar la versión más reciente de la entidad, y aplicar los criterios necesarios para reevaluar si intentar de nuevo la operación.

Aplicar simultaneidad optimista al eliminar

La siguiente solicitud de eliminación de una cuenta con accountid of00000000-0000-0000-0000-000000000001 produce error porque el valor de ETag enviado con el encabezado If-Match es diferente del valor actual. Si el valor hubiera coincidido, se esperaría un estado 204 (No Content).

• Solicitud

  DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
  If-Match: W/"470867"
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  HTTP/1.1 412 Precondition Failed
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
    "error":{
      "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.",
      "innererror":{
        "message":"The version of the existing record doesn't match the RowVersion property provided.",
        "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
  "stacktrace":"  <stack trace details omitted for brevity>
      }
    }
  }
  

Aplicar simultaneidad optimista al actualizar

La siguiente solicitud de actualización de una cuenta con accountid de 00000000-0000-0000-0000-000000000001 produce error porque el valor de ETag enviado con el encabezado If-Match es diferente del valor actual. Si el valor hubiera coincidido, se esperaría un estado 204 (No Content).

• Solicitud

  PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
  If-Match: W/"470867"
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  
  {"name":"Updated Account Name"}
  

• Respuesta

  HTTP/1.1 412 Precondition Failed
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
    "error":{
      "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.",
      "innererror":{
        "message":"The version of the existing record doesn't match the RowVersion property provided.",
        "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
  "stacktrace":"  <stack trace details omitted for brevity>
      }
    }
  }
  

Ver también

Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de operaciones condicionales 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
Actualizar y eliminar entidades mediante la 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

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright