Het OData-eindpunt gebruiken met Ajax- en JScript-webresources

 

Gepubliceerd: november 2016

Is van toepassing op: Dynamics CRM 2015

Dankzij het OData-eindpunt kunt u werken met Microsoft Dynamics CRM 2015 en Microsoft Dynamics CRM Online 2015 Update-gegevens door JavaScript-bibliotheken te gebruiken. U maakt scriptwebresources met behulp van bestanden die de JavaScript-bibliotheken definiëren. Vervolgens koppelt u functies in de bibliotheken aan formulier- of veldgebeurtenishandlers of lintopdrachtacties. U kunt deze net als andere JavaScript-bibliotheken gebruiken binnen webpaginawebresources (HTML).

In dit onderwerp

Ajax

Methodetunneling met POST

Toegang krijgen tot de server-URL

XMLHttpRequest gebruiken

jQuery gebruiken

Werken met datums

Ajax

AJAX (asynchroon JavaScript en XML) is een webontwikkelingstechniek die wordt gebruikt om interactieve webtoepassingen te maken. Serveraanvragen worden gedaan vanuit de browser op de achtergrond met behulp van een XmlHttpRequest-object. U kunt synchrone aanvragen verzenden, maar de aanbevolen methode is asynchrone aanvragen te verzenden. Asynchrone aanvragen vereisen twee JScript-functies, één om de aanvraag te verzenden en een tweede "callback"-functie om een respons te verwerken.

JSON

De JavaScript Object Notation-indeling (JSON) wordt gebruikt voor het serialiseren en overbrengen van gestructureerde gegevens, op grotendeels dezelfde manier als waarop XML meestal wordt gebruikt. Net als XML is het tekstgebaseerd en ontworpen om leesbaar te zijn voor mensen. Als u normale JavaScript-objecten naar de JSON-indeling wilt converteren, gebruikt u de methode JSON.stringify. Aangezien de tekst in JSON JavaScript-objecten definieert, kan de tekst naar JavaScript-objecten worden geconverteerd met behulp van de methode eval. Deze methode leidt echter tot beveiligingskwetsbaarheden. U zou in plaats daarvan de methode JSON.parse moeten gebruiken.

XmlHttpRequest

XmlHttpRequest (som XHR genoemd) biedt mogelijkheden om aanvragen te configureren en te verzenden en een callbackfunctie te definiëren als de aanvraag asynchroon is. De respons HTTP van de server bevat een statuscode die aangeeft of de aanvraag is geslaagd.HTTP waarden voor de statuscode in het bereik 200 worden gezien als geslaagd.

Een XmlHttpRequest bevat instructies voor de server over de indeling van gegevens die in de respons moeten worden opgenomen. Aangezien het ODATA-eindpunt zowel de indeling ATOM als JSON ondersteunt, kunt u verzoeken dat gegevens worden geretourneerd in de indeling XMLATOM. Met JavaScript-code gebruikt de verwachte, gebruikelijke aanvraag echter JavaScript, omdat dat gemakkelijk bruikbaar is met JSON.

Methodetunneling met POST

Het OData-protocol gebruikt minder algemene HTTP-verbs PUT en DELETE en definieert een nieuwe verb: MERGE. Afhankelijk van de ondersteunende bibliotheken die u gebruikt, kunt u problemen ondervinden bij het gebruik van deze verbs. De manier om dit op te lossen is de verb POST te gebruiken en een X-HTTP-MethodHTTP-koptekst op te geven met de gewenste actie. Gebruik de methode setRequestHeader om de actie te negeren die is opgegeven in de XmlHttpRequest.

Toegang krijgen tot de server-URL

Het eerste wat u moet doen als u het ODATA-eindpunt gebruikt met JavaScript is de URL creëren voor de organisatieroot. URL Gebruik de functie getClientUrl vanuit het contextobject.

• Als uw script is ontworpen om te werken in de context van een formulier- of een veldgebeurtenis, of een <JavaScriptFunction> (RibbonDiffXml) voor een lintopdracht, kunt u het Xrm.Page.context-object gebruiken om getClientUrl aan te roepen.

• Als uw script wordt uitgevoerd in de context van een webpaginawebresource (HTML), moet u een verwijzing naar de ClientGlobalContext.js.aspx-pagina in de HTML-webresource opgeven zodat u vervolgens de Functie GetGlobalContext kunt gebruiken.

XMLHttpRequest gebruiken

jQuery is een handige bibliotheek met een verscheidenheid aan gebruik, maar het gebruik van jQuery is geen vereiste voor het uitvoeren van bewerkingen met het ODATA-eindpunt voor Microsoft Dynamics 365. We raden aan geen gebruik te maken van jQuery in formulierscripts of opdrachtscripts die worden uitgevoerd in toepassingspagina's, maar de XmlHttpRequest rechtstreeks te gebruik en te voorkomen dat u de jQuery-bibliotheek moet laden.jQuery**$.ajax** gebruikt XmlHttpRequest beschikbaar in de browser. Dit object rechtstreeks gebruiken wijkt licht af van het gebruik van $.ajax. Als u al bekend bent met het gebruik van XMLHttpRequest, kunt u het blijven gebruiken. Als u altijd jQuery hebt gebruikt, kunt u overwegen XMLHttpRequest direct te gebruiken.Meer informatie:XMLHttpRequest-object

Met XmlHttpRequest maakt u een gebeurtenishandler voor de gebeurtenis onreadystatechange en detecteert u wanneer de aanvraag is voltooid. Controleer in de gebeurtenishandler de statuscode die wordt geretourneerd om te bepalen of de aanvraag is geslaagd. Gebruik ten slotte de methoden open en send. Het volgende voorbeeld gebruikt XmlHttpRequest om een nieuwe accountrecord te maken.

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

Voor meer voorbeelden van het gebruik van XMLHttpRequest raadpleegt u Voorbeeld: Maken, ophalen, bijwerken en verwijderen via het OData-eindpunt met JavaScript

jQuery gebruiken

jQuery is een populaire JavaScript-bibliotheek met webtoepassingprojecten in Microsoft Visual Studio.jQuery biedt een uitgebreide structuur met objecten en functies waarmee u query's kunt opstellen en kunt werken met HTML-pagina's met JavaScript. Voor gebruik van XMLHttpRequest biedt jQuery de methode jQuery.ajax.

Notitie

We adviseren niet jQuery te gebruiken met formulierscripts of opdrachten.Meer informatie:jQuery gebruiken.

Naar het jQuery-object wordt verwezen met het teken $, dus de korte vorm voor jQuery.ajax is $.ajax. De methode ajax wordt veel gebruikt met een imperatieve syntaxis en de aanvraag wordt verzonden zodra een exemplaar van het object is gemaakt. Het volgende voorbeeld maakt een nieuwe accountrecord.

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

De volgende tabel bevat de eigenschappen die u moet kennen om HTTP-aanvragen en -reacties te verwerken met het ODATA-eindpunt voor Microsoft Dynamics 365.

Eigenschapsnaam	Type	Opmerkingen
type	string	Gebruik GET wanneer u gegevens opvraagt en POST voor alle andere bewerkingen.Meer informatie:De aanvraagkoptekst expliciet instellen op een andere HTTP-actie
contentType	string	Geeft het type inhoud op dat aan de server wordt verzonden. Gebruik application/json; charset=utf-8 wanneer u gegevens verzendt in de JSON-indeling.
dataType	string	Het type verwachte gegevens dat door de server wordt geretourneerd.json gebruiken. Notitie Gewoon deze eigenschap instellen kan onvoldoende zijn.Meer informatie:De aanvraagkoptekst expliciet instellen op het accepteren van JSON
data	object	Stel dit in op de waarde van een JSON-object voor maak- en bijwerkbewerkingen.
url	string	De ODATA-eindpunt-URL voor de actie die u uitvoert.
beforeSend	function	Een functie waarmee u het XMLHttpRequest-object kunt wijzigen voordat het wordt verzonden.
success	function	Een callbackfunctie als een aanvraag slaagt.Meer informatie:Resultaten verwerken
error	function	Een functie die wordt aangeroepen als een aanvraag mislukt.Meer informatie:Fouten afhandelen

Zie Voorbeeld: Maken, ophalen, bijwerken en verwijderen via het OData-eindpunt met JavaScript en jQuery voor meer informatie.

De aanvraagkoptekst expliciet instellen op het accepteren van JSON

Wanneer u de resultaten verwacht in een JSON-indeling, werkt alleen het instellen van de eigenschap dataType mogelijk niet. U kunt de eigenschap beforeSend gebruiken om de kopteksten expliciet op XMLHttpRequest int e stellen om gegevens te retourneren als JSON. Dat wordt meestal gedaan door een anonieme functie uit te voeren, zoals in het volgende voorbeeld.

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

Als dit is opgegeven, worden fouten in XMLHttpRequest.responseText opgemaakt in JSON in plaats van in XML.

Tip

Zelfs als u niet verwacht dat gegevens worden geretourneerd, vereenvoudigt opgeven dat de resultaten altijd moeten worden geretourneerd met JSON de foutafhandeling.Meer informatie:Fouten afhandelen

De aanvraagkoptekst expliciet instellen op een andere HTTP-actie

Zoals beschreven in Methodetunneling met POST, als u een actie uitvoert die een andere HTTP-actie beschrijft dan POST of GET, gebruikt u POST en de eigenschap beforeSend om de kopteksten in de XMLHttpRequest expliciet in te stellen om een andere actie uit te voeren. Dat wordt meestal gedaan door een anonieme functie uit te voeren, zoals in het volgende voorbeeld.

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

Fouten afhandelen

Wanneer een aanvraag niet is geslaagd is, geeft $.ajax de volgende drie argumenten door aan een functie die is ingesteld in de fouteigenschap.

• XMLHttpRequest
  Het XMLHttpRequest-object.

• textStatus
  Een tekenreeks die het type fout beschrijft dat is opgetreden. Mogelijke waarden zijn als volgt:

  • null

  • timeout

  • error

  • notmodified

  • parsererror

• errorThrown
  Een optioneel uitzonderingsobject.

Dit voorbeeld laat zien hoe u deze argumenten doorgeeft aan een centrale functie die fouten beheert.

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

Dit voorbeeld laat een eenvoudige functie zien die het foutbericht vastlegt en het resultaat weergeeft met de functie showMessage.

Notitie

Deze functie verwacht dat eventuele foutdetails worden geretourneerd in de JSON-indeling. Tenzij de methode $.ajax is geconfigureerd om resultaten te retourneren met JSON, moet de XMLHttpRequest.responseTextXML zijn.

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

Resultaten verwerken

Als u POST- of GET-bewerkingen uitvoert, kunt u verwachten dat gegevens worden geretourneerd. Als u hebt opgegeven dat resultaten worden geretourneerd in de JSON-indeling, bevinden de resultaten zich in de eigenschap d van het gegevensobject dat wordt geretourneerd. Wanneer u een record maakt of ophaalt met de unieke id, vertegenwoordigt d de gegevens voor de record. In elk ander geval is d een matrix.

Het volgende voorbeeld toont de verwerking van de resultaten van een query die meerdere accountrecords retourneert.

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

Werken met datums

Er zijn vier taken met betrekking tot datums die u mogelijk moet uitvoeren:

• Opgehaalde gegevens parseren

• Datumwaarden weergeven

• Datumwaarden bijwerken

• Een datum als criterium instellen in een filter in een query

Opgehaalde gegevens parseren

Als u records ophaalt met het ODATA-eindpunt, worden datumwaarden geretourneerd als tekenreeksen met de indeling "\/Date(<ticks>)\/", waarbij <ticks> het aantal milliseconden sinds middernacht 1 januari 1970 is. Voorbeeld: "\/Date(1311170400000)\/". Alle waarden die worden geretourneerd uit Microsoft Dynamics 365, vertegenwoordigen de UTC-waarden (Coordinated Universal Time), dus er wordt geen verschuiving opgenomen.

Er zijn twee strategieën die u kunt gebruiken om datums te parseren die worden geretourneerd met het ODATA-eindpunt:

• Een reviverfunctie gebruiken met de JSON.parse-methode

• Gebruik String.replace om een datumwaarde te genereren uit een tekenreeks

Een reviverfunctie gebruiken met de JSON.parse-methode

De methode JSON.parse ondersteunt een optioneel reviverargument, zoals beschreven in de documentatie van de methode JSON.parse op MSDN. Hier volgt een voorbeeld dat de tekenreekswaarden met een patroon dat is gedefinieerd in een gewone expressie, converteert naar Date-objecten.

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

Notitie

Deze code gaat ervan uit dat gegevenswaarden altijd UTC zijn en geen verschuivingsinformatie bevatten.

Gebruik String.replace om een datumwaarde te genereren uit een tekenreeks

Als u het reviverargument niet gebruikt met de methode JSON.parse, toont het volgende voorbeeld hoe u een Date-waarde genereert uit een tekenreeks.

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

Datumwaarden weergeven

Nadat de tekenreekswaarden zijn geconverteerd naar Date-objecten, kunt u allerlei JavaScript-methoden gebruiken of uw eigen methoden maken om de datum weer te geven als een tekenreeks in een gebruikersinterface. Aangezien het JavaScriptDate-object UTC-bewust is, reflecteren de datums die in uw gebruikersinterface worden weergegeven met methoden zoals toString of toLocaleString de tijdzone-instellingen van het besturingssysteem van de gebruiker.

De waarden in uw toepassing kunnen echter afwijken van dezelfde waarden die worden weergegeven in Microsoft Dynamics 365, waar niet wordt vertrouwd op de tijdzone-instellingen van het besturingssysteem van de gebruiker. Deze waarden zijn anders als de voorkeuren van de besturingssysteemtijdzone van de huidige gebruiker niet overeenkomen met de tijdzonevoorkeur die is opgeslagen in Microsoft Dynamics 365.Microsoft Dynamics 365 staat ook persoonlijke instellingen voor presentatieopties toe die niet worden toegepast door het gebruiken standaard JavaScript-datumfuncties zoals toString.

Als u de weergegeven datum- en tijdwaarden wilt afstemmen op de waarden die worden weergegeven in Microsoft Dynamics 365, kunt u gegevens opvragen die zijn opgeslagen in de entiteit UserSettings en in entiteiten zoals TimeZoneDefinition en TimeZoneRule om functies te maken om datums weer te geven die overeenkomen met de voorkeur van de gebruiker.Microsoft Dynamics 365 biedt geen functies om deze acties uit te voeren.

Datumwaarden bijwerken

Als u de waarden van een JavaScript-datum wijzigt met behulp van standaardmethoden zoals setMinutes of setHours, zijn deze wijzigingen in de lokale tijd van de gebruiker. Wanneer u de record opslaat, worden de werkelijke UTC-waarden geserialiseerd en weer opgeslagen in Microsoft Dynamics 365. U hoeft niets te doen om de datums te converteren naar een UTC-waarde.

Als een Date wordt geserialiseerd, verschilt de indeling van de indeling die is gebruikt toen de gegevens werden opgehaald. Zoals gezegd in Opgehaalde gegevens parseren, gebruiken datums die als tekenreeksen worden opgehaald, de indeling "\/Date(1311179400000)\/". Wanneer u de resultaten van JSON.stringify bekijkt voor datumwaarden die terug worden gegeven aan de server, is de indeling "2013-07-20T16:30:00Z".

Een datum als criterium instellen in een filter in een query

Wanneer u een datumwaarde gebruikt met een systeemqueryoptie in $filter, moet u een UTC-datum gebruiken. Als u een JavaScriptDate-object wilt converteren naar de indeling die wordt verwacht voor een filter, moet u de datum verwerken met een functie zoals in het volgende voorbeeld. Het resultaat is een tekenreeks met de volgende indeling: 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;
}

Zie ook

Het OData-eindpunt gebruiken met webresources
OData endpoint Http status codes
JavaScript-bibliotheken voor Microsoft Dynamics CRM 2015
Scriptwebresources (JScript)
Koppel functies aan formulier- en veldgebeurtenissen
jQuery.ajax-methode
XMLHttpRequest Object
Technisch Artikel: Optieset-opties gebruiken met het ODATA-eindpunt - JScript

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht