Dynamics CRM 2015/2016新特性之二十：Web API介绍及使用它创建记录

Posted 2020-12-10 微软MVP(15-18)罗勇

关注本人微信和易信公众号： 微软动态CRM专家罗勇 ，回复203或者20160309可方便获取本文，同时可以在第一间得到我发布的最新的博文信息，follow me！

从Dynamics CRM 2015 UR1开始提供Web API的预览版本，到Dynamics CRM 2016终于出来正式版本了。它实现的是OASIS的OData v4.0标准，支持OAuth认证，支持JSON。原来的OData终结点虽然依然可以使用，但是不再推荐使用了。
关于调用Web API的认证，在Web资源，表单代码或者命令栏使用的命令中调用它还是不需要撰写任何代码进行认证，已经自动做好这个步骤了，这个和以前的OData终结点是一样的。对于本地部署的CRM的认证，SDK中提供的示例代码，对于CRM Online和做了IFD部署本地CRM，是要通过OAuth进行，如果是使用javascript的单页应用(single page application)则可以使用adal.js ，这些在SDK的 Authenticate to Microsoft Dynamics CRM with the Web API 有详细论述，我就不赘述了，本博客以后也会分享详细的文章阐述。
有三个url值得关注，分别是：
http://lycrmvm.cloudapp.net:5555/Demo/api/data/v8.0 截图显示如下，应该是每个实体一条记录，每条记录的kind属性值都为EntitySet，url属性的值就是访问该实体的部分url，name属性据我观察是实体的逻辑名称的复数形式。

 

 

第二个url就是查看某个实体的记录用到的，比如 http://lycrmvm.cloudapp.net:5555/Demo/api/data/v8.0/accounts ，截图如下，只是中文是编码的：

 

 

第三个url是 http://lycrmvm.cloudapp.net:5555/Demo/api/data/v8.0/$metadata 用来查看元数据的，可以用 NavigationProperty 、ComplexType 和 EnumType搜索一些特殊的元素。

 

  

下面我们通过Web API来做一些常做的事情。今天介绍的是使用Web API来插入记录，示例代码如下：

function ConvertStringToDatetime(dateString) {
    var reggie = /(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})Z/;
    var dateArray = reggie.exec(dateString);
    var dateObject = new Date(
        (+dateArray[1]),
        (+dateArray[2]) - 1,
        (+dateArray[3]),
        (+dateArray[4]),
        (+dateArray[5]),
        (+dateArray[6])
    );
    return dateObject;
}
function NameOnchangeHandler() {
    var clientURL = Xrm.Page.context.getClientUrl();
    var req = new XMLHttpRequest()
    req.open("POST", encodeURI(clientURL + "/api/data/v8.0/ly_tests"), 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) {
                var testUri = this.getResponseHeader("OData-EntityId");
                Xrm.Utility.alertDialog("创建成功的罗勇测试试题记录的URI: " + testUri)
            }
            else {
                var error = JSON.parse(this.response).error;
                Xrm.Utility.alertDialog("创建罗勇测试实体记录出错." + error.message);
            }
        }
    };
    var test = {};
    test.ly_name = "单行文本";//单行文本
    test.ly_alternatekey = "13926492291";//单行文本
    test.ly_bool = true;//两个选项
    test.ly_datetime = ConvertStringToDatetime(\'2016-01-07T11:22:30Z\');//日期和时间,需要将UTC时间转换为本地时间
    test.ly_decimal = 10.01;//十进制数
    test.ly_float = 10.02//浮点数
    test["[e-mail]"] = "/accounts(CE23165A-3AA3-E511-80C7-000D3A807EC7)"//查找字段,注意去/api/data/v8.0/$metadata页面查看关系的Partner属性的值
    test.ly_integer = 10;//整数
    test.ly_money = 10.03;//货币
    test.ly_multilinetext = "多行文本";//多行文本
    test.ly_optionset = 364750000;//选项集
    test.ly_singlelinetext = "单行文本";//单行文本
    req.send(JSON.stringify(test));
}

 

如果创建成功，提示如下：

 

  

如果创建失败，也是能获取到相关错误信息的： 

 

特别说明下如何为查找字段赋值，因为这个当时也困扰了我一阵子。最好到 Browse the metadata for your organization 下载并安装Metadata Browser这个解决方案，查看这个实体的元数据，找到这个字段对应的N:1关系的 ReferencingEntityNavigationPropertyName 这个值作为 @data.bind 的前面部分即可。一般这个值是这个字段的架构名称。

 

 

 

 

对应日期字段，请用 "YYYY-MM-DD"这种格式的文本，对于日期时间字段，请用  "YYYY-MM-DDTHH:MI:SSZ" 这种格式文本。

注意，对于可能包括小数的字段，比如十进制数，货币等，如果你赋予整数的话，比如赋予100，会导致出错。错误信息通常是：Incorrect attribute value type System.Int32 . 或者 The property provided was of type System.Int32, when the expected was of type System.Decimal 。我这里提供的解决办法很很简单，就是设置的值加上 0.00001 ，这个对你要设置的值大小没有影响，我查过数据库，但是又能让系统认为你传递过去的数据是正确的类型。示例是：{ "value": 200 + 0.00001 } 。

从Dynamics 365 V9版本开始提供了新的客户端API来方便编程，具体请参考官方文档 createRecord (Client API reference) 。

 

更多信息请参考官方文档：Create an entity record using the Web API 。