Ejecute las operaciones por lotes mediante API web

  • Artículo

 

Publicado: enero de 2017

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

Puede agrupar varias operaciones en una sola solicitud HTTP con una operación por lotes.

En este tema

Cuándo usar solicitudes por lotes

Solicitudes por lotes

Conjuntos de cambios

Ejemplo

Cuándo usar solicitudes por lotes

El valor que las solicitudes por lotes proporcionan es que pueden incluir conjuntos de cambios, que proporcionan una forma de empaquetar varias operaciones que se realizan correcta o incorrectamente como grupo. en una transacción. En comparación con otras operaciones que se pueden realizar a través de la API web, estas son más difíciles de crear sin algún modelo de objetos que incluya la serialización de objetos o una descripción más profunda del protocolo HTTP porque el cuerpo de la solicitud es esencialmente un documento de texto que debe cumplir requisitos muy específicos.

Recuerde que las entidades asociadas se pueden crear en una sola operación más fácilmente que usando una solicitud por lotes. La solicitudes por lotes son más convenientes al realizar operaciones en entidades que no están asociadas entre sí cuando todas las operaciones se deben realizar en una sola operación transaccional.

Además, las respuestas devueltas son esencialmente documentos de texto en lugar de objetos que pueden fácilmente ser analizados en JSON. Necesitará analizar el texto de la respuesta o localizar una biblioteca de código auxiliar para tener acceso a los datos de la respuesta.

Solicitudes por lotes

Use una solicitud POST para enviar una operación por lotes que contenga varias solicitudes. Una solicitud por lotes puede incluir solicitudes GET y conjuntos de cambios. Para usar las funcionalidades transaccionales de solicitudes por lotes, solo las operaciones que cambiarán datos se pueden incluir en un conjunto de cambios. Las solicitudes GET no se deben incluir en el conjunto de cambios.

La solicitud POST que contiene el lote debe tener un encabezado del tipo contenido con un valor establecido como multiparte/mixto con un conjunto de límites para incluir el identificador del lote utilizando este patrón:

--batch_<unique identifier>

El identificador único no necesita ser un GUID, pero debe ser único. Cada elemento dentro del lote debe ir precedido del identificador de lote con un encabezado Content-Type y Content-Transfer-Encoding como el siguiente:

--batch_WKQS9Yui9r
Content-Type: application/http
Content-Transfer-Encoding:binary

El final del lote debe contener un indicador de finalización como el siguiente:

--batch_WKQS9Yui9r--

Nota

La preferencia de odata.continue-on-error no es compatible con la API web. Los errores que se producen en el lote detendrán el procesamiento del resto del lote.

Conjuntos de cambios

Cuando un conjunto de cambios contiene varias operaciones, todas ellas se consideran atómicas, lo que significa que si alguna de las operaciones produce error, se revertirán las operaciones completadas. Como una solicitud de lote, los conjuntos de cambios deben tener un encabezado de tipo contenido con un valor establecido como multiparte/mixto con un conjunto de límites para incluir el identificador del conjunto de cambios utilizando este patrón:

--changeset_<unique identifier>

El identificador único no necesita ser un GUID, pero debe ser único. Cada elemento dentro del conjunto de cambios debe ir precedido del identificador de conjunto de cambios con un encabezado Content-Type y Content-Transfer-Encoding como el siguiente:

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary

Los conjuntos de cambio también pueden incluir un encabezado Content-ID con un valor único. Este valor, cuando va precedido de $, representa una variable que contiene la Uri para cualquier entidad creada en esa operación. Por ejemplo, cuando establece el valor de 1, puede hacer referencia a esa entidad usando $1 más adelante en el conjunto de cambios.

El final del conjunto de cambios debe contener un indicador de finalización como el siguiente:

--changeset_BBB456--

Ejemplo

El siguiente ejemplo incluye un lote con un identificador único de AAA123 y un conjunto de cambios establecido con un identificador único de BBB456.

Dentro del conjunto de cambios, se crean dos tareas usando POST y se asocian con una cuenta existente con accountid = 00000000-0000-0000-000000000001.

Finalmente, se incluye una solicitud GET fuera del conjunto de cambios para devolver las seis tareas asociadas con la cuenta, incluidas las dos que se crearon en la solicitud de lote.

  • Solicitud

    POST cc_WebAPI_ServiceURI/$batch HTTP/1.1
Content-Type: multipart/mixed;boundary=batch_AAA123
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

--batch_AAA123
Content-Type: multipart/mixed;boundary=changeset_BBB456

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 1

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 1 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 2

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 2 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456--

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding:binary

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)/Account_Tasks?$select=subject HTTP/1.1
Accept: application/json

--batch_AAA123--

  • Respuesta

    --batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: multipart/mixed; boundary=changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc

--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc--
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#tasks(subject)","value":[
    {
      "@odata.etag":"W/\"474122\"","subject":"Task Created with Test Account","activityid":"919c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474125\"","subject":"Task 1","activityid":"a29c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474128\"","subject":"Task 2","activityid":"a39c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474131\"","subject":"Task 3","activityid":"a49c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474134\"","subject":"Task 1 in batch","activityid":"a59c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474137\"","subject":"Task 2 in batch","activityid":"a69c24f3-fafc-e411-80dd-00155d2a68cb"
    }
  ]
}
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f--

Ver también

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