如何从SharePoint Online webpart连接Dataverse REST API

配置流程与可复用代码 #

• 依赖安装：在SPFx项目根目录执行命令安装必要依赖，注意版本要和当前项目使用的SPFx基础包版本对齐，避免依赖冲突：
  npm install @microsoft/sp-http @azure/msal-browser@2.38.0
• 权限配置：打开项目下config/package-solution.json文件，在solution节点下添加webApiPermissionRequests配置：

"webApiPermissionRequests": [
  {
    "resource": "Microsoft Dataverse",
    "scope": "user_impersonation"
  }
]

打包生成sppkg文件上传到SharePoint应用目录后，必须进入SharePoint管理中心的「API访问」页面，审批刚提交的Dataverse权限申请，未审批的情况下所有接口请求都会返回403。

• 鉴权代码实现：
  • SPFx 1.17及以上版本直接用内置的AadTokenProvider获取token，无需手动初始化鉴权客户端，内置方法已经处理了token缓存、多账号兼容逻辑：

  // 在web part类的方法中调用
  const tokenProvider = await this.context.aadTokenProviderFactory.getTokenProvider();
  // 替换为你自己的Dataverse实例地址
  const dataverseDomain = "https://[你的组织名].crm.dynamics.com";
  const accessToken = await tokenProvider.getToken(dataverseDomain);
  
  // 调用Dataverse Web API示例
  const resp = await fetch(`${dataverseDomain}/api/data/v9.2/accounts?$select=name,accountid`, {
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "OData-MaxVersion": "4.0",
      "OData-Version": "4.0",
      "Accept": "application/json",
      "Content-Type": "application/json"
    }
  });
  const data = await resp.json();
  

  • SPFx 1.16及以下版本需要手动初始化MSAL实例完成鉴权，不推荐使用已停服的ADAL库。

实操避坑要点 #

• 不要申请超出业务需要的高权限，比如直接申请Organization.ReadWrite.All这类全组织权限，不仅大概率会被管理员审批驳回，还会带来数据安全风险，按照业务需要申请对应表的最小粒度权限即可。
• 本地调试时必须使用HTTPS模式，启动命令用gulp serve --https，同时要把本地调试地址https://localhost:4321/temp/workbench.html添加到Azure AD中对应SPFx应用注册的重定向URI列表里，否则会触发鉴权回调失败、跨域拦截问题。
• 所有Dataverse Web API请求必须携带OData-MaxVersion、OData-Version请求头，否则会返回400错误或者非标准格式响应，导致前端解析失败。
• Safari、Firefox等默认开启第三方cookie拦截的浏览器下，不要用自定义的MSAL配置做静默鉴权，优先用SPFx内置的AadTokenProvider，已经做了第三方cookie场景的兼容，能减少80%的偶发登录失败问题。
• Dataverse原生支持SharePoint域名的跨域请求，不需要额外配置CORS规则，手动添加CORS相关请求头反而会触发OPTIONS预检请求失败。
• 不要硬编码Dataverse实例地址、租户ID这类配置，可以从this.context.pageContext里拿租户ID，实例地址可以存在web part的属性配置里，方便后续环境迁移。

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