Compartir a través de

Ejemplo de operaciones condicionales de 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

Este grupo de ejemplos demuestra cómo realizar operaciones que se basen condicionalmente en la versión del registro de entidad contenido en el servidor de Dynamics 365 y/o mantenido actualmente por el cliente. Para obtener más información, vea Realizar operaciones condicionales mediante la API web. Este ejemplo se implementa como proyecto independiente para los siguientes idiomas:

Ejemplo de operaciones condicionales de la API web (C#)

Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)

La API web de Dynamics 365 sigue las convenciones del protocolo OData v4.0, que usa ETags para implementar el control de versiones del recurso. Las operaciones condicionales de la API web dependen de este mecanismo de versiones.

En este tema se explican la estructura y el contenido de los ejemplos en un nivel superior de lenguaje neutro. Detalla las solicitudes y las respuestas HTTP, y la salida del programa asociada, en el caso correspondiente. Revise los temas de ejemplo vinculados anteriores para obtener implementaciones específicas del idioma y detalles relacionados sobre cómo realizar las operaciones descritas en este tema.

Demostraciones

Este ejemplo se divide en tres secciones principales, enumeradas en la tabla siguiente. Cada sección contiene un conjunto de operaciones de la API web relacionadas que se discuten minuciosamente en la sección conceptual asociada del tema Realizar operaciones condicionales mediante la API web.

Sección de código

Temas conceptuales asociados

GET condicional

Recuperaciones condicionales

Simultaneidad optimista al eliminar y actualizar

Aplicar simultaneidad optimista

Controlar operaciones de upsert

Limitar operaciones de upsert

Las siguientes secciones contienen una breve explicación de las operaciones de la API web de Dynamics 365 realizadas, junto con mensajes HTTP correspondientes y la salida asociada de la consola, que es la misma para cada implementación de idioma. Para razones de brevedad, se han omitido los encabezados HTTP menos pertinentes. Las URI de los registros variarán con la dirección de la organización base y el identificador del registro asignado por el servidor de Dynamics 365.

Datos de ejemplo

El ejemplo crea el registro siguiente antes de que ejecuten las secciones de código principales.

Tipo de entidad

Propiedades asignadas por el cliente

Propiedades asignadas por el servidor

account EntityType

Nombre: Contoso Ltd.
Ingresos: 5000000
Teléfono: 555-0000
Descripción: Parent company of Contoso Pharmaceuticals, etc.

Id: 14e151db-9b4f-e611-80e0-00155da84c08
Etag inicial: W/"628448"

GET condicional

Esta sección del programa muestra cómo realizar recuperaciones condicionales para optimizar el ancho de banda de red y el procesamiento del servidor mientras se mantiene el estado del registro más actual en el cliente.Más información:Recuperaciones condicionales

  1. Intente recuperar la cuenta Contoso Ltd. solo si no coincide con la versión actual, identificada por el valor de ETag inicial que se devolvió al crear el registro de cuenta. Esta condición se representa por el encabezado If-None-Match.

    Solicitud HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

    HTTP/1.1 304 Not Modified

    Salida de la consola

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    El valor de respuesta, 304 Not Modified, indica que el registro actual es el más actual, por lo que el servidor no devuelve el registro solicitado en el cuerpo de respuesta.

  2. Actualice la cuenta modificando su propiedad de número de teléfono principal.

    Solicitud HTTP

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    Respuesta HTTP

    HTTP/1.1 204 No Content

    Salida de la consola

    Account telephone number updated.

  3. Reintente la misma operación GET condicional, de nuevo con el valor de ETag original. Esta vez la operación devuelve los datos solicitados porque la versión en el servidor es diferente (y más reciente) que la versión identificada en la solicitud. Como en todas las recuperaciones de registro, la respuesta incluye un encabezado de ETag que identifica la versión actual.

    Solicitud HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Salida de la consola

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Simultaneidad optimista al eliminar y actualizar

Esta sección del programa muestra cómo realizar operaciones de eliminación y actualización condicionales. El uso más común para tales operaciones es implementar un enfoque de simultaneidad optimista del procesamiento de registros en un entorno multiusuario.Más información:Aplicar simultaneidad optimista

  1. Intente eliminar la cuenta original si y solo si coincide con la versión original (valor de ETag). Esta condición se representa por el encabezado If-Match. Esta operación produce error porque el registro de cuenta se actualizó en la sección anterior, por lo que su versión se actualizó en el servidor.

    Solicitud HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

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

    Salida de la consola

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. Intente actualizar la cuenta si y solo si coincide con el valor de ETag original. Una vez más esta condición está representada por el encabezado If-Match y la operación produce un error por la misma razón.

    Solicitud HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    Respuesta HTTP

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

    Salida de la consola

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. Reintente una actualización, pero en lugar de usar el valor de ETag actual obtenido de la última recuperación de registro de la sección anterior.

    Solicitud HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    Respuesta HTTP

    HTTP/1.1 204 No Content

    Salida de la consola

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. Confirme que la actualización se realizado satisfactoriamente recuperando y generando el estado de cuenta actual. Esto usa una solicitud GET básica.

    Solicitud HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Salida de la consola

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Controlar operaciones de upsert

Esta sección del programa muestra cómo realizar operaciones PATCH condicionales, limitando las operaciones de upsert a realizarse como operaciones solo de actualización o solo de inserción.Más información:Limitar operaciones de upsert

  1. Intente insertar, sin actualizar, las propiedades de teléfono principal e ingresos para esta cuenta. El encabezado If-None-Match con el valor de * representa esta condición de upsert. Esta operación produce error porque este registro de cuenta aún existe en el servidor (a menos que se haya eliminado simultáneamente por otro usuario o proceso).

    Solicitud HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    Respuesta HTTP

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    Salida de la consola

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. Intente realizar la misma operación de actualización sin creación. Para lograrlo, el encabezado If-Match condicional se usa con un valor de *. Esta operación se realiza correctamente porque el registro existe en el servidor.

    Solicitud HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    Respuesta HTTP

    HTTP/1.1 204 No Content

    Salida de la consola

    Account updated using If-Match '*'

  3. Recupere y genere el estado de cuenta actual con una solicitud GET básica. Tenga en cuenta que el valor de ETag devuelto ha cambiado para reflejar la versión nueva y actualizada del registro de cuenta.

    Solicitud HTTP

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Salida de la consola

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. Elimine la cuenta con un DELETE básico.

    Solicitud HTTP

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    Respuesta HTTP

    HTTP/1.1 204 No Content

    Salida de la consola

    Account was deleted.

  5. Igual que en el paso 2, intente actualizar la cuenta si existe. Una vez más, esta condición se representa por el encabezado If-Match con un valor de *. Esta operación produce error porque este registro se acababa de eliminar. Sin embargo, si este encabezado If-Match estaba ausente, la operación básica resultante de upsert debe crear correctamente un nuevo registro.

    Solicitud HTTP

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    Respuesta HTTP

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    Salida de la consola

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

No hay necesidad de limpiar datos de ejemplo porque la cuenta de registro ya se eliminó en el paso 4.

Ver también

Use la API web de Microsoft Dynamics 365
Realizar operaciones condicionales mediante la API web
Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright