Web API 示例（客户端 JavaScript）

项目
03/04/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

此主题提供有关使用客户端 JavaScript 的 Web API 示例的常识。由于每个示例侧重 Microsoft Dynamics 365 Web API 的一个不同方面，所以它们全部采用本主题中介绍的流程和结构。

本主题内容

使用客户端 JavaScript 的 Web API 示例

如何下载示例的源代码。

如果导入包含示例的 Dynamics 365 解决方案。

如何运行示例以查看脚本的实际应用

各示例的公共元素

使用客户端 JavaScript 的 Web API 示例

以下示例使用此处介绍的模式：

示例	示例组	说明
Web API 基本操作示例（客户端 JavaScript）	Web API 基本操作示例	演示如何创建、检索、更新、删除、关联和解除关联 Dynamics 365 实体记录。
Web API 查询数据示例（客户端 JavaScript）	Web API 查询数据示例	演示如何使用查询语法 v4 OData 和函数以及 Microsoft Dynamics 365 和函数。包含处理预定义的查询和使用 FetchXml 执行查询的演示。
Web API 条件操作示例（客户端 JavaScript）	Web API 条件操作示例	演示如何执行条件操作。这些操作的行为取决于您指定的条件。
Web API 函数和操作示例（客户端 JavaScript）	Web API 函数和操作示例	演示如何使用绑定和取消绑定功能和操作，包括自定义操作。

如何下载示例的源代码。

MSDN 代码库中提供各示例的源代码。各示例的单个页面中包含相应示例的下载链接。

下载示例后，提取压缩的文件。在 C# 文件夹内查找各示例的 Visual Studio 2015 解决方案，因为该项目是一个空 ASP.NET Web 应用程序项目。下载中还提供了您可以导入和运行的 Dynamics 365 解决方案。

备注

为 Dynamics 365 开发客户端 JavaScript 既不需要 Microsoft Visual Studio，也不需要 ASP.NET，但是 MSDN 代码库站点要求文件作为容器包含在 Microsoft Visual Studio。但是，Microsoft Visual Studio 不太适合编写 JavaScript。

如果导入包含示例的 Dynamics 365 解决方案。

在每个项目中，可以找到一个 Microsoft Dynamics 365 托管解决方案文件。此文件的名称取决于示例的项目名称，但是文件名以 _managed.zip 结尾。

若要将 Dynamics 365 解决方案导入到您的 Dynamics 365 服务器中，请执行以下操作：

提取下载的 zip 文件的内容并找到 Dynamics 365 解决方案文件，这个文件也是 zip 文件。例如，如果下载了 Basic Operations 示例，请查找名称为 WebAPIBasicOperations\WebAPIBasicOperations_1_0_0_0_managed.zip 的 Dynamics 365 解决方案 zip 文件。
在 Dynamics 365 UI 中，转到“设置 > 解决方案”。此页列出您的 Dynamics 365 服务器上的所有解决方案。此解决方案导入完毕之后，将在此列表中显示该示例的解决方案名称（如：“Web API 基本操作”）。
单击“导入”，然后按照导入对话框中的说明完成此操作。

如何运行示例以查看脚本的实际应用

示例程序在 Dynamics 365 中作为 Web 资源运行。导入的解决方案提供一个配置页，该页中有一个选项供您选择保留还是删除示例数据，还有一个按钮用于启动示例程序。对于 Basic Operations 示例，此界面如下所示。

Dynamics 365 Web API Sample Configuration page

若要运行示例，请执行以下操作：

从 Dynamics 365 中“所有解决方案”页，单击解决方案名称（如：“Web API 基本操作”链接）。将在新窗口中打开该解决方案的属性。
在左导航菜单中，单击“配置”。
单击“启动示例”按钮执行示例代码。

各示例的公共元素

以下示例列表突出显示了这些示例中每一个内找到的一些普通元素。

用户单击 HTML 页面中的“启动示例”按钮时，将调用 Sdk.startSample 函数。Sdk.startSample 函数初始化全局变量并开始执行操作链中的第一个操作。
程序输出和错误消息发送到浏览器的调试器控制台。若要查看这些输出，请在运行示例之前先打开控制台窗口。按 F12 键在 Windows Internet Explorer 和 Microsoft Edge 浏览器中访问开发人员工具，包括控制台窗口。
这些示例将浏览器本机 ES6-Promise 实施使用支持该实施的现代浏览器。对于 Internet Explorer 11，此示例使用 ES6-Promise polyfill，因为 Internet Explorer 11 是不本机支持此功能的 Microsoft Dynamics 365 唯一支持的浏览器。

不需要承诺。可以使用回调函数执行类似交互。有关详细信息，请参阅使用承诺创建可重用的函数。

Sdk.request 函数根据作为参数传递的信息处理请求。根据各示例的需求，传递的参数可能有所不同。请参阅该示例的源代码了解更多详细信息。

/**
 * @function request
 * @description Generic helper function to handle basic XMLHttpRequest calls.
 * @param {string} action - The request action. String is case-sensitive.
 * @param {string} uri - An absolute or relative URI. Relative URI starts with a "/".
 * @param {object} data - An object representing an entity. Required for create and update actions.
 * @returns {Promise} - A Promise that returns either the request object or an error object.
 */
Sdk.request = function (action, uri, data) {
    if (!RegExp(action, "g").test("POST PATCH PUT GET DELETE")) { // Expected action verbs.
        throw new Error("Sdk.request: action parameter must be one of the following: " +
            "POST, PATCH, PUT, GET, or DELETE.");
    }
    if (!typeof uri === "string") {
        throw new Error("Sdk.request: uri parameter must be a string.");
    }
    if ((RegExp(action, "g").test("POST PATCH PUT")) && (data === null || data === undefined)) {
        throw new Error("Sdk.request: data parameter must not be null for operations that create or modify data.");
    }

    // Construct a fully qualified URI if a relative URI is passed in.
    if (uri.charAt(0) === "/") {
        uri = clientUrl + webAPIPath + uri;
    }

    return new Promise(function (resolve, reject) {
        var request = new XMLHttpRequest();
        request.open(action, encodeURI(uri), true);
        request.setRequestHeader("OData-MaxVersion", "4.0");
        request.setRequestHeader("OData-Version", "4.0");
        request.setRequestHeader("Accept", "application/json");
        request.setRequestHeader("Content-Type", "application/json; charset=utf-8");
        request.onreadystatechange = function () {
            if (this.readyState === 4) {
                request.onreadystatechange = null;
                switch (this.status) {
                    case 200: // Success with content returned in response body.
                    case 204: // Success with no content returned in response body.
                        resolve(this);
                        break;
                    default: // All other statuses are unexpected so are treated like errors.
                        var error;
                        try {
                            error = JSON.parse(request.response).error;
                        } catch (e) {
                            error = new Error("Unexpected Error");
                        }
                        reject(error);
                        break;
                }

            }
        };
        request.send(JSON.stringify(data));
    });
};

Sdk.request 函数返回一项承诺。完成该承诺包装的请求时，该承诺即已解决或拒绝。如果已解决，将调用下面的 then 方法中的函数。如果已拒绝，将调用下面的 catch 方法中的函数。如果 then 方法内的函数本身返回一项承诺，则连续的 then 方法内的操作链可以继续。返回承诺让我妈可以按照许多开发人员相比传统回调函数更偏爱的方式将这些示例操作链式组合起来。有关承诺的详细信息，请参阅 JavaScript 承诺。

另请参阅

使用 Microsoft Dynamics 365 Web API
Web API 示例
 Web API 示例 (C#)
Web API 基本操作示例（客户端 JavaScript）
Web API 查询数据示例（客户端 JavaScript）
Web API 条件操作示例
 Web API 函数和操作示例（客户端 JavaScript）

Microsoft Dynamics 365

通过

Web API 示例（客户端 JavaScript）

本主题内容

使用客户端 JavaScript 的 Web API 示例

如何下载示例的源代码。

如果导入包含示例的 Dynamics 365 解决方案。

如何运行示例以查看脚本的实际应用

各示例的公共元素

另请参阅

其他资源