Brug OData-slutpunktet med Ajax og JScript-webressourcer

 

Udgivet: november 2016

Gælder for: Dynamics CRM 2015

Med OData-slutpunktet kan du interagere med Microsoft Dynamics CRM 2015 og opdatering til Microsoft Dynamics CRM Online 2015-data ved hjælp af JavaScript-biblioteker. Du kan oprette script webressourcer, der bruger filer, der definerer JavaScript-bibliotekerne. Derefter knytter du funktioner i bibliotekerne til formular- eller felthændelseshandlere eller kommandohandlinger på båndet. Du kan bruge dem som ethvert andet JavaScript-bibliotek i webressourcer (HTML) på websider.

Dette emne indeholder

Ajax

Metodetunnelføring via POST

Få adgang til serverens URL-adresse

Brug XMLHttpRequest

Brug jQuery

Arbejd med datoer

Ajax

AJAX (Asynkron JavaScript og XML) er en webudviklingsteknik, der bruges til at oprette interaktive webprogrammer. Der sendes serveranmodninger fra browseren i baggrunden ved hjælp af et XmlHttpRequest-objekt. Selv om du kan sende synkrone anmodninger, er den anbefalede praksis at sende asynkrone anmodninger. Asynkrone anmodninger kræver to JScript-funktioner, en til at sende anmodningen og en anden "tilbagekaldsfunktion" til at behandle et svar.

JSON

JSON-formatet (JavaScript Object Notation) bruges til serialisering og overførsel af strukturerede data stort set på samme måde, som XML bruges normalt. Ligesom XML er det tekstbaseret og designet til at kunne læses af mennesker. Når du vil konvertere almindelige JavaScript-objekter til JSON-formatet, skal du bruge JSON.stringify-metoden. Da teksten i JSON definerer JavaScript-objekter, kan teksten konverteres til JavaScript-objekter ved hjælp af eval-metoden. Denne praksis skaber dog sikkerhedsrisici. Du bør bruge JSON.parse-metoden i stedet.

XmlHttpRequest

XmlHttpRequest (som også kaldes XHR) indeholder funktioner til at konfigurere og sende anmodninger og definere en tilbagekaldsfunktion, hvis anmodningen er asynkron.HTTP-svaret fra serveren indeholder en statuskode, der angiver, om anmodningen lykkedes.HTTP-statuskodeværdierne i området 200 anses for at være vellykket.

En XmlHttpRequest indeholder instruktioner til serveren om formatet af alle data, der skal medtages i svaret. Da ODATA-slutpunktet understøtter både ATOM- og JSON-formatet, har du mulighed for at anmode om, at data returneres i XMLATOM-formatet. Men med JavaScript-kode bruger den forventede typiske anmodning JSON, fordi det er let at bruge med JavaScript.

Metodetunnelføring via POST

OData-protokollen bruger de knapt så almindelige HTTP-verber PUT og DELETE og definerer desuden et nyt verbum: MERGE. Afhængigt af de understøttende biblioteker du bruger, kan der opstå problemer ved brug af disse verber. Du kan løse dette problem ved at bruge verbet POST og angive en X-HTTP-MethodHTTP-header med den ønskede handling. Brug setRequestHeader-metoden til at tilsidesætte den handling, der er angivet i XmlHttpRequest.

Få adgang til serverens URL-adresse

Det første, du skal gøre, når du begynder at bruge ODATA-slutpunktet med JavaScript, er at finde frem til URL for organisationsroden URL. Brug funktionen getClientUrl fra kontekstobjektet.

• Hvis dit script er udviklet til brug i forbindelse med en formular- eller felthændelse eller en <JavaScriptFunction> (RibbonDiffXml) til en kommando på båndet, kan du bruge Xrm.Page.context-objektet til at kalde getClientUrl.

• Hvis dit script køres i forbindelse med en webressource til en webside (HTML), skal du medtage en reference til ClientGlobalContext.js.aspx-siden i HTML-webressourcen, så du kan bruge GetGlobalContext-funktion.

Brug XMLHttpRequest

jQuery er et rigtig godt bibliotek med en lang række anvendelser, men brug af jQuery er ikke en forudsætning for at udføre handlinger ved hjælp af ODATA-slutpunktet for Microsoft Dynamics 365. Vi anbefaler, at du ikke bruger jQuery i formularscripts eller kommandoscripts, der køres på programsider, men bruger XmlHttpRequest direkte, så du undgår at skulle indlæse jQuery-biblioteket.jQuery**$.ajax** bruger den XmlHttpRequest, der er tilgængelig i browseren. Brug af dette objekt direkte er lidt anderledes end at bruge $.ajax. Hvis du allerede er fortrolig med brugen af XMLHttpRequest, bør du fortsætte med at bruge den. Hvis du altid har brugt jQuery, kan du overveje at bruge XMLHttpRequest direkte.Flere oplysninger:XMLHttpRequest-objekt

Med XmlHttpRequest opretter du en hændelseshandler til onreadystatechange-hændelsen og registrerer, når anmodningen er fuldført. I hændelseshandleren skal du undersøge returnerede statuskode for at finde ud af, om anmodningen lykkedes. Til slut skal du bruge metoderne open og send. I følgende eksempel bruges XmlHttpRequest til at oprette en ny firmapost.

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

Du kan finde flere eksempler på brug af XMLHttpRequest under Eksempel: Oprette, hente, opdatere og slette vha. OData-slutpunktet med JavaScript

Brug jQuery

jQuery er et populært JavaScript-bibliotek, der følger med programmet webprojekter i Microsoft Visual Studio.jQuery giver en omfattende ramme af objekter og funktioner, hvor du forespørge og arbejde med HTML-sider ved hjælp af JavaScript. Når du vil bruge XMLHttpRequest, kan du anvende jQuery.ajax-metoden i jQuery.

Bemærk

Vi fraråder brug af jQuery i formularscripts og kommandoer på båndet.Flere oplysninger:Brug af jQuery.

Der refereres til jQuery-objektet ved hjælp af $-tegnet, så den kort form af jQuery.ajax er $.ajax.ajax-metoden bruges typisk med en tvingende syntaks, og anmodningen sendes, så snart en forekomst af objektet er instantieret. I følgende eksempel oprettes en ny firmapost.

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

I følgende tabel vises de egenskaber, du er nødt til at kende for at kunne behandle HTTP-anmodninger og svar ved hjælp af ODATA-slutpunktet for Microsoft Dynamics 365.

Egenskabsnavn	Skriv	Kommentarer
type	string	Brug GET, når du henter data, og POST til alle andre handlinger.Flere oplysninger:Indstil eksplicit anmodningsheaderen til en anden HTTP-handling
contentType	string	Angiver typen indhold, der sendes til serveren. Brug application/json; charset=utf-8, når du sender data i JSON-formatet.
dataType	string	Typen af data, der forventes at blive returneret af serveren. Benyt json. > [!NOTE] > Det er muligvis ikke nok blot at indstille denne egenskab.Flere oplysninger:Indstil eksplicit anmodningsheaderen til at acceptere JSON
data	object	Indstil dette til værdien af et JSON-objekt i forbindelse med oprettelses- eller opdateringshandlinger.
url	string	Den ODATA-slutpunkts-URL, der passer til den handling, du udfører.
beforeSend	function	En funktion, du kan bruge til at redigere XMLHttpRequest-objektet, før det sendes.
success	function	En tilbagekaldsfunktion, når en anmodning er lykkedes.Flere oplysninger:Behandlingsresultater
error	function	En funktion, der skal kaldes, hvis en anmodning mislykkes.Flere oplysninger:Håndter fejl

Du kan finde flere oplysninger under Eksempel: Oprette, hente, opdatere og slette ved hjælp af OData-slutpunktet med JavaScript og jQuery.

Indstil eksplicit anmodningsheaderen til at acceptere JSON

Når du forventer resultater i et JSON-format, fungerer det muligvis ikke blot angive egenskaben dataType. Du kan bruge egenskaben beforeSend til udtrykkeligt at indstille headers på XMLHttpRequest til at returnere data som JSON. Dette udføres typisk ved hjælp af en anonym funktion, som vist i følgende eksempel.

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

Eventuelle fejl i XMLHttpRequest.responseText vil blive formateret i JSON i stedet for XML.

Tip

Selv om du ikke forventer, at der returneres nogen data, kan du angive, at resultaterne altid skal returneres ved hjælp af JSON for at forenkle håndtering af fejl.Flere oplysninger:Håndter fejl

Indstil eksplicit anmodningsheaderen til en anden HTTP-handling

Som beskrevet i Metodetunnelføring via POST, når du udfører en handling, der kræver en anden HTTP-handling end POST eller GET, skal du bruge egenskaberne POST og beforeSend til udtrykkeligt at indstille headerne i XMLHttpRequest til at udføre en anden handling. Dette udføres typisk ved hjælp af en anonym funktion, som vist i følgende eksempel.

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

Håndter fejl

Når en anmodning ikke er vellykket, sender $.ajax følgende tre argumenter til en funktion, der er angivet i fejlegenskaben.

• XMLHttpRequest
  Objektet XMLHttpRequest.

• textStatus
  En streng, der beskriver den type fejl, der er opstået. Der er følgende mulige værdier:

  • null

  • timeout

  • error

  • notmodified

  • parsererror

• errorThrown
  Et valgfrit undtagelsesobjekt.

I følgende eksempel kan du se, hvordan du sender disse argumenter til en central funktion, der styrer fejl.

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

I følgende eksempel vises en simpel funktion, der registrerer fejlmeddelelsen og viser resultatet ved hjælp af funktionen showMessage.

Bemærk

Denne funktion forventer, at alle fejloplysninger returneres i JSON-formatet. Medmindre $.ajax-metoden konfigureres til at returnere resultater ved hjælp af JSON, er XMLHttpRequest.responseTextXML.

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

Behandlingsresultater

Når du udfører POST- eller GET-handlinger, kan du forvente, at der returneres data. Hvis du har angivet, at resultater skal returneres i JSON-formatet, findes resultaterne i egenskaben d for det dataobjekt, der returneres. Når du opretter eller henter en post ved hjælp af det entydige id, repræsenterer d dataene for posten. I alle andre tilfælde er d en matrix.

I følgende eksempel kan du se behandlingen af resultaterne af en forespørgsel, der returnerer flere firmaposter.

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

Arbejd med datoer

Der findes fire opgaver, der omfatter datoer, som du evt. skal udføre:

• Fortolk hentede data

• Vis datoværdier

• Opdater datoværdier

• Angiv en dato som kriterium i et filter i en forespørgsel

Fortolk hentede data

Når du henter poster ved hjælp af ODATA-slutpunktet, returneres datoværdier som strenge, der bruger formatet "\/Date(<ticks>)\/", hvor <ticks> er antallet millisekunder siden midnat d. 1. januar 1970. Eksempel: "\/Date(1311170400000)\/". Alle værdier, der returneres fra Microsoft Dynamics 365, repræsenterer UTC-værdier (Coordinated Universal Time), så ingen forskydningsoplysninger er inkluderet.

Der er to strategier, som du kan bruge til at fortolke datoer i poster, der returneres ved hjælp af ODATA-slutpunktet:

• Brug en reviverfunktion med metoden JSON.parse

• Brug String.replace til at oprette en datoværdi fra en streng

Brug en reviverfunktion med metoden JSON.parse

JSON.parse-metoden understøtter et valgfrit reviverargument, som beskrevet i dokumentationen til JSON.parse-metoden på MSDN. Følgende er et eksempel, der konverterer strengværdier, som svarer til et mønster, der er defineret i et søgemønster, til Date-objekter.

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

Bemærk

I koden antages det, at datoværdier altid er UTC-dataværdier, som ikke indeholder nogen forskydningsoplysninger.

Brug String.replace til at oprette en datoværdi fra en streng

Hvis du ikke bruger reviverargumentet med JSON.parse-metoden, kan du i følgende eksempel se, hvordan du kan oprette en Date-værdi fra en streng.

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

Vis datoværdier

Når strengdatoværdier konverteres til Date-objekter, kan du bruge en række JavaScript-metoder eller oprette dine egne for at få vist datoen som en streng i en brugergrænseflade. Da JavaScriptDate-objektet er UTC-bestemt, afspejler datoerne, der vises i brugergrænsefladen ved hjælp af metoder. f.eks toString eller toLocaleString, tidszoneindstillingerne i brugerens operativsystem.

Bemærk dog, at værdierne i dit program kan afvige fra de samme værdier, der vises i Microsoft Dynamics 365, som ikke er afhængige af tidszoneindstillingerne i brugerens operativsystem. Disse værdier vil være forskellige, når brugerens aktuelle tidszoneindstilling i operativsystemet ikke stemmer overens med den foretrukne tidszoneindstilling, der er gemt i Microsoft Dynamics 365.Microsoft Dynamics 365 giver også mulighed for angivelse af personlige præsentationsindstillinger, der ikke anvendes ved hjælp af JavaScript-standarddatofunktioner, f.eks. toString.

Hvis du vil afstemme de viste dato- og klokkeslætsværdier, så de stemmer overens med de værdier, der vises i Microsoft Dynamics 365-objektet, kan du forespørge på data gemt i UserSettings-objektet og objekter som TimeZoneDefinition og TimeZoneRule for at oprette funktioner, der kan vise datoer, der svarer til brugerens præferencer.Microsoft Dynamics 365 indeholder ikke funktioner til at udføre disse handlinger.

Opdater datoværdier

Når du ændrer værdierne for en JavaScript-dato med standardindstillingsmetoder som setMinutes eller setHours, er disse ændringer i brugerens lokale tid. Når du gemmer posten, serialiseres de faktiske UTC-værdier og gemmes i Microsoft Dynamics 365. Du behøver ikke at gøre noget for at konvertere datoerne til en UTC-værdi.

Når en Date serialiseres, adskiller formatet sig fra det format, der blev brugt, da dataene blev hentet. Som nævnt i Fortolk hentede data bruger datoer, der er hentet som strenge, formatet "\/Date(1311179400000)\/". Når du undersøger resultaterne af JSON.stringify for datoværdier, der skal sendes tilbage til serveren, er formatet "2013-07-20T16:30:00Z".

Angiv en dato som kriterium i et filter i en forespørgsel

Når du bruger en datoværdi med en $filter-systemforespørgselsindstilling, skal du bruge en UTC-dato. Når du vil konvertere et JavaScriptDate-objekt til formatet, der forventes for et filter, skal du behandle datoen ved hjælp af en funktion som i følgende eksempel. Resultatet er en streng, der svarer til følgende format: 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;
}

Se også

Brug OData-slutpunktet med webressourcer
OData endpoint Http status codes
JavaScript-biblioteker til Microsoft Dynamics CRM 2015
Webressourcer for script (JScript)
Knytte funktioner til formular- og felthændelser
jQuery.ajax-metode
XMLHttpRequest-objekt
Teknisk artikel: Brug af indstillingen Grupperet indstilling sammen med ODATA-slutpunktet – JScript

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret