Usar el extremo de OData con recursos web Ajax y JScript

 

Publicado: noviembre de 2016

Se aplica a: Dynamics CRM 2015

El extremo OData permite interactuar con los datos de Microsoft Dynamics CRM 2015 y actualización de Microsoft Dynamics CRM Online 2015 mediante las bibliotecas de JavaScript. Crea los recursos web de script mediante archivos que definen las bibliotecas de JavaScript. A continuación, asocia funciones de las bibliotecas con controladores de formularios o eventos de campo o acciones del comando de la cinta. Puede usarlos como cualquier otra biblioteca de JavaScript dentro de los recursos web de la página web (HTML).

En este tema

Ajax

Método que tuneliza a través de una PUBLICACIÓN

Obtenga acceso a la dirección URL del servidor

Utilizar XMLHttpRequest

Utilice jQuery

Trabajar con fechas

Ajax

AJAX (Asincrónico JavaScript y XML) es una técnica de desarrollo web usada para crear aplicaciones web interactivas. Las solicitudes de servidor se efectúan desde el explorador en segundo plano mediante un objeto de XmlHttpRequest. Aunque puede enviar solicitudes sincrónicas, la práctica recomendada es enviar solicitudes asincrónicas. La solicitudes asincrónicas requieren dos funciones de JScript, una para enviar la solicitud y una segunda función de "devolución de llamada" para procesar una respuesta.

JSON

El formato de la notación de objeto (JSON) de JavaScript se usa para serializar y transferir datos estructurados en gran parte de la misma forma en que se utiliza normalmente XML. Al igual que XML, está basado en texto y diseñado para poder ser leído por los humanos. Para convertir objetos de JavaScript normales a formato JSON utilice el método JSON.stringify. Debido a que el texto de JSON define los objetos de JavaScript, el texto se puede convertir en JavaScript mediante el método eval. Sin embargo, esta práctica crea vulnerabilidades de seguridad. En su lugar, debe usar el método JSON.parse.

XmlHttpRequest

XmlHttpRequest (en ocasiones denominado XHR) proporciona funcionalidades para configurar y enviar y solicitudes y definir una función de devolución de llamada si la solicitud es asincrónica. La respuesta HTTP del servidor incluye un código de estado que indica si la solicitud se realizó correctamente. Los valores de código de estado HTTP en el intervalo de 200 se consideran correctos.

XmlHttpRequest proporciona instrucciones al servidor acerca del formato de cualquier dato a incluir en la respuesta. Debido a que el extremo ODATA admite los formatos ATOM y JSON, tiene la opción de solicitar la devolución de datos en formato XMLATOM. No obstante, con el código de JavaScript la solicitud típica esperada usará JSON porque es fácilmente consumible mediante JavaScript.

Método que tuneliza a través de una PUBLICACIÓN

El protocolo OData utiliza menos verbos HTTP comunes PUT y DELETE y define un verbo nuevo: MERGE. En función de las bibliotecas compatibles que usa, puede encontrar problemas mientras usa estos verbos. El modo de resolver esto es usando el verbo POST y especificando un encabezado X-HTTP-MethodHTTP con la acción deseada. Utilice el método setRequestHeader para anular la acción especificada en XmlHttpRequest.

Obtenga acceso a la dirección URL del servidor

Lo primero que hay que hacer cuando se empieza a utilizar el extremo ODATA con JavaScript es establecer la URL en la raíz de la organización URL. Utilice la función getClientUrl del objeto de contexto.

• Si el script se ha diseñado para operar en el contexto de un formulario o de un evento de campo, o un <JavaScriptFunction> (RibbonDiffXml) para un comando de cinta, puede usar el objeto de Xrm.Page.context para llamar a getClientUrl.

• Si el script se ejecuta en el contexto del recurso web de una página web (HTML) deberá incluir una referencia a la página ClientGlobalContext.js.aspx en el recurso web HTML para poder utilizar Función GetGlobalContext.

Utilizar XMLHttpRequest

jQuery es una excelente biblioteca con una gran variedad de usos, pero utilizar jQuery no es un requisito previo para realizar operaciones con el extremo ODATA para Microsoft Dynamics 365. Se recomienda no utilizar jQuery en scripts de formularios o scripts de comando que se ejecuten en páginas de aplicaciones pero que utilicen XmlHttpRequest directamente y eviten tener que cargar la biblioteca jQuery.jQuery**$.ajax** usa la XmlHttpRequest disponible en el explorador. Utilizar este objeto directamente difiere ligeramente de utilizar $.ajax. Si ya está familiarizado con la utilización de XMLHttpRequest, deberá seguir utilizándolo. Si siempre ha utilizado jQuery, considere la posibilidad de utilizar XMLHttpRequest directamente.Más información:XMLHttpRequest Object

