示例:将 OData 终结点与 JavaScript 和 jQuery 结合使用来执行创建、检索、更新和删除操作
发布日期: 2016年11月
适用于: Dynamics CRM 2015
此示例代码适用于 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新。下载 Microsoft Dynamics CRM SDK 包。 它可能位于下载包的以下位置:
SampleCode\JS\RESTEndpoint\JQueryRESTDataOperations
重要
不建议在窗体脚本或功能区命令中使用 jQuery。 请参阅 示例:将 OData 终结点与 JavaScript 一起使用来执行创建、检索、更新和删除操作 获取具有相同功能但与 jQuery 并无依赖关系的示例库。
详细信息:jQuery 的使用。
备注
如果您只想了解此示例如何工作,则可以安装(导入)下载文件中包含的 JQueryRESTDataOperations_1_0_1_2_managed.zip 托管解决方案。 这将安装“JQuery REST 数据操作”解决方案。 如果安装此托管解决方案并想创建使用以下名称的 Web 资源,则您的解决方案发布商自定义前缀不能是“sample”,除非您卸载(删除)该托管解决方案。
要求
此示例使用以下 Web 资源:
sample_/JQueryRESTDataOperations.htm
使用此 HTML 页面启动示例并查看操作的进度。 此页面为“JQuery REST 数据操作”解决方案的配置页面。sample_/Scripts/jquery1.9.1.min.js
jQuery 最小化版本包括 Microsoft Visual Studio Web 应用程序项目。 其中不包括此库的内容。sample_/Scripts/JQueryRESTDataOperationsSample.js
JScript Web 资源执行该操作。 此库依赖于 SDK.JQuery.js 库。sample_/Scripts/SDK.JQuery.js
包含可重用库的 JScript Web 资源,通过使用 JQuery 与 REST 终结点一起执行操作。
> [!NOTE]
> 不依赖于 JQuery 的类似库在 <a href="gg334427(v=crm.7).md">示例:将 OData 终结点与 JavaScript 一起使用来执行创建、检索、更新和删除操作</a> 中可用。
备注
代码中不使用自定义前缀“sample_”。 这些示例将使用任何发布商的自定义前缀进行工作。 但是模拟的 Scripts 文件夹的相对路径需包括在 Web 资源的名称中。
演示
此示例:
将 REST 终结点与 JScript 和 jQuery 结合使用来执行创建、检索、更新和删除操作。
使用 jQuery,它是一种常用库,其中包括使用 $.ajax 方法执行数据操作的功能。
按顺序对新客户记录执行操作。
在运行示例时,您可以选择删除创建的记录。
在预览 Web 资源时,将显示类似如下的结果:sample_/JQueryRESTDataOperations.htm
设置主要联系人为:<您的系统中第一联系人记录的全名>。
将“首选联系方式”设置为“电子邮件”。
将“年收入”设置为“两百万”。
将“电话联系方式”设置为“不允许”。
使用 AccountId 创建名为“测试客户名称”的客户:“7780cef2-fdf4-e011-9d26-00155dba3819”。
检索 AccountId 为“7780cef2-fdf4-e011-9d26-00155dba3819”的客户。
检索名为“测试客户名称”的客户。 此客户的创建时间为:“Wed Oct 12 11:13:56 PDT 2011”。
将客户名称更改为“更新的客户名称”。
添加地址信息。
设置电子邮件地址。
已保存客户记录更改
您已选择删除客户记录。
客户已删除。
如果选择不删除客户,将会看到用于打开您所创建记录的链接。
sample_/JQueryRESTDataOperations.htm
本页提供一些解释以及用于启动和重置示例的按钮。
<html lang="en-us">
<head>
<title>JQuery REST Data Operations</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<script src="Scripts/jquery_1.9.1.min.js"></script>
<script src="Scripts/SDK.JQuery.js" type="text/javascript"></script>
<script src="Scripts/JQueryRESTDataOperationsSample.js" type="text/javascript"></script>
<!-- /WebResources/ClientGlobalContext.js.aspx is accessed using a relative path
because the name of the Web Resource created from this file is "sample_/JQueryRESTDataOperationsSample.htm".
The use of the backslash within the name creates a virtual folder that must be considered
in relative links between Web Resources.
-->
<script type="text/javascript" src="../ClientGlobalContext.js.aspx"></script>
</head>
<body style="background-color: White; font-family:Segoe UI;">
<h1>JavaScript jQuery REST Data Operations Sample</h1>
<p>This page uses the <b>sample_/Scripts/JQueryRESTDataOperationsSample.js</b> JScript library to create, retrieve, and update an
account record. It also provides the option to delete or view the record.</p>
<p>The <b>sample_/Scripts/JQueryRESTDataOperationsSample.js</b> JScript library uses the <b>sample_/Scripts/SDK.JQuery.js</b> JScript library to perform the data operations.</p>
<p>Use the buttons below to verify the functionality of this sample.</p>
<button id="start" title="Click this button to start the sample.">
Start</button>
<button id="reset" title="Click this button to reset the sample." disabled="disabled">
Reset</button>
<ol id="output">
</ol>
</body>
</html>
sample_/Scripts/JQueryRESTDataOperationsSample.js
此库包含用于管理页面上的 UI 元素的函数和示例执行的操作。 此库中的函数依赖于 sample_/Scripts/SDK.JQuery.js 中存在的可重用的泛型方法。
/// <reference path="SDK.JQuery.js" />
/// <reference path="jquery-1.9.1.js" />
var primaryContact = null;
var startButton;
var resetButton;
var output; //The <ol> element used by the writeMessage function to display text showing the progress of this sample.
$(function () {
getFirstContactToBePrimaryContact();
startButton = $("#start");
startButton.click(createAccount);
resetButton = $("#reset");
resetButton.click(resetSample);
output = $("#output");
});
function createAccount() {
startButton.attr("disabled", "disabled");
var account = {};
account.Name = "Test Account Name";
account.Description = "This account was created by the JQueryRESTDataOperations sample.";
if (primaryContact != null) {
//Set a lookup value
writeMessage("Setting the primary contact to: " + primaryContact.FullName + ".");
account.PrimaryContactId = { Id: primaryContact.ContactId, LogicalName: "contact", Name: primaryContact.FullName };
}
//Set a picklist value
writeMessage("Setting Preferred Contact Method to E-mail.");
account.PreferredContactMethodCode = { Value: 2 }; //E-mail
//Set a money value
writeMessage("Setting Annual Revenue to Two Million .");
account.Revenue = { Value: "2000000.00" }; //Set Annual Revenue
//Set a Boolean value
writeMessage("Setting Contact Method Phone to \"Do Not Allow\".");
account.DoNotPhone = true; //Do Not Allow
//Add Two Tasks
var today = new Date();
var startDate = new Date(today.getFullYear(), today.getMonth(), today.getDate() + 3); //Set a date three days in the future.
var LowPriTask = { Subject: "Low Priority Task", ScheduledStart: startDate, PriorityCode: { Value: 0} }; //Low Priority Task
var HighPriTask = { Subject: "High Priority Task", ScheduledStart: startDate, PriorityCode: { Value: 2} }; //High Priority Task
account.Account_Tasks = [LowPriTask, HighPriTask]
//Create the Account
SDK.JQuery.createRecord(
account,
"Account",
function (account) {
writeMessage("The account named \"" + account.Name + "\" was created with the AccountId : \"" + account.AccountId + "\".");
writeMessage("Retrieving account with the AccountId: \"" + account.AccountId + "\".");
retrieveAccount(account.AccountId)
},
errorHandler
);
}
function retrieveAccount(AccountId) {
SDK.JQuery.retrieveRecord(
AccountId,
"Account",
null, null,
function (account) {
writeMessage("Retrieved the account named \"" + account.Name + "\". This account was created on : \"" + account.CreatedOn + "\".");
updateAccount(AccountId);
},
errorHandler
);
}
function updateAccount(AccountId) {
var account = {};
writeMessage("Changing the account Name to \"Updated Account Name\".");
account.Name = "Updated Account Name";
writeMessage("Adding Address information");
account.Address1_AddressTypeCode = { Value: 3 }; //Address 1: Address Type = Primary
account.Address1_City = "Sammamish";
account.Address1_Line1 = "123 Maple St.";
account.Address1_PostalCode = "98074";
account.Address1_StateOrProvince = "WA";
writeMessage("Setting E-Mail address");
account.EMailAddress1 = "someone@microsoft.com";
SDK.JQuery.updateRecord(
AccountId,
account,
"Account",
function () {
writeMessage("The account record changes were saved");
deleteAccount(AccountId);
},
errorHandler
);
}
function deleteAccount(AccountId) {
if (confirm("Do you want to delete this account record?")) {
writeMessage("You chose to delete the account record.");
SDK.JQuery.deleteRecord(
AccountId,
"Account",
function () {
writeMessage("The account was deleted.");
enableResetButton();
},
errorHandler
);
}
else {
var urlToAccountRecord = SDK.JQuery._getClientUrl() + "/main.aspx?etc=1&id=%7b" + AccountId + "%7d&pagetype=entityrecord";
$("<li><span>You chose not to delete the record. You can view the record </span><a href='" +
urlToAccountRecord +
"' target='_blank'>here</a></li>").appendTo(output);
enableResetButton();
}
}
function getFirstContactToBePrimaryContact() {
SDK.JQuery.retrieveMultipleRecords(
"Contact",
"$select=ContactId,FullName&$top=1",
function (results) {
var firstResult = results[0];
if (firstResult != null) {
primaryContact = results[0];
}
else {
writeMessage("No Contact records are available to set as the primary contact for the account.");
}
},
errorHandler,
function () {
//OnComplete handler
}
);
}
function errorHandler(error) {
writeMessage(error.message);
}
function enableResetButton() {
resetButton.removeAttr("disabled");
}
function resetSample() {
output.empty();
startButton.removeAttr("disabled");
resetButton.attr("disabled", "disabled");
}
//Helper function to write data to this page:
function writeMessage(message) {
$("<li>" + message + "</li>").appendTo(output);
}
sample_/Scripts/SDK.JQuery.js
此库包含用于以下操作的公共方法:
createRecord
retrieveRecord
updateRecord
deleteRecord
retrieveMultipleRecords
其中每个方法都包括一个 successCallback 和 errorCallback 参数。 这些参数接受在数据操作成功或失败时将调用的函数的引用。
/// <reference path="jquery1.4.1vsdoc.js" />
if (typeof (SDK) == "undefined")
{ SDK = { __namespace: true }; }
SDK.JQuery = {
_context: function () {
///<summary>
/// Private function to the context object.
///</summary>
///<returns>Context</returns>
if (typeof GetGlobalContext != "undefined")
{ return GetGlobalContext(); }
else {
if (typeof Xrm != "undefined") {
return Xrm.Page.context;
}
else
{ throw new Error("Context is not available."); }
}
},
_getClientUrl: function () {
///<summary>
/// Private function to return the server URL from the context
///</summary>
///<returns>String</returns>
var serverUrl = this._context().getClientUrl()
return serverUrl;
},
_ODataPath: function () {
///<summary>
/// Private function to return the path to the REST endpoint.
///</summary>
///<returns>String</returns>
return this._getClientUrl() + "/XRMServices/2011/OrganizationData.svc/";
},
_errorHandler: function (req) {
///<summary>
/// Private function return an Error object to the errorCallback
///</summary>
///<param name="req" type="XMLHttpRequest">
/// The XMLHttpRequest response that returned an error.
///</param>
///<returns>Error</returns>
return new Error("Error : " +
req.status + ": " +
req.statusText + ": " +
JSON.parse(req.responseText).error.message.value);
},
_dateReviver: function (key, value) {
///<summary>
/// Private function to convert matching string values to Date objects.
///</summary>
///<param name="key" type="String">
/// The key used to identify the object property
///</param>
///<param name="value" type="String">
/// The string value representing a date
///</param>
var a;
if (typeof value === 'string') {
a = /Date\(([-+]?\d+)\)/.exec(value);
if (a) {
return new Date(parseInt(value.replace("/Date(", "").replace(")/", ""), 10));
}
}
return value;
},
_parameterCheck: function (parameter, message) {
///<summary>
/// Private function used to check whether required parameters are null or undefined
///</summary>
///<param name="parameter" type="Object">
/// The parameter to check;
///</param>
///<param name="message" type="String">
/// The error message text to include when the error is thrown.
///</param>
if ((typeof parameter === "undefined") || parameter === null) {
throw new Error(message);
}
},
_stringParameterCheck: function (parameter, message) {
///<summary>
/// Private function used to check whether required parameters are null or undefined
///</summary>
///<param name="parameter" type="String">
/// The string parameter to check;
///</param>
///<param name="message" type="String">
/// The error message text to include when the error is thrown.
///</param>
if (typeof parameter != "string") {
throw new Error(message);
}
},
_callbackParameterCheck: function (callbackParameter, message) {
///<summary>
/// Private function used to check whether required callback parameters are functions
///</summary>
///<param name="callbackParameter" type="Function">
/// The callback parameter to check;
///</param>
///<param name="message" type="String">
/// The error message text to include when the error is thrown.
///</param>
if (typeof callbackParameter != "function") {
throw new Error(message);
}
},
createRecord: function (object, type, successCallback, errorCallback) {
///<summary>
/// Sends an asynchronous request to create a new record.
///</summary>
///<param name="object" type="Object">
/// A JavaScript object with properties corresponding to the Schema name of
/// entity attributes that are valid for create operations.
///</param>
this._parameterCheck(object, "SDK.JQuery.createRecord requires the object parameter.");
///<param name="type" type="String">
/// The Schema Name of the Entity type record to create.
/// For an Account record, use "Account"
///</param>
this._stringParameterCheck(type, "SDK.JQuery.createRecord requires the type parameter is a string.");
///<param name="successCallback" type="Function">
/// The function that will be passed through and be called by a successful response.
/// This function can accept the returned record as a parameter.
/// </param>
this._callbackParameterCheck(successCallback, "SDK.JQuery.createRecord requires the successCallback is a function.");
///<param name="errorCallback" type="Function">
/// The function that will be passed through and be called by a failed response.
/// This function must accept an Error object as a parameter.
/// </param>
this._callbackParameterCheck(errorCallback, "SDK.JQuery.createRecord requires the errorCallback is a function.");
var jsonEntity = window.JSON.stringify(object);
$.ajax({ type: "POST",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: this._ODataPath() + type + "Set",
data: jsonEntity,
beforeSend: function (xhr) {
//Specifying this header ensures that the results will be returned as JSON.
xhr.setRequestHeader("Accept", "application/json");
},
success: function (data, textStatus, xhr) {
successCallback(data.d);
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(SDK.JQuery._errorHandler(xhr));
}
});
},
retrieveRecord: function (id, type, select, expand, successCallback, errorCallback) {
///<summary>
/// Sends an asynchronous request to retrieve a record.
///</summary>
///<param name="id" type="String">
/// A String representing the GUID value for the record to retrieve.
///</param>
this._stringParameterCheck(id, "SDK.JQuery.retrieveRecord requires the id parameter is a string.");
///<param name="type" type="String">
/// The Schema Name of the Entity type record to retrieve.
/// For an Account record, use "Account"
///</param>
this._stringParameterCheck(type, "SDK.JQuery.retrieveRecord requires the type parameter is a string.");
///<param name="select" type="String">
/// A String representing the $select OData System Query Option to control which
/// attributes will be returned. This is a comma separated list of Attribute names that are valid for retrieve.
/// If null all properties for the record will be returned
///</param>
if (select != null)
this._stringParameterCheck(select, "SDK.JQuery.retrieveRecord requires the select parameter is a string.");
///<param name="expand" type="String">
/// A String representing the $expand OData System Query Option value to control which
/// related records are also returned. This is a comma separated list of of up to 6 entity relationship names
/// If null no expanded related records will be returned.
///</param>
if (expand != null)
this._stringParameterCheck(expand, "SDK.JQuery.retrieveRecord requires the expand parameter is a string.");
///<param name="successCallback" type="Function">
/// The function that will be passed through and be called by a successful response.
/// This function must accept the returned record as a parameter.
/// </param>
this._callbackParameterCheck(successCallback, "SDK.JQuery.retrieveRecord requires the successCallback parameter is a function.");
///<param name="errorCallback" type="Function">
/// The function that will be passed through and be called by a failed response.
/// This function must accept an Error object as a parameter.
/// </param>
this._callbackParameterCheck(errorCallback, "SDK.JQuery.retrieveRecord requires the errorCallback parameter is a function.");
var systemQueryOptions = "";
if (select != null || expand != null) {
systemQueryOptions = "?";
if (select != null) {
var selectString = "$select=" + select;
if (expand != null) {
selectString = selectString + "," + expand;
}
systemQueryOptions = systemQueryOptions + selectString;
}
if (expand != null) {
systemQueryOptions = systemQueryOptions + "&$expand=" + expand;
}
}
$.ajax({
type: "GET",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: this._ODataPath() + type + "Set" + "(guid'" + id + "')" + systemQueryOptions,
beforeSend: function (xhr) {
//Specifying this header ensures that the results will be returned as JSON.
xhr.setRequestHeader("Accept", "application/json");
},
success: function (data, textStatus, xhr) {
//JQuery does not provide an opportunity to specify a date reviver so this code
// parses the xhr.responseText rather than use the data parameter passed by JQuery.
successCallback(JSON.parse(xhr.responseText, SDK.JQuery._dateReviver).d);
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(SDK.JQuery._errorHandler(xhr));
}
});
},
updateRecord: function (id, object, type, successCallback, errorCallback) {
///<summary>
/// Sends an asynchronous request to update a record.
///</summary>
///<param name="id" type="String">
/// A String representing the GUID value for the record to retrieve.
///</param>
this._stringParameterCheck(id, "SDK.JQuery.updateRecord requires the id parameter.");
///<param name="object" type="Object">
/// A JavaScript object with properties corresponding to the Schema Names for
/// entity attributes that are valid for update operations.
///</param>
this._parameterCheck(object, "SDK.JQuery.updateRecord requires the object parameter.");
///<param name="type" type="String">
/// The Schema Name of the Entity type record to retrieve.
/// For an Account record, use "Account"
///</param>
this._stringParameterCheck(type, "SDK.JQuery.updateRecord requires the type parameter.");
///<param name="successCallback" type="Function">
/// The function that will be passed through and be called by a successful response.
/// Nothing will be returned to this function.
/// </param>
this._callbackParameterCheck(successCallback, "SDK.JQuery.updateRecord requires the successCallback is a function.");
///<param name="errorCallback" type="Function">
/// The function that will be passed through and be called by a failed response.
/// This function must accept an Error object as a parameter.
/// </param>
this._callbackParameterCheck(errorCallback, "SDK.JQuery.updateRecord requires the errorCallback is a function.");
var jsonEntity = window.JSON.stringify(object);
$.ajax({
type: "POST",
contentType: "application/json; charset=utf-8",
datatype: "json",
data: jsonEntity,
url: this._ODataPath() + type + "Set" + "(guid'" + id + "')",
beforeSend: function (xhr) {
//Specifying this header ensures that the results will be returned as JSON.
xhr.setRequestHeader("Accept", "application/json");
//Specify the HTTP method MERGE to update just the changes you are submitting.
xhr.setRequestHeader("X-HTTP-Method", "MERGE");
},
success: function (data, textStatus, xhr) {
//Nothing is returned to the success function
successCallback();
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(SDK.JQuery._errorHandler(xhr));
}
});
},
deleteRecord: function (id, type, successCallback, errorCallback) {
///<summary>
/// Sends an asynchronous request to delete a record.
///</summary>
///<param name="id" type="String">
/// A String representing the GUID value for the record to delete.
///</param>
this._stringParameterCheck(id, "SDK.JQuery.deleteRecord requires the id parameter.");
///<param name="type" type="String">
/// The Schema Name of the Entity type record to delete.
/// For an Account record, use "Account"
///</param>
this._stringParameterCheck(type, "SDK.JQuery.deleteRecord requires the type parameter.");
///<param name="successCallback" type="Function">
/// The function that will be passed through and be called by a successful response.
/// Nothing will be returned to this function.
/// </param>
this._callbackParameterCheck(successCallback, "SDK.JQuery.deleteRecord requires the successCallback is a function.");
///<param name="errorCallback" type="Function">
/// The function that will be passed through and be called by a failed response.
/// This function must accept an Error object as a parameter.
/// </param>
this._callbackParameterCheck(errorCallback, "SDK.JQuery.deleteRecord requires the errorCallback is a function.");
$.ajax({
type: "POST",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: this._ODataPath() + type + "Set(guid'" + id + "')",
beforeSend: function (XMLHttpRequest) {
//Specifying this header ensures that the results will be returned as JSON.
XMLHttpRequest.setRequestHeader("Accept", "application/json");
//Specify the HTTP method DELETE to perform a delete operation.
XMLHttpRequest.setRequestHeader("X-HTTP-Method", "DELETE");
},
success: function (data, textStatus, xhr) {
// Nothing is returned to the success function.
successCallback();
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(SDK.JQuery._errorHandler(xhr));
}
});
},
retrieveMultipleRecords: function (type, options, successCallback, errorCallback, OnComplete) {
///<summary>
/// Sends an asynchronous request to retrieve records.
///</summary>
///<param name="type" type="String">
/// The Schema Name of the Entity type records to retrieve
/// For an Account record, use "Account"
///</param>
this._stringParameterCheck(type, "SDK.JQuery.retrieveMultipleRecords requires the type parameter is a string.");
///<param name="options" type="String">
/// A String representing the OData System Query Options to control the data returned
/// Do not include the $top option, use the top parameters to set the maximum number of records to return.
///</param>
if (options != null)
this._stringParameterCheck(options, "SDK.JQuery.retrieveMultipleRecords requires the options parameter is a string.");
///<param name="successCallback" type="Function">
/// The function that will be passed through and be called for each page of records returned.
/// This function should loop through the results and push the records into an array.
/// </param>
this._callbackParameterCheck(successCallback, "SDK.JQuery.retrieveMultipleRecords requires the successCallback parameter is a function.");
///<param name="errorCallback" type="Function">
/// The function that will be passed through and be called by a failed response.
/// This function must accept an Error object as a parameter.
/// </param>
this._callbackParameterCheck(errorCallback, "SDK.JQuery.retrieveMultipleRecords requires the errorCallback parameter is a function.");
///<param name="OnComplete" type="Function">
/// The function that will be called when all the requested records have been returned.
/// No parameters are passed to this function.
/// </param>
this._callbackParameterCheck(OnComplete, "SDK.JQuery.retrieveMultipleRecords requires the OnComplete parameter is a function.");
var optionsString;
if (options != null) {
if (options.charAt(0) != "?") {
optionsString = "?" + options;
}
else
{ optionsString = options; }
}
$.ajax({
type: "GET",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: this._ODataPath() + type + "Set" + optionsString,
beforeSend: function (XMLHttpRequest) {
//Specifying this header ensures that the results will be returned as JSON.
XMLHttpRequest.setRequestHeader("Accept", "application/json");
},
success: function (data, textStatus, xhr) {
if (data && data.d && data.d.results) {
successCallback(JSON.parse(xhr.responseText, SDK.JQuery._dateReviver).d.results);
if (data.d.__next != null) {
var queryOptions = data.d.__next.substring((SDK.JQuery._ODataPath() + type + "Set").length);
SDK.JQuery.retrieveMultipleRecords(type, queryOptions, successCallback, errorCallback, OnComplete);
}
else
{ OnComplete(); }
}
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(SDK.JQuery._errorHandler(xhr));
}
});
},
__namespace: true
};
另请参阅
JQuery
将 OData 终结点用于 Web 资源
示例:将 OData 终结点与 JavaScript 一起使用来执行创建、检索、更新和删除操作
示例:将 OData 终结点与 JavaScript 结合使用来检索多条记录
技术文章:将选项集选项与 REST 端点结合使用 - JScript
© 2017 Microsoft。 保留所有权利。 版权