範例:使用 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。 針對擁有相同的功能,但沒有 jQuery 相依性的範例程式庫,請參閱 範例:使用 OData 端點和 JavaScript 建立、擷取、更新及刪除。
其他資訊:使用 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
包括在 Microsoft Visual Studio Web 應用程式專案中最精簡的 jQuery 版本。 此程式庫內容未包含於此處。sample_/Scripts/JQueryRESTDataOperationsSample.js
執行作業的 JScript Web 資源。 此程式庫依賴 SDK.JQuery.js 程式庫。sample_/Scripts/SDK.JQuery.js
JScript Web 資源,包含可重複使用的程式庫,使用 REST 端點與 JQuery 執行動作。
注意
沒有 JQuery 相依性、類似程式庫可在 範例:使用 OData 端點和 JavaScript 建立、擷取、更新及刪除 中找到。
注意
自訂首碼 “sample_” 並未用於程式碼。 利用任何發行者的自訂首碼,這些範例都會運作。 不過已模擬 Scripts 資料夾的相對路徑必須包含在 Web 資源的名稱中。
示範
此範例:
使用 REST 端點和 JScript 及 jQuery,執行建立、擷取、更新及刪除作業。
使用 jQuery,這個常用的程式庫包括功能,可使用 $.ajax 方法執行資料作業。
在新客戶記錄上依序執行作業。
當您執行範例,可以選擇刪除已建立的記錄。
預覽 Web 資源時,顯示類似下列的結果:sample_/JQueryRESTDataOperations.htm
將主要連絡人設定為:<系統中第一個連絡人記錄的全名>。
將偏好的連絡方法設定為電子郵件。
將年度營收設定為兩百萬。
將連絡人方式電話設定為「不允許」。
客戶名稱「Test Account Name」是以 AccountId:「7780cef2-fdf4-e011-9d26-00155dba3819」建立的。
擷取具有 AccountId:"7780cef2-fdf4-e011-9d26-00155dba3819" 的客戶。
擷取名為 "Test Account Name" 的客戶。 此客戶建立時間:「2011 年 10 月 12 日星期三 11:13:56 PDT」。
變更客戶名稱為 "Updated Account Name"。
新增地址資訊。
設定電子郵件地址。
客戶記錄變更已儲存
您選擇刪除客戶記錄。
客戶已刪除。
如果您選擇不刪除客戶,會看到連結開啟剛才建立的記錄。
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. 著作權所有,並保留一切權利。 著作權