Utiliser le point de terminaison OData avec les ressources Web Ajax et JScript

Date de publication : novembre 2016

S’applique à : Dynamics CRM 2015

Le point de terminaison OData vous permet d’interagir avec les données Mise à jour de Microsoft Dynamics CRM 2015 et de Microsoft Dynamics CRM Online 2015 à l’aide des bibliothèques JavaScript. Vous créez des ressources Web de script en utilisant des fichiers qui définissent les bibliothèques JavaScript. Vous associez ensuite les fonctions des bibliothèques aux gestionnaires d’événements de formulaire ou de champ ou aux actions de la commande du ruban. Vous pouvez les utiliser comme vous le feriez avec toute autre bibliothèque JavaScript dans les ressources Web (HTML) d’une page Web.

Contenu de la rubrique

Ajax

Tunnelage de méthode via POST

Accéder à l’URL du serveur

Utiliser XmlHttpRequest

Utiliser jQuery

Utiliser les dates

Ajax

AJAX (JavaScript et XML asynchrones) est une technique de développement Web utilisée pour créer des applications Web interactives. Les demandes du serveur sont effectuées à partir du navigateur en arrière-plan à l’aide d’un objet XmlHttpRequest. Bien que vous puissiez envoyer des demandes synchrones, la pratique recommandée consiste à envoyer des demandes asynchrones. Les demandes asynchrones requièrent deux fonctions JScript, une fonction pour envoyer la demande et une deuxième fonction de « rappel » pour traiter une réponse.

JSON

Le format JSON (JavaScript Object Notation) est utilisé pour sérialiser et transmettre des données structurées de la même manière que XML est généralement utilisé. À l’instar de XML, il est basé sur du texte et conçu pour être lisible. Pour convertir des objets JavaScript ordinaires au format JSON, vous utilisez la méthode JSON.stringify. Étant donné que le texte au format JSON définit des objets JavaScript, il peut être converti en objets JavaScript à l’aide de la méthode eval. Toutefois, cette pratique crée des vulnérabilités de sécurité. Vous devez utiliser la méthode JSON.parse à la place.

XmlHttpRequest

XmlHttpRequest (parfois appelé XHR) fournit des fonctionnalités permettant de configurer et d’envoyer des demandes et de définir une fonction de rappel si la demande est asynchrone. La réponse HTTP du serveur comprend un code de statut qui indique si la demande a réussi. Les valeurs de code de statut HTTP comprises dans la plage 200 sont considérées comme réussies.

Un objet XmlHttpRequest fournit des instructions au serveur sur le format des données à inclure dans la réponse. Étant donné que le point de terminaison ODATA prend en charge les formats ATOM et JSON, vous pouvez demander à ce que les données soient retournées au format XMLATOM. Cependant, avec le code JavaScript, la demande standard attendue utilise JSON, car ce format est facilement utilisable avec JavaScript.

Tunnelage de méthode via POST

Le protocole OData utilise moins les verbes HTTP courants PUT et DELETE ainsi que la définition d’un nouveau verbe : MERGE. Selon les bibliothèques de prise en charge que vous utilisez, vous pouvez rencontrer des problèmes lors de l’utilisation de ces verbes. La solution pour contourner ce problème consiste à utiliser le verbe POST et à spécifier un en-tête HTTPX-HTTP-Method avec l’action souhaitée. Utilisez la méthode setRequestHeader pour remplacer l’action spécifiée dans XmlHttpRequest.

Accéder à l’URL du serveur

La première action à effectuer lorsque vous commencez à utiliser le point de terminaison ODATA avec JavaScript consiste à établir l’URL sur l’URL racine de l’organisation. Utilisez la fonction getClientUrl de l’objet de contexte.

• Si votre script est conçu pour fonctionner dans le contexte d’un événement de formulaire ou de champ, ou de <JavaScriptFunction> (RibbonDiffXml) pour une commande de ruban, vous pouvez utiliser l’objet Xrm.Page.context pour appeler getClientUrl.

• Si votre script s’exécute dans le contexte de la ressource Web (HTML) d’une page Web, vous devez inclure une référence à la page ClientGlobalContext.js.aspx dans la ressource Web HTML pour pouvoir utiliser la Fonction GetGlobalContext.

Utiliser XmlHttpRequest

