求Microsoft 365 Dataverse API前端JavaScript实现CRUD详细教程

前置准备 #

• 身份验证：前端需通过Azure AD获取有效访问令牌，推荐用MSAL.js库处理登录、令牌刷新等流程，Dataverse仅接受合法的Azure AD令牌鉴权
• 基础认知：Dataverse Web API的端点格式为https://<你的环境域名>/api/data/v9.2/，实体请求需使用复数名称（如accounts而非account）

核心操作示例（客户端JavaScript） #

查询数据 #

通过GET请求结合OData参数筛选、返回指定字段：

// 假设已通过MSAL获取到accessToken
const accessToken = "你的访问令牌";
const environmentUrl = "https://你的环境域名.crm.dynamics.com";

async function fetchAccounts() {
  try {
    const response = await fetch(`${environmentUrl}/api/data/v9.2/accounts?$select=name,accountid&$top=5&$filter=contains(name,'测试')`, {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "OData-MaxVersion": "4.0",
        "OData-Version": "4.0",
        "Accept": "application/json",
        "Content-Type": "application/json; charset=utf-8"
      }
    });

    if (!response.ok) {
      throw new Error(`请求失败: ${response.statusText}`);
    }

    const data = await response.json();
    console.log("查询到的账户数据:", data.value);
  } catch (error) {
    console.error("查询出错:", error);
  }
}

// 调用查询函数
fetchAccounts();

说明：$select指定返回字段，$top限制结果数量，$filter添加筛选条件，还可使用$orderby排序、$expand关联查询关联实体

创建数据 #

通过POST请求提交JSON格式的实体数据：

async function createAccount() {
  const newAccount = {
    "name": "新测试公司",
    "telephone1": "1234567890",
    "industrycode": 1 // 行业代码，对应Dataverse选项集值
  };

  try {
    const response = await fetch(`${environmentUrl}/api/data/v9.2/accounts`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "OData-MaxVersion": "4.0",
        "OData-Version": "4.0",
        "Accept": "application/json",
        "Content-Type": "application/json; charset=utf-8"
      },
      body: JSON.stringify(newAccount)
    });

    if (!response.ok) {
      throw new Error(`创建失败: ${response.statusText}`);
    }

    // 从响应头获取新建实体的ID
    const entityId = response.headers.get("OData-EntityId").split("(")[1].split(")")[0];
    console.log("新建账户ID:", entityId);
  } catch (error) {
    console.error("创建出错:", error);
  }
}

createAccount();

更新数据 #

通过PATCH请求修改指定实体，结合ETag做并发控制：

async function updateAccount(accountId) {
  const updatedData = {
    "name": "更新后的公司名称",
    "telephone1": "0987654321"
  };

  try {
    // 先获取实体的ETag（用于并发校验）
    const getResponse = await fetch(`${environmentUrl}/api/data/v9.2/accounts(${accountId})`, {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Accept": "application/json"
      }
    });
    const etag = getResponse.headers.get("ETag");

    const updateResponse = await fetch(`${environmentUrl}/api/data/v9.2/accounts(${accountId})`, {
      method: "PATCH",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "OData-MaxVersion": "4.0",
        "OData-Version": "4.0",
        "Accept": "application/json",
        "Content-Type": "application/json; charset=utf-8",
        "If-Match": etag // 确保更新的是最新版本，避免冲突
      },
      body: JSON.stringify(updatedData)
    });

    if (!updateResponse.ok) {
      throw new Error(`更新失败: ${updateResponse.statusText}`);
    }

    console.log("账户更新成功");
  } catch (error) {
    console.error("更新出错:", error);
  }
}

// 传入要更新的账户ID
updateAccount("00000000-0000-0000-0000-000000000001");

删除数据 #

通过DELETE请求删除指定实体，同样可结合ETag控制并发：

async function deleteAccount(accountId) {
  try {
    // 获取实体ETag
    const getResponse = await fetch(`${environmentUrl}/api/data/v9.2/accounts(${accountId})`, {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Accept": "application/json"
      }
    });
    const etag = getResponse.headers.get("ETag");

    const deleteResponse = await fetch(`${environmentUrl}/api/data/v9.2/accounts(${accountId})`, {
      method: "DELETE",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "If-Match": etag
      }
    });

    if (!deleteResponse.ok) {
      throw new Error(`删除失败: ${deleteResponse.statusText}`);
    }

    console.log("账户删除成功");
  } catch (error) {
    console.error("删除出错:", error);
  }
}

deleteAccount("00000000-0000-0000-0000-000000000001");

关键注意事项 #

• 令牌管理：MSAL.js会自动处理令牌过期刷新，避免手动维护令牌有效期
• 跨域配置：如果前端部署在Dataverse环境外，需在Dataverse后台配置允许的跨域源（CORS）
• 权限控制：确保令牌对应的Azure AD用户拥有Dataverse实体的操作权限（如读取、创建、写入）
• 错误处理：针对常见HTTP错误码做对应处理，比如401代表令牌过期需重新登录，403代表权限不足，404代表实体不存在

内容的提问来源于stack exchange，提问作者Gekyo