Dynamics 365 V9版本新的客戶端API Xrm.WebApi.online.execute 使用實例

我是微軟Dynamics 365 & Power Platform方面的工程師羅勇，也是2015年7月到2018年6月連續三年Dynamics CRM/Business Solutions方面的微軟最有價值專家(Microsoft MVP)，歡迎關注我的微信公眾號 MSFTDynamics365erLuoYong ，回復393或者20200212可方便獲取本文，同時可以在第一間得到我發布的最新博文信息，follow me!

Dynamics 365 Customer Engagement V9版本新增了客戶端API：Xrm.WebApi.online.execute ，官方文檔請參考：Xrm.WebApi.online.execute (Client API reference) 。

示例中舉了非綁定操作(Action)的調用，但是沒有綁定操作的調用示例，Dynamics MVP Debajit Dutta 的文章 Calling bound actions (entity actions) using Xrm.WebApi.execute in Dynamics V9 有介紹，我這里稍微改動一點轉換過來。

1. 調用綁定action必須傳遞參數 entity 的值，這個entity的值就是一個類似 { entityType: "account", id: accountid } 的對象，它是操作綁定的實體要執行該操作的記錄。

2. 操作的為EntityReference類型的輸入參數和調用時候傳遞的entity參數，其對應的structuralProperty的值為5，也就是 EntityType 。

3.參數的typeName的值請參考 Settings –> Customizations –> Developer Sesources -> Instance Web API 中 Download OData Metadata 鏈接下載下來的操作的輸入參數的Type值，類似如下圖。如果是EntityReference類型的參數，typeName的值是該實體的邏輯名稱前面加上mscrm. 。

 

 4. 操作返回參數值的獲取請參考我后面的代碼，是 result.json().then 中能獲取到返回值。

話不多說，上個調用示例，我這個操作是綁定在客戶(account)實體上。

var ly_accountid = formContext.getAttribute("lvo_accountid").getValue();
if (ly_accountid !== null) {
    var accountid = ly_accountid[0].id.replace("{", "").replace("}", "");
    var target = { entityType: "account", id: accountid };
    var reqObject = {};
    reqObject.getMetadata = function () {
        return {
            boundParameter: "entity",
            operationType: 0,
            operationName: "ly_LuoYongBoundAction",
            parameterTypes: {
                "entity": {
                    typeName: "mscrm.account",
                    structuralProperty: 5
                }
            }
        }
    };
    reqObject.entity = target;
    Xrm.WebApi.online.execute(reqObject).then(
        function (result) {
            if (result.ok) {
                console.log("Status: %s %s", result.status, result.statusText);
                result.json().then(
                    function (response) {
                        //此處獲取到了操作返回參數的值
                        console.log(response);
                        alert(response.OutCountry.ly_testid);
                    });
            }
        },
        function (error) {
            console.log(error);
            Xrm.Utility.alertDialog(error.message);
        }
    );
}

 

我這里還記錄下自己寫HTTP請求調用非綁定操作的代碼示例：

var clientURL = Xrm.Utility.getGlobalContext().getClientUrl();
var req = new XMLHttpRequest()
req.open("POST", encodeURI(clientURL + "/api/data/v9.1/WinOpportunity"), true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
    if (this.readyState == 4 /* complete */) {
        req.onreadystatechange = null;
        if (this.status == 204) {
            Xrm.Utility.alertDialog("將商機作為贏單關閉成功!");
        }
        else {
            var error = JSON.parse(this.response).error;
            Xrm.Utility.alertDialog("將商機作為贏單關閉出錯." + error.message);
        }
    }
};
var requestmsg = {};
requestmsg.Status = 3;
requestmsg.OpportunityClose = {};
requestmsg.OpportunityClose.subject = "羅勇結束了這個商機";
requestmsg.OpportunityClose["[e-mail]"] = "/opportunities(6025165A-3AA3-E511-80C7-000D3A807EC7)";
req.send(JSON.stringify(requestmsg));

 

