Web API データ操作のサンプル (クライアント側の JavaScript)

[アーティクル]
02/23/2023

この記事では、クライアント側の JavaScript を使用した WebAPI サンプルに関する一般的な理解を提供します。各サンプルは、Microsoft Dataverse Web API のさまざまな部分に注目しますが、それらはすべて、このトピックで説明されている類似したプロセスと構造をフォローします。

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

次のサンプルは、ここで説明されるパターンを使用します:

サンプル	サンプルグループ	説明
Web API 基本操作のサンプル (クライアント側の JavaScript)	Web API Operations 操作のサンプル	Dataverse テーブル行 (エンティティレコード) の作成、取得、更新、削除、関連付け、および関連付け解除の各操作を実行する方法を説明します。
Web API クエリデータのサンプル (クライアント側の JavaScript)	Web API クエリデータのサンプル	OData v4 クエリ構文と機能および Dataverse クエリ機能を使用する方法を説明します。定義済みクエリに関する作業、および FetchXML を使用したクエリの実行のデモンストレーションが含まれます。
Web API 条件付き演算のサンプル (クライアント側の JavaScript)	Web API 条件付き演算サンプル	条件付きの操作の実行方法を示します。これらの操作の動作は、指定した条件によって異なります。
Web API 機能およびアクションのサンプル (クライアント側 JavaScript)	Web API 機能およびアクションのサンプル	ユーザー定義アクションを含む、バインドされた関数とバインドされていない関数およびアクションの使用方法を説明します。

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

各サンプルのソース・コードは GitHub で入手可能です。各サンプルをダウンロードするリンクが、そのサンプルの各ページに含まれています。

サンプルをダウンロードした後で、圧縮されたファイルを解凍します。プロジェクトが空の ASP.NET web アプリケーションプロジェクトであるため、C#フォルダ内の各サンプルのソリューションを見つけます。 Dataverse ソリューションは、インポートして実行できるようにダウンロード形式でも提供されます。

注意

Dataverse のクライアントサイド JavaScript を開発するには、Visual Studio も ASP.NET も必要ありません。ただし、Visual Studio は JavaScript の記述に関して向上したエクスペリエンスを提供します。

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

それぞれのプロジェクトの中に、Dataverse 管理ソリューションのファイルがあります。このファイルの名前は、サンプルのプロジェクト名によって異なりますが、ファイル名は _managed.zip で終わります。

Dataverse ソリューションを Dataverse サーバーにインポートするには、次の手順を実行してください。

ダウンロードした ZIP ファイルの中身を解凍して、Dataverse ソリューションファイルを見つけます。このファイルも ZIP 形式のファイルです。たとえば Basic Operations サンプルをダウンロードした場合は、WebAPIBasicOperations\WebAPIBasicOperations_1_0_0_0_managed.zip という名前の Dataverse ソリューション ZIP ファイルを見つけます。
Dataverse UI で、設定 > ソリューション に移動します。このページには、Dataverse サーバーのソリューションの一覧が表示されます。このソリューションのインポートを完了した後、そのサンプルのソリューション名が一覧に表示されます (例: Web API の基本操作)。
インポートを選択し、インポートダイアログの指示に従ってこの操作を完了します。

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

サンプルプログラムは、Dataverse 内から Web リソースとして実行します。インポートされたソリューションには、サンプルデータを使用するか、または削除するかを選択できるオプションがある構成ページがあります。またサンプルプログラムを開始するためのボタンもあります。

サンプルを実行するには、次の手順を実行します。

Dataverse の すべてのソリューション ページから、ソリューション名を選択します (例:Web API の基本操作 リンク)。これにより、新しいウィンドウのソリューションのプロパティが開きます。
左側のナビゲーションウィンドウから構成を選択します。
サンプルの開始ボタンを選択し、サンプルコードを実行します。

各サンプルの共通要素

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

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

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 のサンプル

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

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

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

各サンプルの共通要素

関連項目

フィードバック

その他のリソース

Web API データ操作のサンプル (クライアント側の JavaScript)

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

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

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

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

各サンプルの共通要素

関連項目

フィードバック

その他のリソース

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