Compartilhar via

Usar o ponto de extremidade do OData com os recursos da Web JScript e Ajax

  • Artigo

 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

O ponto de extremidade do OData permite interagir com os dados do Atualização do Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015 usando bibliotecas do JavaScript. Crie recursos de script da Web usando arquivos que definem as bibliotecas do JavaScript. Em seguida, associe as funções das bibliotecas com manipuladores de eventos de formulário ou de campo ou com ações do comando da faixa de opções. É possível usá-las como qualquer outra biblioteca do JavaScript nos recursos da Web na página da Web (HTML).

Neste tópico

Ajax

Túnel de método por meio da POSTAGEM

Acesso à URL do servidor

Uso de XMLHttpRequest

Use jQuery

Trabalho com datas

Ajax

O AJAX (JavaScript e XML assíncrono) é uma técnica de desenvolvimento da Web usada para criar aplicativos Web interativos. As solicitações do servidor são feitas a partir do navegador em segundo plano usando um objeto XmlHttpRequest. Embora seja possível enviar solicitações síncronas, é recomendável enviar solicitações assíncronas. As solicitações assíncronas exigem duas funções do JScript: uma para enviar a solicitação e uma segunda função de “retorno de chamada” para processar uma resposta.

JSON

O formato Object Notation (JSON) do JavaScript é usado para serializar e transmitir dados estruturados da mesma forma que o XML é geralmente usado. Assim como o XML, ele é baseado em texto e desenvolvido para ser legível por humanos. Para converter objetos regulares do JavaScript no formato JSON, use o método JSON.stringify. Como o texto no JSON define objetos do JavaScript, o texto poderia ser convertido em objetos do JavaScript usando o método eval. No entanto, essa ação cria vulnerabilidades de segurança. Em vez disso, é necessário usar o método JSON.parse.

XmlHttpRequest

XmlHttpRequest (às vezes conhecido como XHR) fornece recursos para configurar e enviar solicitações e definir uma função de retorno de chamada, caso a solicitação seja assíncrona. A resposta HTTP do servidor inclui um código de status informando se a solicitação foi bem-sucedida. Os valores de código de status em HTTP no intervalo 200 são considerados com êxito.

Um XmlHttpRequest fornece instruções para o servidor sobre o formato dos dados que serão incluídos na resposta. Como o ponto de extremidade ODATA oferece suporte aos formatos ATOM e JSON, você tem a opção de solicitar que os dados sejam retornados no formato XMLATOM. Entretanto, com o código do JavaScript, a solicitação típica esperada usará o JSON, pois ele é facilmente consumível com o JavaScript.

Túnel de método por meio da POSTAGEM

O protocolo OData usa os verbos PUT e DELETE menos comuns em HTTP, além de definir um novo verbo: MERGE. Dependendo das bibliotecas de apoio utilizadas, poderão ocorrer problemas durante o uso desses verbos. A forma de contornar esse problema é usar o verbo POST e especificar um títuloX-HTTP-Method em HTTP com a ação desejada. Use o método setRequestHeader para substituir a ação especificada em XmlHttpRequest.

Acesso à URL do servidor

A primeira coisa a fazer ao começar a usar o ponto de extremidade do ODATA com o JavaScript é estabelecer a URL na URL raiz da organização. Use a função getClientUrl do objeto de contexto.

Uso de XMLHttpRequest

jQuery é uma ótima biblioteca com uma variedade de usos, mas usar jQuery não é um pré-requisito para executar operações com o ponto de extremidade do ODATA para o Microsoft Dynamics 365. É recomendável não usar o jQuery em scripts de formulário ou scripts de comandos que sejam executados em páginas de aplicativo. Em vez disso, use o XmlHttpRequest diretamente e evite o carregamento da biblioteca jQuery.jQuery**$.ajax** usa o objeto XmlHttpRequest disponível no navegador. Usar este objeto diretamente é um pouco diferente de usar $.ajax. Se você já está familiarizado com o uso de XMLHttpRequest, continue a usá-lo. Se você sempre usou jQuery, considere usar XMLHttpRequest diretamente.Para obter mais informações:Objeto XMLHttpRequest

Com o XmlHttpRequest, crie um manipulador de evento do evento onreadystatechange e detecte o momento em que a solicitação é concluída. No manipulador de eventos, verifique o código de status retornado para determinar se a solicitação foi bem-sucedida. Por último, use os métodos open e send. O seguinte exemplo usa o XmlHttpRequest para criar um novo registro de conta.

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 obter mais exemplos com XMLHttpRequest, consulte Exemplo: Criar, recuperar, atualizar e excluir usando o ponto de extremidade OData com JavaScript

Use jQuery

