Verwenden des OData-Endpunkts mit Ajax- und JScript-Webressourcen

Artikel
07/06/2017

Veröffentlicht: November 2016

Gilt für: Dynamics CRM 2015

Mit dem OData-Endpunkt können Sie mit Microsoft Dynamics CRM 2015 und Microsoft Dynamics CRM Online 2015-Update-Daten mithilfe von JavaScript-Bibliotheken interagieren. Sie erstellen Skriptwebressourcen mithilfe von Dateien, die die JavaScript-Bibliotheken definieren. Dann ordnen Sie die Funktionen in den Bibliotheken Formular- oder Ereignishandlern oder Menübandbefehlsaktionen zur. Sie können sie wie jede andere JavaScript-Bibliothek innerhalb von Webseiten-Webressourcen (HTML) verwenden.

In diesem Thema

Ajax

Methoden-Tunneling durch POST

Zugreifen auf die Server-URL

Verwenden von XmlHttpRequest

Verwenden von jQuery

Verwenden von Datumsangaben

Ajax

AJAX (Asynchrones JavaScript und XML) ist eine Internetentwicklungstechnik, die verwendet wird, um interaktive Webanwendungen zu erstellen. Serveranforderungen gehen vom Browser im Hintergrund mithilfe eines XmlHttpRequest-Objekts aus. Obwohl Sie synchrone Anforderungen senden können, sollten Sie asynchrone Anforderungen senden. Asynchrone Anforderungen erfordern zwei JScript-Funktionen, eine zum Senden der Anforderung und eine zweite Rückruffunktion zum Verarbeiten einer Antwort.

JSON

Das JavaScript-JSON-Format wird für das Serialisieren und Übertragen strukturierter Daten auf ähnliche Weise wie XML verwendet. Wie XML ist es textbasiert und so entworfen, dass es von Menschen gelesen werden kann. Um reguläre JavaScript-Objekte in das JSON-Format zu konvertieren, verwenden Sie die JSON.stringify-Methode. Da der Text in JSON JavaScript-Objekte definiert, kann der Text in JavaScript-Objekte mithilfe der eval-Methode konvertiert werden. Diese Vorgehensweise verursacht jedoch Sicherheitsrisiken. Sie sollten stattdessen die JSON.parse-Methode verwenden.

XmlHttpRequest

XmlHttpRequest (manchmal als XHR bezeichnet), stellt Funktionen zum Konfigurieren und Senden von Anforderungen und zum Definieren einer Rückruffunktion bereit, falls die Anforderung asynchron ist. Die HTTP Antwort auf dem Server umfasst einen Statuscode der angibt, dass die Anforderung erfolgreich war.HTTP Statuscodewerte im Bereich 200 gelten als erfolgreich.

Eine XmlHttpRequest stellt dem Server Anweisungen zum Format aller Daten bereit, die in der Antwort enthalten sein sollen. Da der ODATA-Endpunkt die ATOM- und JSON-Formate unterstützt, können Sie Daten anfordern, die im XMLATOM-Format zurückgegeben werden sollen. Allerdings verwendet die typische Anforderung mit JavaScript-Code JSON, da sie problemlos mit JavaScript verwendbar ist.

Methoden-Tunneling durch POST

Das OData-Protokoll verwendet die weniger häufigen HTTP-Verben PUT und DELETE und definiert ein neues Verb: MERGE. Je nach verwendeten unterstützenden Bibliotheken können Sie beim Verwenden dieser Verben auf Probleme stoßen. Die Möglichkeit, dieses Problem zu umgehen, besteht im Verwenden des POST-Verbs und im Angeben einer X-HTTP-MethodHTTP-Kopfzeile mit der gewünschten Aktion. Verwenden Sie die setRequestHeader-Methode, um die Aktion zu überschrieben, die in XmlHttpRequest angegeben ist.

Zugreifen auf die Server-URL

