次の方法で共有

クイック スタート: クライアント側 JavaScript と Visual Studio Code を使用した Web API

このクイック スタートでは、Dataverse に接続し、次のテクノロジで Web API を使用する方法について説明します。

テクノロジー Description
JavaScript 対話型コンテンツを有効にする Web 開発用のプログラミング言語。 クライアント側スクリプト用のブラウザーで実行され、Node.jsでサーバー側で使用できます。
Visual Studio Code デバッグ、構文の強調表示、プラグインのサポートを備えた軽量のオープン ソース コード エディター。
シングル ページ アプリケーション (SPA) 1 つの HTML ページを読み込み、ユーザーがアプリを操作するにつれてコンテンツを動的に更新する Web アプリケーション。 この方法では、ページの再読み込みを減らし、パフォーマンスを向上させることで、よりスムーズで高速なユーザー エクスペリエンスが提供されます。
JavaScript 用 Microsoft 認証ライブラリ (MSAL.js) Microsoft ID プラットフォームを使用した Web アプリケーションの認証と承認を有効にするライブラリ。 これにより、保護されたリソースにアクセスするためのセキュリティで保護されたサインインとトークンの取得の統合が簡略化されます。
クロスオリジン リソース共有 (CORS) CORS が有効になっているため、SPA アプリケーションは Dataverse Web API でクライアント側の JavaScript を使用できます。 CORS は、Web ブラウザーのセキュリティ機能であり、別の配信元から Web サーバー上のリソースへのアクセスを制御できます。 これにより、Web アプリケーションは 同じ配信元ポリシーをバイパスでき、異なるドメイン間での安全で安全なデータ共有が容易になります。

目標

このクイック スタートでは、最小限の手順で SPA クライアント アプリケーションを使用して、JavaScript を使用して Dataverse Web API に接続することに重点を置いています。 このクイック スタートを完了すると、次のことが可能になります。

  • サインインして Dataverse に接続する
  • WhoAmI 関数を呼び出し、UserID値を表示します。

クイック スタートの実行が完了しました

このクイックスタートを完了すると、より高度な機能を示す Web API データ操作サンプル (クライアント側 JavaScript) を試すことができます。

注

このクイック スタートは、次のクライアント側 JavaScript シナリオには適用されません。

Scenario 詳細情報
モデル駆動型アプリケーション スクリプト - JavaScript を使用したモデル駆動型アプリでクライアント スクリプトを使用してビジネス ロジックを適用する
- Xrm.WebApi (クライアント API リファレンス)
Power Apps component framework - コード コンポーネント WebAPI
- Web API コンポーネントの実装
Power Pages ポータル Power Pages ポータル Web API

これらのシナリオでは、このクイックスタートに示すように、それぞれのアプリケーションの種類によって、JavaScript ネイティブ Fetch API を直接使用するのではなく、要求を送信する機能が提供されます。 モデル駆動型アプリ内のクライアント側スクリプトは、認証されたアプリケーションのコンテキストで実行されるため、各要求にはアクセス トークンは必要ありません。

[前提条件]

次の表では、このクイック スタートと Web API データ操作サンプル (クライアント側 JavaScript) を完了するために必要な前提条件について説明します。

前提条件 Description
Entra アプリの登録を作成するための特権 Microsoft Entra アプリの登録を作成して有効にしないと、このクイック スタートを完了できません。

可能かどうかわからない場合は、 SPA アプリケーションを登録 して調べる最初の手順を試してください。
Visual Studio Code Visual Studio Code がコンピューターにインストールされていない場合は、Visual Studio Code をダウンロードしてインストール して、このクイック スタートを実行する必要があります。
Node.js Node.js は、サーバー側で JavaScript を実行できるランタイム環境です。 このクイック スタートでは、Node.js ランタイムではなく、ブラウザーでクライアント側で JavaScript を実行する SPA アプリケーションを作成します。 ただし、 Node Package Manager (npm) は Node.jsと共にインストールされ、Parcel と MSAL.js ライブラリをインストールするには npm が必要です。
パーセル 最新の Web アプリケーションは、通常、npm とスクリプトを使用して配布されるオープン ソース ライブラリに多くの依存関係があり、ビルド プロセス中に管理および最適化する必要があります。 これらのツールは "bundlers" と呼ばれます。 最も一般的なものは webpack です。 このクイック スタートでは 、簡単 なエクスペリエンスを提供するため、パーセルを使用します。

さまざまなフレームワークとバンドルを使用する SPA アプリケーションを示すクイック スタートとサンプルについては、 Microsoft Entra シングルページ アプリケーションのサンプルを参照してください。 このクイック スタートに示す情報を使用して、これらのサンプルを Dataverse Web API を使用するように調整できます。
Web テクノロジ このクイック スタートのしくみを理解するには、HTML、JavaScript、CSS に関する知識が必要です。 JavaScript を使用して ネットワーク要求を行う方法を 理解することは不可欠です。

SPA アプリケーションを登録する

最初に、アプリを登録できない場合は、このクイック スタートを完了できないためです。

次のいずれかの特権を 持つ Microsoft Entra ロール には、必要なアクセス許可が含まれます。

アプリケーションを構成するときは、アプリケーション (クライアント) ID と Microsoft Entra テナントの ID が必要です。 また、アプリケーションが何のために作成されたかをユーザーが把握できるように、アプリケーションのわかりやすい名前を選択する必要があります。

アプリの登録

アプリケーションは、次のいずれかを使用して登録できます。

  • Microsoft Entra Web アプリケーション UI
  • Azure PowerShell New-AzADApplication コマンドレット。

アプリケーション登録を作成する

  1. Microsoft Entra 管理センターにサインインします。

  2. 複数のテナントにアクセスできる場合は、上部のメニューの [設定 ] アイコンを使用して、[ ディレクトリとサブスクリプション ] メニューからアプリケーションを登録するテナントに切り替えます。

  3. Identity>Applications>App registrations に移動し、[新しい登録] を選択します。

  4. など、アプリケーションの名前を入力Dataverse Web API Quickstart SPA。

  5. [サポートされているアカウントの種類] の [このアプリケーションを使用できるユーザーまたはこの API にアクセスできるユーザー] で、この組織のディレクトリ内のアカウントのみを選択します (<テナント名> - シングル テナント)。

  6. リダイレクト URI の場合 (省略可能)

    1. [ プラットフォームの選択] で、[ シングルページ アプリケーション (SPA)] を選択します。
    2. 値として「 http://localhost:1234 」と入力します。

  7. [ 登録] を選択して変更を保存します。

  8. 作成したアプリ登録のウィンドウの [ 概要 ] タブの [ 要点] の下に、次の値があります。

    • アプリケーション (クライアント) ID
    • ディレクトリ (テナント) ID

  9. 環境変数を使用する .env ファイルを作成 するときに必要になるため、これらの値をコピーします。

Dataverse user_impersonation 特権を追加する

  1. [ 管理 ] 領域で、[ API のアクセス許可] を選択します。
  2. [アクセス許可の追加] を選択します。
  3. [ API のアクセス許可の要求 ] ポップアップで、 組織が使用する API タブを選択します。
  4. 「Dataverse」と入力して、アプリケーション (クライアント) ID 00000007-0000-0000-c000-000000000000を検索します。
  5. Dataverse アプリケーションを選択します。
  6. [ アクセス許可の選択] では、 user_impersonation のみが使用可能な委任されたアクセス許可です。 それを選択します。
  7. アクセス許可の追加 を選択します。

注

会社のアプリ登録を作成する権限がない場合は、 Power Apps 開発者プランを使用して独自のテナントを取得します。

Node.js のインストール

  1. ダウンロード Node.jsに移動します。

  2. オペレーティング システム (Windows、macOS、または Linux) に適したインストーラーを選択し、ダウンロードします。

  3. インストーラーを実行します。 既定のオプションを受け入れることを確認します。 npm をインストールします。これは、Node.jsに推奨されるパッケージ マネージャーです。

  4. ターミナルまたはコマンド プロンプトを開き、次のコマンドを入力して Enter キーを押して、インストールを確認します。

    • node -v
    • npm -v

    次のような内容が表示されます。

    PS C:\Users\you> node -v
v22.14.0
PS C:\Users\you> npm -v
9.5.0
PS C:\Users\you>

プロジェクトを作成する

注

これらの手順は、 PowerApps-Samples リポジトリを複製またはダウンロードすることでスキップできます。 これらの手順の完成したアプリケーションは 、/dataverse/webapi/JS/quickspa で入手できます。 README の指示に従います。

このセクションの手順では、npm から依存関係をインストールし、フォルダー構造を作成し、Visual Studio Code を開く方法について説明します。

  1. プロジェクトを作成する場所にターミナル ウィンドウを開きます。 これらの手順では、 C:\projectsを使用します。

  2. 次のコマンドを入力し、 Enter キー を押して次のアクションを実行します。

    Command 目的
    mkdir quickspa quickspa という名前の新しいフォルダーを作成します。
    cd quickspa 新しい quickspa フォルダーに移動します。
    npm install --save-dev parcel パーセルをインストールし、プロジェクトを初期化します。
    npm install @azure/msal-browser MSAL.js ライブラリをインストールします。
    npm install dotenv dotenv をインストールして、機密性の高い構成データを格納する環境変数にアクセスします。
    mkdir src 次の手順でアプリの HTML、JS、CSS ファイルを追加する src フォルダーを作成します。
    code . quickspa フォルダーのコンテキストで Visual Studio Code を開きます。

Visual Studio Code Explorer では、プロジェクトは次のようになります。

ファイルが追加される前に、新しく作成された quickspa プロジェクトを表示します。

.env ファイルを作成する

コードとは別の環境に構成データを格納することは、セキュリティのベスト プラクティスです。

  1. .env フォルダーのルートに quickspa という名前の新しいファイルを作成します。

  2. [ アプリの登録 ] の値を貼り付けて、以下の CLIENT_ID と TENANT_ID の値を置き換えます。

    # The environment this application will connect to.
BASE_URL=https://<yourorg>.api.crm.dynamics.com
# The registered Entra application id
CLIENT_ID=11112222-bbbb-3333-cccc-4444dddd5555
# The Entra tenant id
TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
# The SPA redirect URI included in the Entra application registration
REDIRECT_URI=http://localhost:1234

  3. BASE_URL値を、接続先の環境の Web API URL の URL に設定します。

注

あなたは.env ファイルをチェックインしません。 [ファイルの作成] で、そのファイルを除外します。 ただし、プレースホルダー値を使用して .env.example ファイルを作成し、含める必要があるデータをユーザーに知らせる必要がある場合があります。

HTML ページを作成する

このセクションの手順では、SPA アプリケーションのユーザー インターフェイスを提供する HTML ファイルを作成する方法について説明します。

  1. srcという名前のindex.html フォルダーに新しいファイルを作成します。

  2. このコンテンツをコピーして index.html ページに貼り付けます。

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Dataverse Web API JavaScript Quick Start</title>
    <link rel="stylesheet" href="styles/style.css" />
  </head>
  <body>
    <header>
      <h1>Dataverse Web API JavaScript Quick Start</h1>
      <button id="loginButton">Login</button>
      <button id="logoutButton" class="hidden">Logout</button>
    </header>
    <nav id="buttonContainer" class="disabled">
      <button id="whoAmIButton">WhoAmI</button>
    </nav>
    <main id="container"></main>
    <script type="module" src="scripts/index.js"></script>
  </body>
</html>

この HTML には、次の要素が用意されています。

要素 ID 要素タイプ Description
loginButton ボタン ログイン ダイアログを開くには
logoutButton ボタン ログアウト ダイアログを開くには 既定では非表示です。
buttonContainer nav ユーザーがログインして使用する必要があるボタンが含まれています。 既定で無効です。
whoAmIButton ボタン WhoAmI 関数を実行して、ユーザーの ID を表示します。
container メイン ユーザーに情報を表示できる領域。
スクリプト ページの残りの要素が読み込まれた後、 index.js ファイルを読み込みます。

JavaScript スクリプトを作成する

このファイルには、 index.html ページを動的にするすべてのロジックが含まれています。

  1. srcという名前のscripts フォルダーに新しいフォルダーを作成します。

  2. scriptsという名前index.jsフォルダーに新しいファイルを作成します。

  3. このコンテンツをコピーして index.js ページに貼り付けます。

    import { PublicClientApplication } from "@azure/msal-browser";
import 'dotenv/config'

// Load the environment variables from the .env file
const config = {
   baseUrl: process.env.BASE_URL,
   clientId: process.env.CLIENT_ID,
   tenantId: process.env.TENANT_ID,
   redirectUri: process.env.REDIRECT_URI,
};

// Microsoft Authentication Library (MSAL) configuration
const msalConfig = {
  auth: {
    clientId: config.clientId,
    authority: "https://login.microsoftonline.com/" + config.tenantId,
    redirectUri: config.redirectUri,
    postLogoutRedirectUri: config.redirectUri,
  },
  cache: {
    cacheLocation: "sessionStorage", // This configures where your cache will be stored
    storeAuthStateInCookie: true,
  },
};

// Create an instance of MSAL
const msalInstance = new PublicClientApplication(msalConfig);

// body/main element where messages are displayed
const container = document.getElementById("container");

// Event handler for login button
async function logIn() {
  await msalInstance.initialize();

  if (!msalInstance.getActiveAccount()) {
    const request = {
      scopes: ["User.Read", config.baseUrl + "/user_impersonation"],
    };
    try {
      const response = await msalInstance.loginPopup(request);
      msalInstance.setActiveAccount(response.account);

      // Hide the loginButton so it won't get pressed twice
      document.getElementById("loginButton").style.display = "none";

      // Show the logoutButton
      const logoutButton = document.getElementById("logoutButton");
      logoutButton.innerHTML = "Logout " + response.account.name;
      logoutButton.style.display = "block";
      // Enable any buttons in the nav element
      document.getElementsByTagName("nav")[0].classList.remove("disabled");
    } catch (error) {
      let p = document.createElement("p");
      p.textContent = "Error logging in: " + error;
      p.className = "error";
      container.append(p);
    }
  } else {
    // Clear the active account and try again
    msalInstance.setActiveAccount(null);
    this.click();
  }
}

// Event handler for logout button
async function logOut() {
  const activeAccount = await msalInstance.getActiveAccount();
  const logoutRequest = {
    account: activeAccount,
    mainWindowRedirectUri: config.redirectUri,
  };

  try {
    await msalInstance.logoutPopup(logoutRequest);

    document.getElementById("loginButton").style.display = "block";

    this.innerHTML = "Logout ";
    this.style.display = "none";
    document.getElementsByTagName("nav")[0].classList.remove("disabled");
  } catch (error) {
    console.error("Error logging out: ", error);
  }
}

/**
 * Retrieves an access token using MSAL (Microsoft Authentication Library).
 * Set as the getToken function for the DataverseWebAPI client in the login function.
 *
 * @async
 * @function getToken
 * @returns {Promise<string>} The access token.
 * @throws {Error} If token acquisition fails and is not an interaction required error.
 */
async function getToken() {
  const request = {
    scopes: [config.baseUrl + "/.default"],
  };

  try {
    const response = await msalInstance.acquireTokenSilent(request);
    return response.accessToken;
  } catch (error) {
    if (error instanceof msal.InteractionRequiredAuthError) {
      const response = await msalInstance.acquireTokenPopup(request);
      return response.accessToken;
    } else {
      console.error(error);
      throw error;
    }
  }
}

// Add event listener to the login button
document.getElementById("loginButton").onclick = logIn;

// Add event listener to the logout button
document.getElementById("logoutButton").onclick = logOut;

/// Function to get the current user's information
/// using the WhoAmI function of the Dataverse Web API.
async function whoAmI() {
  const token = await getToken();
  const request = new Request(config.baseUrl + "/api/data/v9.2/WhoAmI", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      Accept: "application/json",
      "OData-Version": "4.0",
      "OData-MaxVersion": "4.0",
    },
  });
  // Send the request to the API
  const response = await fetch(request);
  // Handle the response
  if (!response.ok) {
    throw new Error("Network response was not ok: " + response.statusText);
  }
  // Successfully received response
  return await response.json();
}

// Add event listener to the whoAmI button
document.getElementById("whoAmIButton").onclick = async function () {
  // Clear any previous messages
  container.replaceChildren();
  try {
    const response = await whoAmI();
    let p1 = document.createElement("p");
    p1.textContent =
      "Congratulations! You connected to Dataverse using the Web API.";
    container.append(p1);
    let p2 = document.createElement("p");
    p2.textContent = "User ID: " + response.UserId;
    container.append(p2);
  } catch (error) {
    let p = document.createElement("p");
    p.textContent = "Error fetching user info: " + error;
    p.className = "error";
    container.append(p);
  }
};

index.js スクリプトには、次の定数と関数が含まれています。

Item Description
config Microsoft 認証ライブラリ (MSAL) 構成で使用されるデータを格納します。
msalConfig Microsoft Authentication Library (MSAL) の構成。
msalInstance MSAL PublicClientApplication インスタンス。
container メッセージが表示される要素。
getToken MSAL を使用してアクセス トークンを取得します。
logIn ログイン ボタンのイベント リスナー関数。 [アカウントの選択] ダイアログを開きます。
logOut ログアウト ボタンのイベント リスナー関数。 [アカウントの選択] ダイアログを開きます。
whoAmI Dataverse からデータを取得するために WhoAmI 関数 を呼び出す非同期関数。
whoAmIButton イベントリスナー whoAmI関数を呼び出し、UI の変更を管理してメッセージを表示する関数。

CSS ページを作成する

カスケード スタイル シート (CSS) ファイルは、HTML ページをより魅力的にし、コントロールが無効または非表示になるタイミングを制御する役割を持ちます。

  1. styles フォルダーに src という名前の新しいフォルダーを作成します。

  2. style.css フォルダーに styles という名前の新しいファイルを作成します。

  3. 次のテキストをコピーして、 style.css ファイルに貼り付けます。

    .disabled {
   pointer-events: none;
   opacity: 0.5;
   /* Optional: to visually indicate the element is disabled */
}

.hidden {
   display: none;
}

.error {
   color: red;
}

.expectedError {
   color: green;
}

body {
   font-family: 'Roboto', sans-serif;
   font-size: 16px;
   line-height: 1.6;
   color: #333;
   background-color: #f9f9f9;
}

h1,
h2,
h3 {
   color: #2c3e50;
}

button {
   background-color: #3498db;
   color: #fff;
   border: none;
   padding: 10px 20px;
   border-radius: 5px;
   box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
   transition: background-color 0.3s ease;
   margin: 5px;
   /* Adjust the value as needed */
}

button:hover {
   background-color: #2980b9;
}

header {
   padding-bottom: 10px;
   /* Adjust the value as needed */
}

.gitignore ファイルを作成する

アプリがソース管理でチェックインされると、 .gitignore ファイルを追加すると、指定したファイルとフォルダーのファイルをチェックインできなくなります。

  1. .gitignore という名前でファイルを作成します。

  2. 次の内容を追加します。

    .parcel-cache
dist
node_modules
.env

アプリを初めて実行すると、 .parcel-cache フォルダーと dist フォルダーが表示されます。

.env ファイルをチェックインしないのは、セキュリティのベスト プラクティスです。 プレースホルダー値を持つプレースホルダー.env.sampleファイルをチェックインしてみても良いかもしれません。

Visual Studio Code Explorer では、プロジェクトは次のようになります。

ファイルが追加された後の quickspa プロジェクトを表示します。

package.json ファイルを構成する

package.json ファイルは次のようになります。

{
  "devDependencies": {
    "parcel": "^2.14.1",
  },
  "dependencies": {
    "@azure/msal-browser": "^4.7.0",
    "dotenv": "^16.4.7"
  }
}

scriptsの下に次のdependencies項目を追加します。

  "dependencies": {
    "@azure/msal-browser": "^4.7.0",
    "dotenv": "^16.4.7"
  },
  "scripts": {
    "start": "parcel src/index.html"
  }

この構成では、次の手順で npm start を使用してアプリケーションを開始できます。

使ってみる

  1. Visual Studio Code でターミナル ウィンドウを開く

  2. npm start と入力し、Enter キーを押します。

    注

    プロジェクトが初めて初期化されている間に、ターミナルに書き込まれた出力が表示される場合があります。 これは、 dotenv を使用するときの問題を軽減するために、いくつかのノード モジュールをインストールするパーセルです。 package.jsonを見ると、いくつかの新しい項目がdevDependenciesに追加されます。

    ターミナルへの出力は次のようになります。

    Server running at http://localhost:1234
Built in 1.08s

  3. Ctrl キーを押しながら http://localhost:1234 リンクをクリックしてブラウザーを開きます。

  4. ブラウザーで、[ ログイン ] ボタンを選択します。

    [ アカウントへのサインイン ] ダイアログが開きます。

  5. [ アカウントへのサインイン ] ダイアログで、Dataverse にアクセスできるアカウントを選択します。

    新しいアプリケーション (クライアント) ID 値を使用して初めてアクセスすると、次の アクセス許可が要求されたダイアログが 表示されます。

    [アクセス許可が要求されました] ダイアログ

  6. [要求されたアクセス許可] ダイアログで [同意する] を選択します。

  7. [WhoAmI] ボタンを選択します。

    メッセージはおめでとうございます。Web API を使用して Dataverse に接続しました。は、UserIdの値と共に表示されます。

トラブルシューティング

このセクションには、このクイック スタートの実行で発生する可能性があるエラーが含まれています。

注

このクイック スタートの手順を完了するときに問題が発生した場合は、 PowerApps-Samples リポジトリの複製またはダウンロードを試してください。 これらの手順の完成したアプリケーションは 、/dataverse/webapi/JS/quickspa で入手できます。 README の指示に従います。 それでも問題が解決しない場合は、この quickspa サンプル アプリケーションを参照する GitHub の問題を作成します。

選択したユーザー アカウントがテナントに存在しない

選択したアカウントが登録済みアプリケーションと同じ Microsoft Entra テナントに属していない場合は、[ アカウントの選択 ] ダイアログで次のエラーが表示されます。

Selected user account does not exist in tenant '{Your tenant name}' and cannot access the application '{Your application ID}' in that tenant. The account needs to be added as an external user in the tenant first. Please use a different account.

解決策: 正しいユーザーを選択してください。

次のステップ

クライアント側 JavaScript を使用する他のサンプルをお試しください。

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

サービス ドキュメントを理解して、Dataverse Web API 機能の詳細を確認します。

Web API の種類と操作

  • Last updated on