jQuery é uma biblioteca JavaScript popular que está incluída em projetos de aplicativo Web no Microsoft Visual Studio.jQuery fornece uma estrutura extensiva de objetos e funções que permitem que você consulte e trabalhe com páginas HTML usando JavaScript. Para usar o XMLHttpRequest, o jQuery fornece o método jQuery.ajax.

Observação

Não é recomendável usar o jQuery com scripts de comandos ou formulário.Para obter mais informações:Uso do jQuery.

O objeto jQuery é referenciado com o caractere $, para que o formato abreviado de jQuery.ajax seja $.ajax. O método ajax é geralmente usado com uma sintaxe imperativa e a solicitação é enviada assim que uma instância do objeto é criada. O seguinte exemplo cria um novo registro de conta.

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);
    }
});

A tabela a seguir lista as propriedades que você precisa conhecer para processar solicitações e respostas em HTTP usando o ponto de extremidade do ODATA do Microsoft Dynamics 365.

Nome da Propriedade

Tipo

Comentários

type

string

Use GET ao recuperar dados e POST para todas as outras operações.Para obter mais informações:Definição explícita do título da solicitação para uma ação diferente em HTTP

contentType

string

Especifica o tipo de conteúdo enviado ao servidor. Use application/json; charset=utf-8 quando estiver enviando dados no formato JSON.

dataType

string

O tipo de dados esperados que será retornado pelo servidor. Usar json

Observação

Simplesmente definir esta propriedade pode não ser suficiente.Para obter mais informações:Definição explícita do título da solicitação para aceitar JSON

data

object

Defina-a para o valor de um objeto JSON para criar ou atualizar operações.

url

string

A URL do ponto de extremidade do ODATA adequada para a ação que está sendo executada.

beforeSend

function

Uma função que permite modificar o objeto XMLHttpRequest antes que ele seja enviado.

success

function

Uma função de retorno de chamada quando uma solicitação é bem-sucedida.Para obter mais informações:Processamento dos resultados

error

function

Uma função que será chamada se houver falha de uma solicitação.Para obter mais informações:Tratamento de erros

Para obter mais informações, consulte Exemplo: Criar, recuperar, atualizar e excluir usando o ponto de extremidade OData com o JavaScript e jQuery.

Definição explícita do título da solicitação para aceitar JSON

Quando estiver aguardando resultados em um formato JSON, simplesmente definir a propriedade dataType pode não funcionar. É possível usar a propriedade beforeSend para definir explicitamente os títulos em XMLHttpRequest para retornar os dados como JSON. Isso geralmente é executado com o uso de uma função anônima, como mostrado no exemplo a seguir.

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

Quando especificado, todos os erros em XMLHttpRequest.responseText serão formatados em JSON, em vez de XML.

Dica

Mesmo quando não esperar o retorno de dados, especificar que os resultados sejam sempre retornados com JSON simplificará o tratamento de erros.Para obter mais informações:Tratamento de erros

Definição explícita do título da solicitação para uma ação diferente em HTTP

Como descrevemos em Túnel de método por meio da POSTAGEM, ao executar uma ação que exige uma ação em HTTP que não seja POST ou GET, use POST e a propriedade beforeSend para definir explicitamente os títulos em XMLHttpRequest para executar uma ação diferente. Isso geralmente é executado com o uso de uma função anônima, como mostrado no exemplo a seguir.

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

Tratamento de erros

Quando uma solicitação não é bem-sucedida, $.ajax transmitirá os três argumentos a seguir para uma função definida na propriedade de erros.

  • XMLHttpRequest
    O objeto XMLHttpRequest.

  • textStatus
    Uma cadeia de caracteres descreve o tipo de erro ocorrido. Os possíveis valores são:

    • null

    • timeout

    • error

    • notmodified

    • parsererror

  • errorThrown
    Um objeto de exceção opcional.

O seguinte exemplo mostra como transmitir estes argumentos para uma função central que gerencia os erros.

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

O exemplo a seguir mostra uma função simples que captura a mensagem de erro e exibe o resultado usando a função showMessage.

Observação

Esta função espera que todos os detalhes de erros sejam retornados no formato JSON. A menos que o método $.ajax tenha sido configurado para retornar resultados usando o JSON, o XMLHttpRequest.responseText seria XML.

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

Processamento dos resultados

Ao executar as operações POST ou GET, você pode esperar que os dados sejam retornados. Se tiver especificado que os resultados sejam retornados no formato JSON, os resultados estarão localizados na propriedade d do objeto de dados retornado. Ao criar ou recuperar um registro usando o identificador exclusivo, d representará os dados do registro. Em uma a cada duas ocorrências, d será uma matriz.

O exemplo a seguir mostra o processamento dos resultados de uma consulta que retorna vários registros da conta.

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

