Web API 範例 (用戶端 JavaScript)

發行項
03/03/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 查詢資料範例	示範如何使用 OData v4 查詢語法和函數，以及 Microsoft Dynamics 365 查詢函數。包含使用預先定義的查詢和使用 FetchXML 執行查詢的示範。
Web API 條件式作業範例 (用戶端 JavaScript)	Web API 條件式作業範例	示範如何執行條件式作業。這些作業的行為取決於您指定的準則。
Web API 函數和動作範例 (用戶端 JavaScript)	Web API 函數和動作範例	示範如何使用已繫結和未繫結的函數及動作，包括自訂動作。

如何下載範例的原始程式碼。

每個範例的原始程式碼都可在 MSDN Code Gallery 取得。下載每個範例的連結包含在該範例的個別頁面中。

下載範例之後，將檔案解壓縮。在 C# 資料夾中尋找每個範例的 Visual Studio 2015 解決方案，因為專案是空的 ASP.NET Web 應用程式專案。Dynamics 365 解決方案也包含在下載中，您可以匯入或執行。

注意

開發適用於 Dynamics 365 的用戶端 JavaScript 不需要 Microsoft Visual Studio 和 ASP.NET，不過 MSDN Code Gallery 網站要求將檔案包含在 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 Basics Operations)。
按一下 [匯入]，並遵循匯入對話方塊的指示完成此動作。

如何執行範例以查看指令碼的實際運作

範例程式會在 Dynamics 365 內做為 Web 資源執行。匯入的解決方案會提供設定頁面，讓您選擇保留或刪除範例資料，以及一個按鈕來啟動範例程式。若是 Basic Operations 範例，此介面看起來像這樣。

Dynamics 365 Web API Sample Configuration page

若要執行範例，請執行以下操作：

從 Dynamics 365 中的 [所有解決方案] 頁面，按一下解決方案名稱 (例如：[Web API Basics Operations] 連結)。這樣會在新視窗中開啟解決方案的屬性。
從左邊導覽功能表中按一下 [設定]。
按一下 [啟動範例] 按鈕，執行範例程式碼。

每個範例中通用的元素

下列清單反白顯示每一個範例中常用的元素。

Sdk.startSample 函數會在使用者從 HTML 頁面按一下 [啟動範例] 按鈕時呼叫。Sdk.startSample 函數會初始化全域變數，並開始進行鏈結中的第一項作業。
程式輸出和錯誤訊息會傳送給瀏覽器的偵錯程式主控台。若要查看這些輸出，請先開啟視窗，再執行範例。按 F12 鍵存取開發人員工具，包括主控台視窗，在 Windows Internet Explorer 和 Microsoft Edge 瀏覽器中。
這些範例使用瀏覽器原生的 ES6-Promise 實作，針對支援它的現代化瀏覽器。若是 Internet Explorer 11，此範例使用 ES6-Promise polyfill，因為 Internet Explorer 11 是 Microsoft Dynamics 365 支援的唯一沒有此功能的原生支援的瀏覽器。

不需要 Promises。類似的互動可以使用回呼函數執行。如需詳細資訊，請參閱使用 Promise 建立可重複使用的函數。

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 函數會傳回 promise。當 promise 包裝的要求完成時，promise 就會解決或遭拒。如果解決，將會呼叫下列 then 方法中的函數。如果遭拒，將會呼叫下列 catch 方法中的函數。如果 then 方法本身內的函數傳回 promise，則連續 then 方法內的作業鏈結就能繼續。傳回 promise 可讓我們鏈結這些範例作業在一起，採用許多開發人員偏好的傳統回呼函數。如需 promise 的詳細資訊，請參閱 JavaScript Promise。

另請參閱

使用 Microsoft Dynamics 365 Web API
Web API 範例
 Web API 範例 (C#)
Web API 基本作業範例 (用戶端 JavaScript)
Web API 查詢資料範例 (用戶端 JavaScript)
Web API 條件式作業範例
 Web API 函數和動作範例 (用戶端 JavaScript)

Microsoft Dynamics 365

Share via

Web API 範例 (用戶端 JavaScript)

本主題內容

使用用戶端 JavaScript 的 Web API 範例

如何下載範例的原始程式碼。

如何匯入包含範例的 Dynamics 365 解決方案。

如何執行範例以查看指令碼的實際運作

每個範例中通用的元素

另請參閱

其他資源