Con XmlHttpRequest, cree un controlador de eventos para el evento onreadystatechange y detecte cuándo se finaliza la solicitud. En el controlador de eventos, compruebe el código de estado devuelto para determinar si la solicitud tuvo éxito. Finalmente, use los métodos open y send. El siguiente ejemplo utiliza XmlHttpRequest para crear un nuevo registro de cuenta.

var account = {};
    account.Name = "Sample Account";
    var jsonAccount = JSON.stringify(account);

    var createAccountReq = new XMLHttpRequest();
    createAccountReq.open("POST", Xrm.Page.context.getClientUrl() + "/XRMServices/2011/OrganizationData.svc/AccountSet", true);
    createAccountReq.setRequestHeader("Accept", "application/json");
    createAccountReq.setRequestHeader("Content-Type", "application/json; charset=utf-8");
    createAccountReq.onreadystatechange = function () {
        createAccountReqCallBack(this);
    };
    createAccountReq.send(jsonAccount);

function createAccountReqCallBack(createAccountReq) {
    if (createAccountReq.readyState == 4 /* complete */) {
        createAccountReq.onreadystatechange = null; //avoids memory leaks
        if (createAccountReq.status == 201) {
            //Success
            var newAccount = JSON.parse(createAccountReq.responseText).d;
        }
        else {
            //Failure
            errorHandler(createAccountReq);
        }
    }
};

Para obtener más ejemplos mediante XMLHttpRequest, consulte Ejemplo: crear, recuperar, actualizar y eliminar el uso del extremo de OData con JavaScript

Utilice jQuery

jQuery es una popular biblioteca de JavaScript que se incluye con proyectos de aplicaciones web en Microsoft Visual Studio.jQuery proporciona un amplio marco de objetos y funciones que le permiten consultar y trabajar con las páginas HTML usando JavaScript. Para utilizar XMLHttpRequest, jQuery proporciona el método jQuery.ajax.

Nota

No se recomienda el uso de jQuery con scripts de formularios o comandos.Más información:Uso de jQuery.

Se hace referencia al objeto jQuery mediante el carácter $, por lo que la forma corta de jQuery.ajax es $.ajax. El método ajax se suele usar con una sintaxis imperativa y se envía la solicitud en cuanto se crea una instancia del objeto. El siguiente ejemplo crea un nuevo registro de cuenta.

var account = {};
account.Name = "Sample Account";
var jsonAccount = window.JSON.stringify(account);
$.ajax({
    type: "POST",
    contentType: "application/json; charset=utf-8",
    datatype: "json",
    url: Xrm.Page.context.getClientUrl() + "/XRMServices/2011/OrganizationData.svc/AccountSet",
    data: jsonAccount,
    beforeSend: function (XMLHttpRequest) {
        //Specifying this header ensures that the results will be returned as JSON.
        XMLHttpRequest.setRequestHeader("Accept", "application/json");
    },
    success: function (data, textStatus, XmlHttpRequest) {
        account = data.d;
    },
    error: function (XMLHttpRequest, textStatus, errorThrown) {
        errorHandler(XMLHttpRequest, textStatus, errorThrown);
    }
});

La siguiente tabla enumera las propiedades que tendrá que saber para procesar solicitudes HTTP y respuestas mediante el extremo ODATA para Microsoft Dynamics 365.

Nombre de la propiedad	Tipo	Comentarios
type	string	Utilice GET cuando recupere datos y POST para el resto de operaciones.Más información:Defina explícitamente el encabezado de solicitud en una acción HTTP diferente
contentType	string	Especifica el tipo de contenido enviado al servidor. Utilice application/json; charset=utf-8 cuando esté enviando datos en formato JSON.
dataType	string	El tipo de datos que se espera de devuelva el servidor. Usar json. Nota Solamente configurar esta propiedad puede ser suficiente.Más información:Defina explícitamente el encabezado de solicitud para aceptar JSON
data	object	Defina esto en el valor de un objeto JSON para crear o actualizar operaciones.
url	string	La URL del extremo ODATA adecuada para la acción que está llevando a cabo.
beforeSend	function	Función que le permite modificar el objeto XMLHttpRequest antes de haberlo enviado.
success	function	Función de devolución de llamada cuando se efectúa una solicitud correctamente.Más información:Resultados de proceso
error	function	Función a recuperar si falla una solicitud.Más información:Manejar errores

Para obtener más información, vea Ejemplo: crear, recuperan, actualizar y eliminar el uso del extremo de OData con JavaScript y jQuery.

Defina explícitamente el encabezado de solicitud para aceptar JSON

Si está esperando resultados en formato JSON, puede que ajustar tan solo la propiedad dataType no funcione. Puede usar la propiedad beforeSend para establecer explícitamente los encabezados de XMLHttpRequest para devolver datos como JSON. Esto se lleva a cabo normalmente usando una función anónima tal y como se muestra en el siguiente ejemplo.

beforeSend: function (XMLHttpRequest) {
   //Specifying this header ensures that the results will be returned as JSON.
   XMLHttpRequest.setRequestHeader("Accept", "application/json");}

Cuando se especifica, los errores de XMLHttpRequest.responseText se formatearán en JSON en lugar de en XML.

Sugerencia

Aunque no espere que se devuelva ningún dato, especificar que los resultados se devuelvan siempre mediante JSON simplificará el manejo de los errores.Más información:Manejar errores

Defina explícitamente el encabezado de solicitud en una acción HTTP diferente

Tal y como se describe en Método que tuneliza a través de una PUBLICACIÓN, cuando lleve a cabo una acción que requiera una acción HTTP distinta de POST o GET, utilice POST y la propiedad beforeSend para definir explícitamente los encabezados en XMLHttpRequest para llevar a cabo una acción diferente. Esto se lleva a cabo normalmente usando una función anónima tal y como se muestra en el siguiente ejemplo.

beforeSend: function (XMLHttpRequest) {
   //Specify the HTTP method DELETE to perform a delete operation.
   XMLHttpRequest.setRequestHeader("X-HTTP-Method", "DELETE");
}

Manejar errores

Cuando una solicitud no sea correcta, $.ajax pasará los tres siguientes argumentos a una función establecida en la propiedad de errores.

• XMLHttpRequest
  El objeto XMLHttpRequest.

• textStatus
  Cadena que describe el tipo de error que se ha producido. Los valores posibles son los siguientes:

  • null

  • timeout

  • error

  • notmodified

  • parsererror

• errorThrown
  Un objeto de excepción opcional.

El siguiente ejemplo muestra cómo transferir estos argumentos a una función central que administra errores.

error: function (XMLHttpRequest, textStatus, errorThrown) {
   errorHandler(XMLHttpRequest, textStatus, errorThrown);
}

El siguiente ejemplo muestra una función simple que captura el mensaje de error y muestra el resultado mediante la función showMessage.

Nota

Esta función espera que los detalles del error se devuelvan en formato JSON. A menos que se configure el método $.ajax para devolver resultados mediante JSON, XMLHttpRequest.responseText será XML.

function errorHandler(XMLHttpRequest, textStatus, errorThrown)
{ showMessage("Error : " + textStatus + ": " + JSON.parse(XMLHttpRequest.responseText).error.message.value); }

Resultados de proceso

Cuando ejecute operaciones POST o GET, podrá esperar la devolución de datos. Si ha especificado que los resultados se devuelvan en formato JSON, los resultados estarán en la propiedad d del objeto de datos devuelto. Cuando cree o recupere un registro mediante el identificador único, d representará los datos del registro. En el resto de casos, d será una matriz.

En el siguiente ejemplo se muestra el procesamiento de los resultados de una consulta que devuelve varios registros de cuenta.

success: function (data, textStatus, XmlHttpRequest) {
   var accounts = data.d;
   for (var i in accounts) {   showMessage(accounts[i].Name);
   }}

Trabajar con fechas

Existen cuatro tareas que afectan a las fechas que puede necesitar realizar:

• Análisis de datos recuperados

• Mostrar valores de fecha

• Actualizar valores de fecha

• Establezca una fecha como criterio en un filtro de una consulta

Análisis de datos recuperados

Si recupera registros mediante el extremo ODATA, los valores de las fechas se recuperan como cadenas que utilizan el formato "\/Date(<ticks>)\/" donde <ticks> es el número de milisegundos desde la medianoche del 1 de enero de 1970. Por ejemplo: "\/Date(1311170400000)\/". Todos los valores devueltos de Microsoft Dynamics 365 representan los valores de la hora universal coordinada (UTC) por lo que no se incluye ninguna información de compensación.

Hay dos estrategias que puede usar para analizar las fechas de los registros devueltos mediante el extremo ODATA:

• Utilice una función reviver con el método de JSON.parse

• Utilice String.replace para generar un valor de fecha a partir de una cadena

Utilice una función reviver con el método de JSON.parse

El método JSON.parse admite un argumento reviver opcional como se describe en la documentación del método JSON.parse de MSDN. A continuación se facilita un ejemplo que convierte los valores de cadenas que se corresponden con un patrón definido en una expresión regular en Date.

var jsontext = '{ "hiredate": "\/Date(1311170400000)\/", "birthdate": "\/Date(-158342400000)\/" }';
var dates = JSON.parse(jsontext, dateReviver);
var string = dates.hiredate.toUTCString();
// The value of string is "Wed, 20 Jul 2011 14:00:00 UTC"

function dateReviver(key, value) {
 var a;
 if (typeof value === 'string') {
  a = /Date\(([-+]?\d+)\)/.exec(value);
  if (a) {
   return new Date(parseInt(value.replace("/Date(", "").replace(")/", ""), 10));
  }
 }
 return value;
};

Nota

Este código da por hecho que los valores de fecha siempre serán valores de fecha UTC y no incluirán ninguna información de compensación.

Utilice String.replace para generar un valor de fecha a partir de una cadena

Si no utiliza el argumento reviver con el método JSON.parse, en el siguiente ejemplo se muestra cómo puede generar un valor Date a partir de una cadena.

var dateValue = new Date(parseInt(stringDateValue.replace("/Date(", "").replace(")/", ""), 10));

Mostrar valores de fecha

Una vez convertidos los valores de fecha de cadena en objetos Date, puede usar una variedad de métodos JavaScript o bien crear los suyos propios para mostrar la fecha como una cadena en una interfaz de usuario. Debido a que el objeto JavaScriptDate dispone de reconocimiento de UTC, las fechas mostradas en su interfaz de usuario que utilizan métodos como toString o toLocaleString reflejarán la configuración de la zona horaria del sistema operativo del usuario.

Sin embargo, tenga en cuenta que es posible que los valores de la aplicación sean distintos de los mismos valores mostrados en Microsoft Dynamics 365, que no confía en la configuración de zona horaria del sistema operativo del usuario. Estos valores serán diferentes cuando la zona horaria del sistema operativo actual del usuario no coincide con la preferencia de la zona horaria guardada en Microsoft Dynamics 365.Microsoft Dynamics 365 también permite establecer opciones de presentación personalizadas que no se aplicarán mediantes las funciones de fecha JavaScript estándar como toString.

Si desea reconciliar los valores mostrados de fecha y hora para que coincidan con los valores mostrados en Microsoft Dynamics 365, puede consultar datos almacenados en la entidad UserSettings y entidades como TimeZoneDefinition y TimeZoneRule para crear funciones para mostrar fechas que coincidan con la preferencia de usuario.Microsoft Dynamics 365 no ofrece funciones para realizar estas acciones.

Actualizar valores de fecha

Cuando cambie los valores de una fecha de JavaScript mediante métodos de ajuste estándar como setMinutes o setHours, estos cambios serán en la hora local del usuario. Al guardar el registro, los valores reales de UTC se serializan y se guardan en de nuevo en Microsoft Dynamics 365. No es necesario que realice nada para convertir las fechas en un valor de UTC.

Cuando se serializa una Date, el formato es distinto del formato utilizado al recuperar los datos. Tal y como se indica en Análisis de datos recuperados, las fechas se recuperan como cadenas que utilizan el formato "\/Date(1311179400000)\/". Cuando examina los resultados de JSON.stringify para que los valores de fechas se vuelvan a pasar al servidor, el formato será "2013-07-20T16:30:00Z".

Establezca una fecha como criterio en un filtro de una consulta

Cuando se usa un valor de fecha con una opción de consulta del sistema $filter, debe utilizar una fecha UTC. Para convertir un objeto de JavaScriptDate en el formato esperado para un filtro, es necesario procesar la fecha usando una función similar al siguiente ejemplo. El resultado es una cadena que coincide con el siguiente formato: datetime'2010-09-28T18:21:46:594Z'.

function getODataUTCDateFilter(date) {

 var monthString;
 var rawMonth = (date.getUTCMonth()+1).toString();
 if (rawMonth.length == 1) {
  monthString = "0" + rawMonth;
 }
 else
 { monthString = rawMonth; }

 var dateString;
 var rawDate = date.getUTCDate().toString();
 if (rawDate.length == 1) {
  dateString = "0" + rawDate;
 }
 else
 { dateString = rawDate; }


 var DateFilter = "datetime\'";
 DateFilter += date.getUTCFullYear() + "-";
 DateFilter += monthString + "-";
 DateFilter += dateString;
 DateFilter += "T" + date.getUTCHours() + ":";
 DateFilter += date.getUTCMinutes() + ":";
 DateFilter += date.getUTCSeconds() + ":";
 DateFilter += date.getUTCMilliseconds();
 DateFilter += "Z\'";
 return DateFilter;
}

Ver también

Usar el extremo de OData con recursos web
OData endpoint Http status codes
Bibliotecas de JavaScript para Microsoft Dynamics CRM 2015
Recursos web de script (JScript)
El asociado funciona con eventos de formulario y campo
Método jQuery.ajax
XMLHttpRequest Object
Artículo técnico: Uso de opciones del conjunto de opciones con el extremo ODATA - JScript

© 2017 Microsoft. Todos los derechos reservados. Copyright