Trabalho com datas

Há quatro tarefas que envolvem datas que pode ser necessário realizar:

  • Análise dos dados recuperados

  • Exibição dos valores de data

  • Atualização dos valores de data

  • Definição de uma data como critérios de um filtro em uma consulta

Análise dos dados recuperados

Ao recuperar registros usando o ponto de extremidade ODATA, os valores de data são retornados como cadeias de caracteres que usam o formato "\/Date(<ticks>)\/", onde <ticks> é o número em milissegundos desde meia-noite de 1º de janeiro de 1970. Por exemplo: "\/Date(1311170400000)\/". Todos os valores retornados do Microsoft Dynamics 365 representam os valores do Tempo Universal Coordenado (UTC), para que nenhuma informação de compensação seja incluída.

Há duas estratégias que podem ser usadas para analisar datas em registros retornados com o ponto de extremidade do ODATA:

  • Uso de uma função de recuperação com o método JSON.parse

  • Uso de String.replace para gerar um valor de data a partir de uma cadeia de caracteres

Uso de uma função de recuperação com o método JSON.parse

O método JSON.parse oferece suporte a um argumento de recuperação opcional, conforme descrito em Documentação do método JSON.parse no MSDN. O exemplo a seguir é um exemplo que converte os valores da cadeia de caracteres que correspondem a um padrão definido em uma expressão regular dos objetos 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;
};

Observação

Este código pressupõe que os valores de data serão sempre valores de dados UTC e não incluirão nenhuma informação de compensação.

Uso de String.replace para gerar um valor de data a partir de uma cadeia de caracteres

Se você não usa o argumento de recuperação com o método JSON.parse, o exemplo a seguir mostra como gerar um valor de Date a partir de uma cadeia de caracteres.

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

Exibição dos valores de data

Depois que os valores de data da cadeia de caracteres são convertidos em objetos de Date, é possível usar vários métodos do JavaScript, ou criar os seus próprios, para exibir a data como uma cadeia de caracteres em uma interface do usuário. Como o objeto do JavaScriptDate conhece o UTC, as datas exibidas na interface do usuário usando métodos como toString ou toLocaleString refletirão as configurações de fuso horário do sistema operacional do usuário.

Entretanto, observe que os valores no aplicativo podem ser diferentes dos mesmos valores exibidos no Microsoft Dynamics 365, que não dependem das configurações de fuso horário do sistema operacional do usuário. Esses valores serão diferentes quando a preferência atual de fuso horário do usuário do sistema operacional não corresponder à preferência de fuso horário salva no Microsoft Dynamics 365. O Microsoft Dynamics 365 também permite definir opções personalizadas de apresentação que não serão aplicadas usando funções JavaScript padrão de data como toString.

Se desejar reconciliar os valores de data e hora exibidos para que eles correspondam aos valores mostrados no Microsoft Dynamics 365, você pode consultar os dados armazenados na entidade UserSettings e em entidades como TimeZoneDefinition e TimeZoneRule para criar funções para exibir datas que correspondam à preferência do usuário. O Microsoft Dynamics 365 não fornece funções para executar essas ações.

Atualização dos valores de data

Ao alterar os valores de uma data do JavaScript usando métodos padrão definidos como setMinutes ou setHours, essas alterações são realizadas no horário local do usuário. Ao salvar o registro, os valores reais do UTC são serializados e salvos de volta para o Microsoft Dynamics 365. Não é necessário executar nenhuma ação para converter as datas em um valor de UTC.

Quando a Date é serializada, o formato difere do formato usado quando os dados são recuperados. Conforme observado em Análise dos dados recuperados, as datas são recuperadas como cadeias de caracteres que usam o formato "\/Date(1311179400000)\/". Ao examinar os resultados de JSON.stringify para os valores de data que serão transmitidos para o servidor, o formato será "2013-07-20T16:30:00Z".

Definição de uma data como critérios de um filtro em uma consulta

Ao usar o valor de data com uma opção de consulta do sistema de $filter, é necessário usar uma data do UTC. Para converter um objeto Date do JavaScript no formato esperado para um filtro, é necessário processar a data usando uma função conforme o exemplo a seguir. O resultado é uma cadeia de caracteres que correspondente ao seguinte 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;
}

Confira Também

Usar o ponto de extremidade do OData com os recursos da Web
OData endpoint Http status codes
Bibliotecas JavaScript para Microsoft Dynamics CRM 2015
Recursos da Web de script (JScript)
Associar funções a eventos de Formulário e de Campo
método jQuery.ajax
Objeto XMLHttpRequest
Artigo técnico: Como usar as opções do Conjunto de Opções com o ponto de extremidade ODATA – JScript

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais