如何使用NodeJs、Express、Typescript开发从Sharepoint获取文件的API？

一、核心依赖选择 #

• 官方Graph API客户端：@microsoft/microsoft-graph-client（原生支持TypeScript）
• Azure AD认证工具：@azure/msal-node（处理OAuth2凭证流）
• 基础开发依赖：express、typescript、@types/express、ts-node、nodemon

二、项目初始化步骤 #

1. 创建项目并初始化npm：

mkdir sp-file-api && cd sp-file-api
npm init -y

2. 安装依赖：

# 生产依赖
npm install express @microsoft/microsoft-graph-client @azure/msal-node dotenv
# 开发依赖
npm install -D typescript @types/express @types/node ts-node nodemon @microsoft/microsoft-graph-types

3. 配置tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

三、Azure AD应用配置（关键前置步骤） #

• 登录Azure门户，注册后台/服务器端应用
• 配置API权限：添加Microsoft Graph的应用权限，选择Files.Read.All或Sites.Read.All，并完成管理员同意
• 记录应用凭证：clientId、tenantId、clientSecret，后续代码中使用

四、核心代码实现 #

1. 认证模块（src/auth.ts） #

import { ConfidentialClientApplication } from '@azure/msal-node';

const config = {
  auth: {
    clientId: process.env.CLIENT_ID!,
    tenantId: process.env.TENANT_ID!,
    clientSecret: process.env.CLIENT_SECRET!
  }
};

const cca = new ConfidentialClientApplication(config);

export async function getAccessToken(): Promise<string> {
  const result = await cca.acquireTokenByClientCredential({
    scopes: ['https://graph.microsoft.com/.default']
  });
  return result.accessToken!;
}

2. Graph客户端初始化（src/graphClient.ts） #

import { Client } from '@microsoft/microsoft-graph-client';
import { getAccessToken } from './auth';

export async function getGraphClient(): Promise<Client> {
  const accessToken = await getAccessToken();
  return Client.init({
    authProvider: (done) => {
      done(null, accessToken);
    }
  });
}

3. Express API路由（src/routes/files.ts） #

import express from 'express';
import { getGraphClient } from '../graphClient';
import { DriveItem } from '@microsoft/microsoft-graph-types';

const router = express.Router();

// 获取指定文件夹下的PDF/Excel文件列表
router.get('/', async (req, res) => {
  try {
    const { siteId, driveId, folderPath } = req.query;
    if (!siteId || !driveId || !folderPath) {
      return res.status(400).json({ error: '缺少必填参数：siteId、driveId、folderPath' });
    }

    const client = await getGraphClient();
    // 筛选PDF和Excel格式文件
    const items = await client.api(`/sites/${siteId}/drives/${driveId}/root:${folderPath}:/children`)
      .filter('file/mimeType eq \'application/pdf\' or file/mimeType eq \'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\' or file/mimeType eq \'application/vnd.ms-excel\'')
      .select('id,name,webUrl,file')
      .get();

    res.json(items.value as DriveItem[]);
  } catch (error) {
    console.error('获取文件失败:', error);
    res.status(500).json({ error: '获取文件失败，请检查配置和参数' });
  }
});

// 下载指定文件
router.get('/download', async (req, res) => {
  try {
    const { siteId, driveId, fileId } = req.query;
    if (!siteId || !driveId || !fileId) {
      return res.status(400).json({ error: '缺少必填参数：siteId、driveId、fileId' });
    }

    const client = await getGraphClient();
    const fileStream = await client.api(`/sites/${siteId}/drives/${driveId}/items/${fileId}/content`)
      .getStream();

    res.setHeader('Content-Type', 'application/octet-stream');
    fileStream.pipe(res);
  } catch (error) {
    console.error('下载文件失败:', error);
    res.status(500).json({ error: '下载文件失败，请检查配置和参数' });
  }
});

export default router;

4. 主入口文件（src/index.ts） #

import express from 'express';
import dotenv from 'dotenv';
import filesRouter from './routes/files';

dotenv.config();
const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());
app.use('/api/sharepoint/files', filesRouter);

app.listen(PORT, () => {
  console.log(`服务器运行在http://localhost:${PORT}`);
});

五、运行与测试 #

1. 创建.env文件填入Azure凭证：

CLIENT_ID=你的应用clientId
TENANT_ID=你的租户ID
CLIENT_SECRET=你的应用clientSecret
PORT=3000

2. 配置启动脚本（package.json）：

"scripts": {
  "dev": "nodemon src/index.ts",
  "build": "tsc",
  "start": "node dist/index.js"
}

3. 启动开发服务器：npm run dev
4. 测试API：
   • 获取文件列表：GET http://localhost:3000/api/sharepoint/files?siteId=你的站点ID&driveId=文档库ID&folderPath=/目标文件夹路径
   • 下载文件：GET http://localhost:3000/api/sharepoint/files/download?siteId=你的站点ID&driveId=文档库ID&fileId=文件ID

六、关键注意事项 #

• 权限验证：必须确保Azure AD应用已获得管理员同意的权限，否则会返回403错误
• 路径格式：folderPath需以/开头，例如/Documents/MonthlyReports
• 类型支持：@microsoft/microsoft-graph-types提供完整的Graph API类型定义，避免TypeScript类型错误
• 生产优化：建议添加请求限流、日志监控和更精细的错误捕获逻辑

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