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["opportunityid@odata.bind"] = "/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,  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,  400 };
        Xrm.Navigation.openAlertDialog(alertStrings, alertOptions);
    }
);