Condividi tramite

Utilizzare l'endpoint OData con risorse Web Ajax e JScript

  • Articolo

 

Data di pubblicazione: novembre 2016

Si applica a: Dynamics CRM 2015

L'endpoint OData consente di interagire con i dati di Aggiornamento di Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015 utilizzando le librerie JavaScript. È possibile creare risorse Web dello script utilizzando file che definiscono le librerie JavaScript. Quindi associare le funzioni nelle librerie a gestori di eventi di modulo o di campo o ad azioni di comandi della barra multifunzione. È possibile utilizzarle come qualsiasi altra libreria JavaScript all'interno di risorse Web di pagine Web (HTML).

In questo argomento

Ajax

Tunneling di metodo tramite POST

Accesso all'URL del server

Utilizzare XMLHttpRequest

Utilizzare jQuery

Utilizzare le date

Ajax

AJAX (Asynchronous JavaScript and XML) è una tecnica di sviluppo Web utilizzata per creare applicazioni Web interattive. Le richieste server vengono effettuate dal browser in background tramite un oggetto XmlHttpRequest. Sebbene sia possibile inviare richieste sincrone, è consigliabile inviare richieste asincrone. Le richieste asincrone richiedono due funzioni JScript: una funzione per inviare la richiesta e una seconda funzione di "callback" per elaborare una risposta.

JSON

Il formato JSON (JavaScript Object Notation) viene utilizzato per serializzare e trasmettere dati strutturati in modo molto simile a quando si utilizza XML. Come in XML, si tratta di testo basato e progettato per essere leggibile dagli utenti. Per convertire normali oggetti JavaScript nel formato JSON si utilizza il metodo JSON.stringify. Poiché il testo in JSON definisce oggetti JavaScript, il testo può essere convertito in oggetti JavaScript utilizzando il metodo eval. Tuttavia, in questo modo si creano vulnerabilità di protezione. Si consiglia invece di utilizzare il metodo JSON.parse.

XmlHttpRequest

XmlHttpRequest (talvolta indicato come XHR) offre funzionalità per configurare e inviare richieste e definire una funzione di callback se la richiesta è asincrona. La risposta HTTP del server include un codice di stato che indica se la richiesta è stata elaborata correttamente. I valori di codice di stato HTTP sotto il 200 indicano esito positivo.

Un oggetto XmlHttpRequest fornisce al server le istruzioni sul formato dei dati da includere nella risposta. Poiché l'endpoint ODATA supporta entrambi i formati ATOM e JSON, è possibile scegliere di richiedere i dati nel formato XMLATOM. Tuttavia, con il codice JavaScript la richiesta tipica prevista utilizzerà il formato JSON perché è facilmente riproducibile con JavaScript.

Tunneling di metodo tramite POST

Il protocollo OData utilizza i verbi HTTP meno comuni, PUT e DELETE, nonché la definizione di un nuovo verbo: MERGE. A seconda delle librerie di supporto utilizzate, l'utilizzo di questi verbi può generare alcuni problemi. Per ovviare a questi problemi, utilizzare il verbo POST e specificare un'intestazione HTTP per il X-HTTP-Method con l'azione desiderata. Utilizzare il metodo setRequestHeader per sostituire l'azione specificata nell'oggetto XmlHttpRequest.

Accesso all'URL del server

La prima cosa da fare quando si inizia a utilizzare l'endpoint ODATA con JavaScript è impostare l'URL all'URL radice dell'organizzazione. Utilizzare la funzione getClientUrl dall'oggetto di contesto.

  • Se lo script è progettato per l'utilizzo nel contesto di un evento di modulo o di campo, oppure di un oggetto <JavaScriptFunction> (RibbonDiffXml) per un comando della barra multifunzione, è possibile utilizzare l'oggetto Xrm.Page.context per chiamare getClientUrl.

  • Se lo script viene eseguito nel contesto di una risorsa Web di pagina Web (HTML), è necessario includere un riferimento alla pagina ClientGlobalContext.js.aspx nella risorsa Web HTML in modo da poter utilizzare la Funzione GetGlobalContext.

Utilizzare XMLHttpRequest

jQuery è una libreria eccezionale con una varietà di usi, ma l'utilizzo di jQuery non è un prerequisito per effettuare operazioni che utilizzano l'endpoint ODATA per Microsoft Dynamics 365. Si consiglia di non utilizzare jQuery negli script di modulo o negli script di comando che vengono eseguiti nelle pagine di applicazione e di utilizzare invece l'oggetto XmlHttpRequest direttamente ed evitare di caricare la libreria jQuery. La libreria jQuery**$.ajax** utilizza l'oggetto XmlHttpRequest disponibile nel browser. L'utilizzo diretto di questo oggetto è leggermente differente dall'utilizzo di $.ajax. Se si ha familiarità con l'utilizzo di XMLHttpRequest, si consiglia di continuare a utilizzare questo oggetto. Se jQuery è già stato utilizzato, si consiglia di utilizzare direttamente XMLHttpRequest.Ulteriori informazioni:Oggetto XMLHttpRequest

Con l'oggetto XmlHttpRequest si crea un gestore eventi per l'evento onreadystatechange e si rileva quando la richiesta è stata completata. Nel gestore eventi controllare il codice di stato restituito per determinare se la richiesta è stata elaborata correttamente. Infine, utilizzare i metodi open e send. Nell'esempio seguente viene utilizzato l'oggetto XmlHttpRequest per creare un nuovo record di account.

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

Per ulteriori esempi con l'utilizzo di XMLHttpRequest, vedere Esempio: creare, recuperare, aggiornare e eliminare utilizzando l'endpoint OData con JavaScript

Utilizzare jQuery

jQuery è una nota libreria JavaScript che viene inclusa con i progetti di applicazioni Web in Microsoft Visual Studio. La libreria jQuery offre un ampio framework di oggetti e funzioni che consentono di creare query e utilizzare le pagine HTML utilizzando JavaScript. Per l'utilizzo dell'oggetto XMLHttpRequest, jQuery fornisce il metodo jQuery.ajax.

Nota

Si consiglia di non utilizzare jQuery con gli script o i comandi di moduli.Ulteriori informazioni:Utilizzare jQuery.

All'oggetto jQuery viene fatto riferimento utilizzando il carattere $, per cui la forma breve di jQuery.ajax è $.ajax. Il metodo ajax viene in genere utilizzato con una sintassi imperativa e la richiesta viene inviata non appena viene creata un'istanza dell'oggetto. Nell'esempio seguente viene creato un nuovo record di account.

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

Nella tabella seguente sono elencate le proprietà che è necessario conoscere per elaborare le richieste e le risposte HTTP che utilizzano l'endpoint ODATA per Microsoft Dynamics 365.

Nome proprietà

Tipo

Commenti

type

string

Utilizzare GET per recuperare i dati e POST per tutte le altre operazioni.Ulteriori informazioni:Definire esplicitamente l'intestazione di richiesta su un'azione HTTP differente

contentType

string

Specifica il tipo di contenuto inviato al server. Utilizzare application/json; charset=utf-8 quando si inviano dati nel formato JSON.

dataType

string

Tipo di dati previsto di ritorno dal server. Utilizzare le json.

Nota

La semplice impostazione di questa proprietà potrebbe non essere sufficiente.Ulteriori informazioni:Definire esplicitamente l'intestazione di richiesta per accettare JSON

data

object

Impostarlo sul valore di un oggetto JSON per le operazioni di creazione o di aggiornamento.

url

string

URL appropriato dell'endpoint ODATA per l'azione che si sta eseguendo.

beforeSend

function

Funzione che consente di modificare l'oggetto XMLHttpRequest prima che sia inviato.

success

function

Funzione di callback quando una richiesta ha esito positivo.Ulteriori informazioni:Elaborare i risultati

error

function

Funzione da chiamare se una richiesta non riesce.Ulteriori informazioni:Gestire gli errori

Per ulteriori informazioni, vedere Esempio: creare, recuperare, aggiornare e eliminare utilizzando l'endpoint OData con JavaScript e jQuery.

Definire esplicitamente l'intestazione di richiesta per accettare JSON

Quando si prevedono i risultati in un formato JSON, la semplice impostazione della proprietà dataType potrebbe non funzionare. È possibile utilizzare la proprietà beforeSend per impostare in modo esplicito le intestazioni sull'oggetto XMLHttpRequest in modo da restituire i dati nel formato JSON. Questa operazione viene in genere eseguita utilizzando una funzione anonima come mostrato nell'esempio seguente.

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

Quando specificato, tutti gli errori in XMLHttpRequest.responseText saranno formattati in JSON anziché in XML.

Suggerimento

Anche quando non è prevista restituzione di dati, l'indicazione che i risultati debbano essere sempre restituiti utilizzando JSON semplificherà la gestione degli errori.Ulteriori informazioni:Gestire gli errori

Definire esplicitamente l'intestazione di richiesta su un'azione HTTP differente

Come descritto in Tunneling di metodo tramite POST, quando si esegue un'azione che richiede un'azione HTTP diversa da POST o GET, utilizzare POST e la proprietà beforeSend per impostare in modo esplicito le intestazioni sull'oggetto XMLHttpRequest per eseguire un'azione differente. Questa operazione viene in genere eseguita utilizzando una funzione anonima, come mostrato nell'esempio seguente.

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

Gestire gli errori

Quando una richiesta non riesce, in $.ajax i tre argomenti seguenti vengono passati a una funzione impostata nella proprietà di errore.

  • XMLHttpRequest
    Oggetto XMLHttpRequest.

  • textStatus
    Stringa che descrive il tipo di errore che si è verificato. I valori possibili sono:

    • null

    • timeout

    • error

    • notmodified

    • parsererror

  • errorThrown
    Oggetto eccezione facoltativo.

Nell'esempio seguente viene mostrato come passare questi argomenti a una funzione centrale che gestisce gli errori.

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

Nell'esempio seguente viene illustrata una funzione semplice che acquisisce il messaggio di errore e visualizza il risultato tramite la funzione showMessage.

Nota

Questa funzione presuppone che tutti i dettagli dell'errore siano restituiti in formato JSON. A meno che il metodo $.ajax non sia configurato per restituire i risultati utilizzando JSON, l'oggetto XMLHttpRequest.responseText è XML.

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

Elaborare i risultati

Quando si eseguono operazioni POST o GET si presuppone che vengano restituiti dei dati. Se è stato specificato che i risultati debbano essere restituiti in formato JSON, i risultati saranno nella proprietà d dell'oggetto dati restituito. Quando si crea o si recupera un record utilizzando l'identificatore univoco, la proprietà d rappresenterà i dati per il record. In ogni altro caso d sarà una matrice.

Nell'esempio seguente viene illustrata l'elaborazione dei risultati di una query che restituisce più record di account.

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

Utilizzare le date

Esistono quattro attività che coinvolgono le date che potrebbe essere necessario eseguire:

  • Analizzare i dati recuperati

  • Visualizzare valori di data

  • Aggiornare i valori di data

  • Impostare una data come criterio di filtro in una query

Analizzare i dati recuperati

Quando si recuperano i record utilizzando l'endpoint ODATA, i valori di data vengono restituiti come stringhe che utilizzano il formato "\/Date(<ticks>)\/", dove <ticks> è il numero di millisecondi trascorsi dal 1 gennaio 1970. Ad esempio: "\/Date(1311170400000)\/". Tutti i valori restituiti da Microsoft Dynamics 365 rappresentano i valori UTC (Coordinated Universal Time), pertanto non viene inclusa alcuna informazione di offset.