調用綁定操作的示例：

var clientURL = Xrm.Utility.getGlobalContext().getClientUrl();
var req = new XMLHttpRequest()
req.open("POST", encodeURI(clientURL + "/api/data/v9.1/teams(E4CC382D-02B9-E511-80DC-000D3A804C3F)/Microsoft.Dynamics.CRM.RemoveMembersTeam"), true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
    if (this.readyState == 4 /* complete */) {
        req.onreadystatechange = null;
        if (this.status == 204) {
            Xrm.Utility.alertDialog("將用戶移出團隊成功!");
        }
        else {
            var error = JSON.parse(this.response).error;
            Xrm.Utility.alertDialog("將用戶移出團隊出錯." + error.message);
        }
    }
};
var requestmsg = {};
requestmsg.Members = [];
requestmsg.Members[0] = {};
requestmsg.Members[0].systemuserid = "A576C4B5-44A9-E511-80CF-000D3A806074";
requestmsg.Members[1] = {};
requestmsg.Members[1].systemuserid = "CEFE67E5-44A9-E511-80CF-000D3A806074";
req.send(JSON.stringify(requestmsg));

 

當然通過組織服務也是可以調用Action的，示例如下：

            OrganizationRequest req = new OrganizationRequest("ly_AssignAction");
            req["InRequestType"] = new EntityReference("ly_casetype",Guid.Parse("4deeef82-4830-ea11-a810-000d3a3786fc"));
            req["InRequestSubType"] = new EntityReference("ly_casetype", Guid.Parse("7a66ea89-4930-ea11-a810-000d3a3786fc"));
            req["Target"] = new EntityReference("ly_servicerequest", Guid.Parse("d5315ee2-ca53-ea11-a812-000d3a378f47"));//global action則無需此參數
            crmSvc.Execute(req);

 

再舉個調用非綁定action的例子，這兩個輸入參數都是EntityReference類型，注意傳遞值的方法：

var AssignActionRequest = function (entityLogicalName, entityId, businessGroup, group, requestType) {
    this.InEntityLogicalName = entityLogicalName;
    this.InEntityId = entityId;
    this.InGroup = group;
    this.InRequestType = requestType;
};

AssignActionRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {
            "InEntityLogicalName": {
                typeName: "Edm.String",
                structuralProperty: 1
            },
            "InEntityId": {
                typeName: "Edm.String",
                structuralProperty: 1
            },
            "InGroup": {
                typeName: "mscrm.ly_demoentitylogicalname",
                structuralProperty: 5
            },
            "InRequestType": {
                typeName: "mscrm.lvo_casetype",
                structuralProperty: 5
            }
        },
        operationType: 0,
        operationName: "ly_AssignAction",
    };
};

var requestType = {
    "ly_casetypeid": "4d1eef82-4830-ea11-a810-000d3a3786fc"
}

var assignActionRequest = new AssignActionRequest("lvo_orderchangerequest", "{d5315ee2-ca53-ea11-a812-000d3a378f47}", null, equestType);
//如下也可以
//var assignActionRequest = new AssignActionRequest("lvo_orderchangerequest", "d5315ee2-ca53-ea11-a812-000d3a378f47",null,equestType);
Xrm.WebApi.online.execute(assignActionRequest).then(
    function (result) {
        if (result.ok) {
            var alertStrings = { confirmButtonLabel: "OK", text: "Operation compeleted successfully.", title: "Info" };
            var alertOptions = { height: 300, width: 400 };
            Xrm.Navigation.openAlertDialog(alertStrings, alertOptions);
        }
    },
    function (error) {
        console.log(error);
        var alertStrings = { confirmButtonLabel: "OK", text: "Operation Failed. " + error.message, title: "Error" };
        var alertOptions = { height: 300, width: 400 };
        Xrm.Navigation.openAlertDialog(alertStrings, alertOptions);
    }
);