jQuery est une bibliothèque efficace avec une variété d’utilisations, mais l’utilisation de jQuery n’est pas une condition préalable à l’exécution d’opérations à l’aide du point de terminaison ODATA pour Microsoft Dynamics 365. Nous vous déconseillons d’utiliser jQuery dans les scripts de formulaire ou de commande qui s’exécutent dans les pages d’application. Utilisez XmlHttpRequest directement sans avoir à charger la bibliothèque jQuery.jQuery**$.ajax** utilise XmlHttpRequest disponible dans le navigateur. L’utilisation directe de cet objet est légèrement différente de l’utilisation de $.ajax. Si vous avez l’habitude d’utiliser XMLHttpRequest, vous devez continuer à l’utiliser. Si vous avez toujours utilisé jQuery, envisagez d’utiliser directement XMLHttpRequest.Pour plus d'informations :Objet XMLHttpRequest

Avec XmlHttpRequest, vous créez un gestionnaire d’événements pour l’événement onreadystatechange et détectez quand la demande est terminée. Dans le gestionnaire d’événements, activez le code de statut retourné pour déterminer si la demande a réussi. Enfin, utilisez les méthodes open et send. L’exemple de code suivant utilise XmlHttpRequest pour créer un enregistrement de compte.

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

Pour plus d’exemples avec XMLHttpRequest, consultez Exemple : créer, extraire, mettre à jour et supprimer le point de terminaison OData avec JavaScript

Utiliser jQuery

jQuery est une bibliothèque JavaScript populaire fournie avec les projets d'application Web dans Microsoft Visual Studio.jQuery fournit une structure étendue d'objets et de fonctions qui vous permettent d'interroger et d'utiliser des pages HTML avec JavaScript. Pour utiliser XMLHttpRequest, jQuery fournit la méthode jQuery.ajax.

L’objet jQuery est référencé avec le caractère $ ; par conséquent, la forme abrégée pour jQuery.ajax est $.ajax. La méthode ajax est généralement utilisée avec une syntaxe impérative et la demande est envoyée dès que l’objet est instancié. L’exemple de code suivant crée un enregistrement de compte.

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

Le tableau suivant répertorie les propriétés que vous devrez connaître pour traiter les demandes et les réponses HTTP à l’aide du point de terminaison ODATA pour Microsoft Dynamics 365.

Pour plus d'informations, voir Exemple : créer, extraire, mettre à jour et supprimer le point de terminaison OData avec JavaScript et jQuery.

Définir explicitement l’en-tête de demande pour accepter JSON

Lorsque vous attendez des résultats au format JSON, la définition de la propriété dataType risque de ne pas fonctionner. Vous pouvez utiliser la propriété beforeSend pour définir explicitement les en-têtes sur XMLHttpRequest pour retourner les données au format JSON. Cette opération est généralement effectuée à l’aide d’une fonction anonyme, comme illustré dans l’exemple suivant.

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

Lorsqu’elles sont spécifiées, les erreurs dans XMLHttpRequest.responseText sont mises en forme au format JSON au lieu du format XML.

Définir explicitement l’en-tête de demande sur une action HTTP différente

Comme décrit dans Tunnelage de méthode via POST, lorsque vous effectuez une action qui requiert une action HTTP autre que POST ou GET, utilisez POST et la propriété beforeSend pour définir explicitement les en-têtes sur XMLHttpRequest pour effectuer une action différente. Cette opération est généralement effectuée à l’aide d’une fonction anonyme, comme illustré dans l’exemple suivant.

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

Gérer les erreurs

Lorsqu’une demande échoue, $.ajax transmet les trois arguments ci-après à une fonction définie dans la propriété d’erreur.

• XMLHttpRequest
  Objet XMLHttpRequest.

• textStatus
  Chaîne qui décrit le type d’erreur qui s’est produite. Les valeurs possibles sont les suivantes :

  • null

  • timeout

  • error

  • notmodified

  • parsererror

• errorThrown
  Objet d’exception facultatif.

L’exemple suivant montre comment transmettre ces arguments à une fonction centrale qui gère les erreurs.

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

L’exemple suivant illustre une fonction simple qui capture le message d’erreur et affiche le résultat à l’aide de la fonction showMessage.

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

Traiter les résultats

Lorsque vous effectuez des opérations POST ou GET, vous pouvez vous attendre à ce que les données soient retournées. Si vous avez spécifié que les résultats soient retournés au format JSON, ceux-ci seront dans la propriété d de l’objet de données retourné. Lorsque vous créez ou récupérez un enregistrement à l’aide de l’identificateur unique, d représente les données de l’enregistrement. Dans tous les autres cas, d est un tableau.

L’exemple suivant illustre le traitement des résultats d’une requête qui retourne plusieurs enregistrements de compte.

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

Utiliser les dates

Il existe quatre tâches impliquant les dates que vous devrez peut-être effectuer :

• Analyser les données récupérées

• Afficher les valeurs de date

• Mettre à jour les valeurs de date

• Définir une date comme critère de filtre dans une requête

Analyser les données récupérées

Lorsque vous récupérez des enregistrements à l’aide du point de terminaison ODATA, les valeurs de date sont retournées en tant que chaînes qui utilisent le format « \/Date(<ticks>)\/ », où <ticks> correspond au nombre de millisecondes depuis le 1er janvier 1970 à minuit. Par exemple : "\/Date(1311170400000)\/". Toutes les valeurs retournées par Microsoft Dynamics 365 représentent les valeurs UTC ; par conséquent, aucune information de décalage n’est incluse.

Deux stratégies vous permettent d’analyser les dates dans les enregistrements retournés à l’aide du point de terminaison ODATA :

• Utiliser une fonction reviver avec la méthode JSON.parse

• Utiliser String.replace pour générer une valeur de date à partir d’une chaîne

Utiliser une fonction reviver avec la méthode JSON.parse

La méthode JSON.parse prend en charge un argument reviver facultatif, comme décrit dans la Documentation de la méthode JSON.parse sur MSDN. L’exemple suivant convertit les valeurs de chaîne correspondant à un modèle défini dans une expression régulière en objets 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;
};

Utiliser String.replace pour générer une valeur de date à partir d’une chaîne

Si vous n’utilisez pas l’argument reviver avec la méthode JSON.parse, l’exemple suivant montre comment générer une valeur Date à partir d’une chaîne.

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

Afficher les valeurs de date

Une fois que les valeurs de date de chaîne sont converties en objets Date, vous pouvez utiliser une variété de méthodes JavaScript, ou créer votre propre méthode, pour afficher la date sous forme de chaîne dans une interface utilisateur. Étant donné que l’objet Date de JavaScript est compatible UTC, les dates affichées dans votre interface utilisateur à l’aide des méthodes telles que toString ou toLocaleString reflètent les paramètres de fuseau horaire du système d’exploitation de l’utilisateur.

Toutefois, notez que les valeurs dans votre application peuvent être différentes de celles affichées dans Microsoft Dynamics 365, qui ne dépend pas des paramètres de fuseau horaire du système d’exploitation de l’utilisateur. Ces valeurs sont différentes lorsque les préférences de fuseau horaire du système d'exploitation de l'utilisateur ne correspondent pas à celles enregistrées dans Microsoft Dynamics 365.Microsoft Dynamics 365 permet également de définir des options de présentation personnalisées qui ne sont pas appliquées à l'aide de fonctions de date JavaScript standard comme toString.

Si vous souhaitez rapprocher les valeurs de date et d’heure affichées pour correspondre aux valeurs affichées dans Microsoft Dynamics 365, vous pouvez interroger les données stockées dans l’entité UserSettings et les entités telles que TimeZoneDefinition et TimeZoneRule pour créer des fonctions pour afficher les dates correspondant aux préférences de l’utilisateur.Microsoft Dynamics 365 ne fournit pas de fonctions pour effectuer ces actions.

Mettre à jour les valeurs de date

Lorsque vous modifiez les valeurs d’une date JavaScript à l’aide de méthodes de définition standard telles que setMinutes ou setHours, ces modifications s’appliquent à l’heure locale de l’utilisateur. Lorsque vous sauvegardez l’enregistrement, les valeurs UTC réelles sont sérialisées et enregistrées dans Microsoft Dynamics 365. Aucune action n’est nécessaire pour convertir les dates en une valeur UTC.

Lorsqu’une Date est sérialisée, le format est différent du format utilisé lors de la récupération des données. Comme indiqué dans Analyser les données récupérées, les dates sont récupérées sous forme de chaînes qui utilisent le format "\/Date(1311179400000)\/". Lorsque vous examinez les résultats de JSON.stringify pour retourner les valeurs de date au serveur, le format est "2013-07-20T16:30:00Z".

Définir une date comme critère de filtre dans une requête

Lorsque vous utilisez une valeur de date avec une option de requête système $filter, vous devez utiliser une date UTC. Pour convertir un objet DateJavaScript au format attendu pour un filtre, vous devez traiter la date à l’aide d’une fonction, comme dans l’exemple ci-après. Le résultat est une chaîne qui correspond au format suivant : 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;
}

Voir aussi

Utiliser le point de terminaison OData avec les ressources Web
OData endpoint Http status codes
Bibliothèques JavaScript pour Microsoft Dynamics CRM 2015
Ressources Web de script (JScript)
Associer des fonctions aux événements de formulaire et de champ
Méthode jQuery.ajax
Objet XMLHttpRequest
Article technique : Utilisation des options de groupe d’options avec le point de terminaison ODATA - JScript

© 2017 Microsoft. Tous droits réservés. Copyright