Wenn Sie den ODATA-Endpunkt mit JavaScript verwenden, sollten Sie zunächst Organisationsstamm die URL zum Organisationsstamm URL einrichten. Verwenden Sie die getClientUrl-Funktion aus dem Kontextobjekt.

Wenn Ihr Skript so konzipiert ist, dass es im Kontext eines Formular- oder Feldereignisses oder einer <JavaScriptFunction> (RibbonDiffXml) für einen Menübandbefehl funktioniert, können Sie das Objekt Xrm.Page.context verwenden, um getClientUrl aufzurufen.
Wenn Ihr Skript im Kontext einer Webressource auf einer Webseiten-Webressource (HTML) ausgeführt wird, müssen Sie einen Verweis auf die Seite ClientGlobalContext.js.aspx in die Webressource HTML einfügen, damit Sie dann GetGlobalContext-Funktion verwenden können.

Verwenden von XmlHttpRequest

jQuery ist eine großartige Bibliothek mit verschiedenen Anwendungsmöglichkeiten, aber das Verwenden von jQuery ist keine Voraussetzung für die Ausführung von Vorgängen mithilfe des ODATA-Endpunkts für Microsoft Dynamics 365. Es ist empfehlenswert, jQuery nicht in Formularskripts oder Befehlsskripts zu verwenden, die auf Anwendungsseiten ausgeführt werden. Verwenden Sie stattdessen direkt XmlHttpRequest und vermeiden Sie das Laden der jQuery-Bibliothek.jQuery**$.ajax** verwendet die XmlHttpRequest, die im Browser verfügbar ist. Das direkte Verwenden dieses Objekts unterscheidet sich leicht vom Vuntererwenden von $.ajax. Wenn Sie mit dem Verwenden von XMLHttpRequest bereits vertraut sind, sollten Sie die Verwendung fortsetzen. Wenn Sie schon immer jQuery verwendet haben, sollten Sie überlegen, XMLHttpRequest direkt zu verwenden.Weitere Informationen:XMLHttpRequest Objekt

Mit XmlHttpRequest erstellen Sie einen Ereignishandler für das onreadystatechange-Ereignis und erkennen, wann die Anforderung abgeschlossen ist. Überprüfen Sie im Ereignishandler den Statuscode, um zu ermitteln, ob die Anforderung erfolgreich war. Verwenden Sie schließlich die Methoden open und send. Das folgende Beispiel verwendet XmlHttpRequest, um einen neuen Firmendatensatz zu erstellen.

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

Weitere Beispiele mit XMLHttpRequest finden Sie unter Beispiel: Erstellen, abrufen, aktualisieren und löschen mithilfe des OData-Endpunkts mit JavaScript.

Verwenden von jQuery

jQuery ist eine beliebte JavaScript Bibliothek, die in Webanwendungsprojekten in Microsoft Visual Studioenthalten ist.jQuery stellt ein umfangreiches Framework von Objekten und Funktionen bereit, mit denen Sie mit JavaScript Abfragen vornehmen und mit HTML arbeiten können. Für die Verwendung von XMLHttpRequest stellt jQuery die jQuery.ajax-Methode bereit.

Hinweis

Es empfiehlt sich, jQuery nicht in Formularskripten oder Befehlen zu verwenden.Weitere Informationen:Verwendung von jQuery.

Das jQuery-Objekt wird mit dem $-Zeichen referenziert, sodass die Kurzform für jQuery.ajax$.ajax lautet. Die ajax-Methode wird normalerweise mit einer obligatorischen Syntax verwendet und die Anforderung wird gesendet, sobald das Objekt instanziiert wird. Das folgende Beispiel erstellt einen neuen Firmendatensatz.

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

In der folgenden Tabelle sind die Eigenschaften aufgeführt, die Sie kennen müssen, um HTTP-Anforderungen und -Antworten mithilfe des ODATA-Endpunkts für Microsoft Dynamics 365 zu verarbeiten.

Eigenschaftenname	Typ	Kommentare
type	string	Verwenden Sie GET,wenn Sie Daten und POST für alle anderen Vorgänge abrufen.Weitere Informationen:Legen Sie den Anforderungsheader explizit auf eine andere HTTP-Aktion fest
contentType	string	Gibt den Typ des Inhalts an, der an den Server gesendet wird. Verwenden Sie application/json; charset=utf-8 wenn Sie Daten im JSON-Format senden.
dataType	string	Der erwartete Datentyp, der vom Server zurückgegeben wird. Verwenden von json. Hinweis ;öglicherweise ist es nicht ausreichend, diese Eigenschaft einfach festzulegen.Weitere Informationen:Legen Sie den Anforderungsheader explizit so fest, dass JSON akzeptiert wird
data	object	Legen Sie die Eigenschaft auf einen Wert eines JSON-Objektsfür Erstellen- oder Aktualisierungsvorgänge fest.
url	string	Die ODATA-Endpunkt-URL für die Aktion, die Sie ausführen.
beforeSend	function	Eine Funktion, mit der Sie das Objekt XMLHttpRequest vor dem Senden ändern können.
success	function	Eine Rückruffunktion, wenn eine Anforderung erfolgreich ist.Weitere Informationen:Verarbeiten von Ergebnissen
error	function	Eine Funktion, die aufgerufen wird, wenn eine Anforderung fehlschlägt.Weitere Informationen:Verarbeiten von Fehlern

Weitere Informationen finden Sie unter Beispiel: Erstellen, Abrufen, Aktualisieren und Löschen mithilfe des OData-Endpunkts mit jQuery.

Legen Sie den Anforderungsheader explizit so fest, dass JSON akzeptiert wird

Wenn Sie Ergebnisse in einem JSON-Format, funktioniert das einfache Festlegen der dataType-Eigenschaft möglicherweise nicht. Sie können die beforeSend-Eigenschaft verwenden, um die Kopfzeilen der XMLHttpRequest explizit so festzulegen, dass Daten als JSON zurückgegeben werden. Dies wird normalerweise mithilfe einer anonymen Funktion durchgeführt, wie im folgenden Beispiel gezeigt wird.

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

Falls angegeben, werden alle Fehler in XMLHttpRequest.responseText in JSON anstatt in XML formatiert.

Tipp

Selbst wenn Sie nicht erwarten, dass Daten zurückgegeben werden, wird durch das Angeben, dass Ergebnisse mit JSON immer zurückgegeben werden, die Fehlerbehandlung vereinfacht.Weitere Informationen:Verarbeiten von Fehlern

Legen Sie den Anforderungsheader explizit auf eine andere HTTP-Aktion fest

Wie in Methoden-Tunneling durch POST beschrieben: Wenn Sie eine Aktion ausführen, die eine HTTP-Aktion außer POST oder GET erfordert, verwenden Sie POST und die beforeSend-Eigenschaft, um die Kopfzeilen der XMLHttpRequest explizit auf das Ausführen einer anderen Aktion festzulegen. Dies wird normalerweise mithilfe einer anonymen Funktion durchgeführt, wie im folgenden Beispiel gezeigt wird.

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

Verarbeiten von Fehlern

Wenn eine Anforderung nicht erfolgreich ist, übergibt $.ajax die folgenden drei Argumente an eine Funktiongruppe in der Fehlereigenschaft.

XMLHttpRequest
Das XMLHttpRequest-Objekt.
textStatus
Eine Zeichenfolge, die den aufgetretenen Fehlertyp beschreibt. Mögliche Werte:
- null
- timeout
- error
- notmodified
- parsererror
errorThrown
Ein optionales Ausnahmeobjekt.

Das folgende Beispiel zeigt, wie diese Argumente an eine zentrale Funktion, die Fehler verwaltet, übergeben wird.

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

Das folgende Beispiel zeigt eine einfache Funktion, die die Fehlermeldung erfasst, und zeigt das Ergebnis mithilfe der showMessage-Funktion an.

Hinweis