Esistono due strategie utilizzabili per analizzare le date nei record restituiti utilizzando l'endpoint ODATA:

  • Utilizzare la funzione reviver con il metodo JSON.parse

  • Utilizzare String.replace per generare un valore di data da una stringa

Utilizzare la funzione reviver con il metodo JSON.parse

Il metodo JSON.parse supporta un argomento reviver facoltativo come descritto nella documentazione sul metodo JSON.parse su MSDN. Nell'esempio seguente vengono convertiti in oggetti Date i valori stringa che corrispondono a un modello definito in un'espressione regolare.

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

Questo codice presuppone che i valori di data siano sempre valori di dati UTC e non includano informazioni di offset.

Utilizzare String.replace per generare un valore di data da una stringa

Se non si utilizza l'argomento reviver con il metodo JSON.parse, nell'esempio seguente viene illustrato come generare un valore di Date da una stringa.

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

Visualizzare valori di data

Dopo che i valori di data stringa vengono convertiti in oggetti Date, è possibile utilizzare vari metodi di JavaScript, o crearne di personali, per visualizzare la data come stringa nell'interfaccia utente. Poiché l'oggetto JavaScriptDate riconosce UTC, le date visualizzate nell'interfaccia utente che utilizzano i metodi come toString o toLocaleString rispecchieranno le impostazioni di fuso orario del sistema operativo dell'utente.

Tuttavia, i valori nell'applicazione dello sviluppatore potrebbero essere diversi dagli stessi valori visualizzati in Microsoft Dynamics 365, il quale non si basa sulle impostazioni del fuso orario del sistema operativo dell'utente. Questi valori saranno differenti quando la preferenza corrente del fuso orario del sistema operativo dell'utente non corrisponde alla preferenza di fuso orario salvata in Microsoft Dynamics 365. In Microsoft Dynamics 365 è inoltre consentita l'impostazione di opzioni di presentazione personalizzate che non saranno applicate utilizzando le funzioni di data JavaScript standard come toString.

Per riconciliare i valori di data e ora visualizzati con i valori mostrati in Microsoft Dynamics 365, è possibile eseguire una query sui dati archiviati in una o più entità di UserSettings, come TimeZoneDefinition e TimeZoneRule, per creare funzioni per visualizzare date che soddisfano le preferenze dell'utente. In Microsoft Dynamics 365 non sono disponibili funzioni per effettuare queste operazioni.

Aggiornare i valori di data

Quando si modificano i valori di una data JavaScript utilizzando i metodi set standard come setMinutes o setHours, queste modifiche vengono apportate nell'ora locale dell'utente. Quando si salva il record, i valori UTC effettivi vengono serializzati e salvati nuovamente in Microsoft Dynamics 365. Non è necessario alcun intervento per convertire le date in un valore UTC.

Quando un oggetto Date viene serializzato, il formato differisce da quello utilizzato nel recupero dei dati. Come descritto in Analizzare i dati recuperati, le date vengono recuperate come stringhe che utilizzano il formato "\/Date(1311179400000)\/". Quando si esaminano i risultati di JSON.stringify per i valori di data da passare nuovamente al server, il formato è "2013-07-20T16:30:00Z".

Impostare una data come criterio di filtro in una query

Quando si utilizza un valore di data con un'opzione di query di sistema $filter, è necessario specificare una data UTC. Per convertire un oggetto Date di JavaScript in un formato previsto per un filtro, è necessario elaborare la data utilizzando una funzione come nell'esempio riportato di seguito. Il risultato è una stringa corrispondente al formato seguente: 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;
}

Vedere anche

Utilizzare l'endpoint OData con risorse Web
OData endpoint Http status codes
Librerie JavaScript per Microsoft Dynamics CRM 2015
Risorse Web per script (JScript)
Associare funzioni con eventi di campo e modulo
metodo jQuery.ajax
Oggetto XMLHttpRequest
Articolo tecnico: utilizzo delle opzioni Set di opzione con l'endpoint OData - JScript

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright