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 Operations 操作のサンプル	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 ソリューションは、インポートして実行できるようにダウンロード形式でも提供されます。

注意

Microsoft Visual Studio または ASP.NET のどちらも Dynamics 365 用にクライアントサイドの JavaScript を開発するために必要ではありませんが、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 の基本操作] リンク)。これにより、新しいウィンドウのソリューションのプロパティが開きます。
左側のナビゲーションメニューで [構成] をクリックします。
[サンプルの開始] ボタンをクリックしてサンプルコードを実行します。

各サンプルの共通要素

次の一覧は、これらのサンプルでの共通要素に注目しています。

Sdk.startSample 機能は、ユーザーが HTML ページの [サンプルの開始] ボタンをクリックすると呼ばれます。Sdk.startSample 関数はグローバル変数を初期化し、チェーン内の最初の操作を開始します。
プログラム出力およびエラーメッセージは、ブラウザーのデバッガーコンソールに送信されます。これらの出力を表示するには、サンプルを実行する前に、コンソールウィンドウを開きます。Windows Internet Explorer および Microsoft Edge のコンソールウィンドウを含む開発者ツールにアクセスするには [F12] を押します。
これらのサンプルは、モダンなブラウザーでサポートされている、ブラウザーにネイティブな ES6-Promise の実装を使用します。Internet Explorer 11 の場合、このサンプルは ES6-Promise polyfill を使用します。Internet Explorer 11 が Microsoft Dynamics 365 によりサポートされている唯一のブラウザーであり、この機能のネイティブサポートがないからです。

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」を参照してください。

Web API のサンプル (クライアント側の JavaScript)

このトピックの内容

クライアント側の JavaScript を使用する Web API のサンプル

サンプルのソースコードのダウンロード方法。

サンプルを含む Dynamics 365 のソリューションをインポートする方法。

サンプルを実行して実行中のスクリプトを確認する方法

各サンプルの共通要素

関連項目

その他のリソース

Web API のサンプル (クライアント側の JavaScript)

このトピックの内容

クライアント側の JavaScript を使用する Web API のサンプル

サンプルのソース コードのダウンロード方法。

サンプルを含む Dynamics 365 のソリューションをインポートする方法。

サンプルを実行して実行中のスクリプトを確認する方法

各サンプルの共通要素

関連項目

その他のリソース

サンプルのソースコードのダウンロード方法。