Diese Funktion erwartet, dass sämtliche Fehlerdetails im JSON-Format zurückgegeben werden. Sofern die $.ajax-Methode nicht so konfiguriert wird, dass die Ergebnisse mithilfe von JSON zurückzugeben werden, ist XMLHttpRequest.responseText gleich XML.

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

Verarbeiten von Ergebnissen

Wenn Sie POST- oder GET-Vorgänge ausführen, können Sie erwarten, dass Daten zurückgegeben werden. Wenn Sie angegeben haben, dass Ergebnisse im JSON-Format zurückgegeben werden, werden die Ergebnisse in der d-Eigenschaft des Datenobjekts zurückgegeben. Wenn Sie einen Datensatz mithilfe des eindeutigen Bezeichners erstellen oder abrufen, stellt d die Daten für den Datensatz dar. In allen anderen Fällen ist d ein Array.

Das folgende Beispiel zeigt die Verarbeitung der Ergebnisse einer Abfrage, die mehrere Firmendatensätze zurückgibt.

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

Verwenden von Datumsangaben

Es gibt vier Aufgaben mit Datumsangaben, die unter Umständen ausführen müssen:

Analyse abgerufener Daten
Anzeigen von Datumswerten
Aktualisieren von Datumswerten
Legen Sie ein Datum als Kriterien in einem Filter in einer Abfrage fest

Analyse abgerufener Daten

Wenn Sie Datensätze mithilfe des ODATA-Endpunkts abrufen, werden Datumswerte als Zeichenfolgen im Format "\/Date(<ticks>)\/" zurückgegeben, wobei <ticks> die Anzahl der Millisekunden seit Mitternacht am 1. Januar 1970 ist. Beispiel: "\/Date(1311170400000)\/". Alle Werte, die von Microsoft Dynamics 365 zurückgegeben werden, stellen die UTC-Werte (Coordinated Universal Time) dar, sodass keine Offsetinformationen enthalten sind.

Zwei Strategien, die Sie verwenden können, um Datumsangaben in Datensätzen zu analysieren, die mithilfe des ODATA-Endpunkts zurückgegeben werden:

Verwenden Sie eine reviver-Funktion mit der JSON.parse-Methode
Verwenden Sie String.replace, um einen Datumswert aus einer Zeichenfolge zu generieren

Verwenden Sie eine reviver-Funktion mit der JSON.parse-Methode

Die JSON.parse-Methode unterstützt ein optionales reviver-Argument, wie in der JSON.parse-Methodendokumentation auf MSDN beschrieben. Im Folgenden finden Sie ein Beispiel, das die Zeichenfolgenwerte, die einem Muster entsprechen, das in einem regelmäßigen Ausruck definiert wurde, in Date-Objekte konvertiert.

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

Hinweis

Dieser Code nimmt an, dass immer Datumswerte UTC-Datenwerte sind und keine Offsetinformationen enthalten.

Verwenden Sie String.replace, um einen Datumswert aus einer Zeichenfolge zu generieren

Wenn Sie nicht das reviver-Argument mit der JSON.parse-Methode verwenden, zeigt das folgende Beispiel, wie Sie einen Date-Wert für aus einer Zeichenfolge generieren können.

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

Anzeigen von Datumswerten

Nachdem die Zeichenfolgendatumswerte in Date-Objekte konvertiert wurden, können Sie eine Vielzahl von JavaScript-Methoden verwenden, oder erstellen Sie eigene, um das Datum als Zeichenfolge in einer Benutzeroberfläche anzuzeigen. Da das JavaScriptDate-Objekt UTC-fähig ist, geben die in der Benutzeroberfläche angezeigten Datumsangaben die Methoden wie toString oder toLocaleString an, die Zeitzoneneinstellungen des Betriebssymstems des Benutzers wiedergeben.

Beachten Sie jedoch, dass sich die Werte in der Anwendung von den gleichen Werten unterscheiden können, die in Microsoft Dynamics 365 angezeigt werden und nicht von den Betriebssystem-Zeitzoneneinstellungen des Benutzers abhängig sind. Diese Werte sind anders, wenn die aktuelle Betriebssystemzeitzoneneinstellung des Benutzers nicht der Zeitzoneneinstellung entspricht, die in Microsoft Dynamics 365 gespeichert wurden.Microsoft Dynamics 365 können auch das Festlegen von personalisierten Präsentationsoptionen, die nicht von standardisierten JavaScript Datenfunktionen wie toString angewendet werden.

Wenn Sie die angezeigten Uhrzeit- und Datumswerte mit den in Microsoft Dynamics 365 angezeigten Werten abgleichen möchten, können Sie die Daten, die in der UserSettings-Entität gespeichert sind, und Entitäten wie TimeZoneDefinition und TimeZoneRule abfragen, um Funktionen zu erstellen und Datumsangaben anzuzeigen, die den Einstellungen des Benutzers entsprechen.Microsoft Dynamics 365 enthält keine Funktionen, um die Aktionen auszuführen.

Aktualisieren von Datumswerten

Wenn Sie die Werte eines JavaScript-Datums mithilfe von Standardfestlegemethoden wie setHours oder setMinutes ändern, sind diese Änderungen in der lokalen Zeit des Benutzers angegeben. Wenn Sie den Datensatz speichern, werden die tatsächlichen UTC-Werte serialisiert und wieder in Microsoft Dynamics 365 gespeichert. Sie müssen keine Maßnahmen ergreifen, um die Datumsangaben zurück in einen UTC-Wert zu konvertieren.

Wenn ein Date serialisiert wird, unterscheidet sich das Format von dem Format, das verwendet wurde, wenn die Daten abgerufen werden. Wie in Analyse abgerufener Daten angemerkt, werden Datumsangaben als Zeichenfolgen abgerufen, die das Format "\/Date(1311179400000)\/" verwenden. Wenn Sie die Ergebnisse von JSON.stringify für Datumswerte untersuchen, die zurück an den Server gegeben werden, ist das Format "2013-07-20T16:30:00Z"..

Legen Sie ein Datum als Kriterien in einem Filter in einer Abfrage fest

Wenn Sie einen Datumswert mit einer $filter-Systemabfrageoption verwenden, müssen Sie ein UTC-Datum verwenden. Um ein JavaScriptDate-Objekt in das Format zu konvertieren, das für einen Filter erwartet wird, müssen Sie die Datumsangaben mithilfe einer Funktion verarbeiten, wie im folgenden Beispiel gezeigt wird. Das Ergebnis ist eine Zeichenfolge, die dem folgenden Format entspricht: 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;
}

Siehe auch

Verwenden des OData-Endpunkts mit Webressourcen
OData endpoint Http status codes
JavaScript-Bibliotheken für Microsoft Dynamics CRM 2015
Webressourcen für Skripts (JScript)
Funktionen zu Formular- und Feldereignissen zuordnen
jQuery.ajax-Methode
XMLHttpRequest-Objekt
Technischer Artikel: Verwenden von Optionsset-Options mit dem ODATA-Endpunkt - JScript

Freigeben über

Verwenden des OData-Endpunkts mit Ajax- und JScript-Webressourcen

In diesem Thema

Ajax

JSON

XmlHttpRequest

Methoden-Tunneling durch POST

Zugreifen auf die Server-URL

Verwenden von XmlHttpRequest

Verwenden von jQuery

Legen Sie den Anforderungsheader explizit so fest, dass JSON akzeptiert wird

Legen Sie den Anforderungsheader explizit auf eine andere HTTP-Aktion fest

Verarbeiten von Fehlern

Verarbeiten von Ergebnissen

Verwenden von Datumsangaben

Analyse abgerufener Daten

Verwenden Sie eine reviver-Funktion mit der JSON.parse-Methode

Verwenden Sie String.replace, um einen Datumswert aus einer Zeichenfolge zu generieren

Anzeigen von Datumswerten

Aktualisieren von Datumswerten

Legen Sie ein Datum als Kriterien in einem Filter in einer Abfrage fest

Siehe auch

Zusätzliche Ressourcen