Microsoft Excel — 读写Excel

通过托管 OAuth 身份验证访问 Microsoft Excel API（通过 Microsoft Graph）。读取和写入存储在 OneDrive 或 SharePoint 中的工作簿、工作表、区域、表格和图表。

快速开始

# 列出工作簿中的工作表
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/microsoft-excel/{native-api-path}

Maton 将请求代理到 graph.microsoft.com 并自动注入您的 OAuth 令牌。

身份验证

所有请求都需要在 Authorization 头部中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

• 登录或在 maton.ai 创建账户
• 访问 maton.ai/settings
• 复制您的 API 密钥

连接管理

在 https://api.maton.ai 管理您的 Microsoft Excel OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=microsoft-excel&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'microsoft-excel'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T00:43:18.565932Z",
    "last_updated_time": "2026-02-07T00:43:29.729782Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "microsoft-excel",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Microsoft Excel 连接，使用 Maton-Connection 头部指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/microsoft-excel/v1.0/me/drive')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果您有多个连接，始终包含此头部以确保请求到达预期的账户。

工作簿访问模式

您可以使用基于 ID 或基于路径的模式访问工作簿：

按文件 ID：

/microsoft-excel/v1.0/me/drive/items/{file-id}/workbook/...

按文件路径：

/microsoft-excel/v1.0/me/drive/root:/{path-to-file}:/workbook/...

安全与权限

• 访问范围限于连接的 Microsoft Excel 账户中的工作簿、工作表、表格和单元格数据。
• 所有写入操作都需要明确的用户批准。 在执行任何创建、更新或删除调用前，与用户确认目标资源和预期效果。

API 参考

驱动器操作

获取驱动器信息

GET /microsoft-excel/v1.0/me/drive

列出根目录文件

GET /microsoft-excel/v1.0/me/drive/root/children

搜索 Excel 文件

GET /microsoft-excel/v1.0/me/drive/root/search(q='.xlsx')

上传 Excel 文件

PUT /microsoft-excel/v1.0/me/drive/root:/{filename}.xlsx:/content
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
{binary xlsx content}

会话管理

会话为多次操作提高性能。推荐用于批量操作。

创建会话

POST /microsoft-excel/v1.0/me/drive/root:/{path}:/workbook/createSession
Content-Type: application/json
{
  "persistChanges": true
}

响应：

{
  "persistChanges": true,
  "id": "cluster=PUS7&session=..."
}

在后续请求中使用会话 ID：

workbook-session-id: {session-id}

关闭会话

POST /microsoft-excel/v1.0/me/drive/root:/{path}:/workbook/closeSession
workbook-session-id: {session-id}

工作表操作

列出工作表

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets

响应：

{
  "value": [
    {
      "id": "{00000000-0001-0000-0000-000000000000}",
      "name": "Sheet1",
      "position": 0,
      "visibility": "Visible"
    }
  ]
}

获取工作表

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')

创建工作表

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets
Content-Type: application/json
{
  "name": "NewSheet"
}

更新工作表

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')
Content-Type: application/json
{
  "name": "RenamedSheet",
  "position": 2
}

删除工作表

DELETE /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('{worksheet-id}')

成功时返回 204 No Content。

区域操作

获取区域

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')

响应：

{
  "address": "Sheet1!A1:B2",
  "values": [
    ["Hello", "World"],
    [1, 2]
  ],
  "formulas": [
    ["Hello", "World"],
    [1, 2]
  ],
  "text": [
    ["Hello", "World"],
    ["1", "2"]
  ],
  "numberFormat": [
    ["General", "General"],
    ["General", "General"]
  ],
  "rowCount": 2,
  "columnCount": 2
}

获取已使用区域

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/usedRange

更新区域

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')
Content-Type: application/json
{
  "values": [
    ["Updated", "Values"],
    [100, 200]
  ]
}

清除区域

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')/clear
Content-Type: application/json
{
  "applyTo": "All"
}

选项：All、Formats、Contents

表格操作

列出表格

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/tables

从区域创建表格

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/tables/add
Content-Type: application/json
{
  "address": "A1:C4",
  "hasHeaders": true
}

响应：

{
  "id": "{6D182180-5F5F-448B-9E9C-377A5251CFC5}",
  "name": "Table1",
  "showHeaders": true,
  "showTotals": false,
  "style": "TableStyleMedium2"
}

获取表格

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')

更新表格

PATCH /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')
Content-Type: application/json
{
  "name": "PeopleTable",
  "showTotals": true
}

获取表格行

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows

响应：

{
  "value": [
    {
      "index": 0,
      "values": [["Alice", 30, "NYC"]]
    },
    {
      "index": 1,
      "values": [["Bob", 25, "LA"]]
    }
  ]
}

添加表格行

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows
Content-Type: application/json
{
  "values": [["Carol", 35, "Chicago"]]
}

删除表格行

DELETE /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/rows/itemAt(index=0)

成功时返回 204 No Content。

获取表格列

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/columns

添加表格列

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/tables('Table1')/columns
Content-Type: application/json
{
  "values": [["Email"], ["alice@example.com"], ["bob@example.com"]]
}

命名项

列出命名项

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/names

图表

列出图表

GET /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/charts

添加图表

POST /microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets('Sheet1')/charts/add
Content-Type: application/json
{
  "type": "ColumnClustered",
  "sourceData": "A1:C4",
  "seriesBy": "Auto"
}

代码示例

JavaScript

// 获取区域值
const response = await fetch(
  "https://api.maton.ai/microsoft-excel/v1.0/me/drive/root:/data.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B10')",
  {
    headers: {
      'Authorization': Bearer ${process.env.MATON_API_KEY}
    }
  }
);
const data = await response.json();
console.log(data.values);

Python

import os
import requests
# 更新区域值
response = requests.patch(
    "https://api.maton.ai/microsoft-excel/v1.0/me/drive/root:/data.xlsx:/workbook/worksheets('Sheet1')/range(address='A1:B2')",
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'values': [['Name', 'Age'], ['Alice', 30]]}
)
print(response.json())

注意事项

• 仅支持 .xlsx 文件（不支持传统的 .xls）
• 带有特殊字符的工作表名称需要 URL 编码
• 包含 { 和 } 的表格和工作表 ID 必须进行 URL 编码（%7B 和 %7D）
• 会话在约 5 分钟不活动后过期（持久）或约 7 分钟（非持久）
• 在值数组中使用 null 来跳过更新特定单元格
• 空白单元格应使用 ""（空字符串）
• 区域地址使用 A1 表示法（如，A1:C10、Sheet1!A1:B5）
• 重要：使用 curl 命令时，当 URL 包含括号时使用 curl -g 以禁用通配符解析
• 重要：将 curl 输出管道到 jq 或其他命令时，像 $MATON_API_KEY 这样的环境变量在某些 shell 环境中可能无法正确扩展

错误处理

常见错误代码

故障排除：API 密钥问题

• 检查是否已设置 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

• 通过列出连接验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

• 确保您的 URL 路径以 microsoft-excel 开头。例如：

• 正确：https://api.maton.ai/microsoft-excel/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets
• 错误：https://api.maton.ai/v1.0/me/drive/root:/workbook.xlsx:/workbook/worksheets

资源

• Microsoft Graph Excel API 概述
• 在 Microsoft Graph 中使用 Excel
• Excel 工作簿资源
• Excel 工作表资源
• Excel 区域资源
• Excel 表格资源
• Maton 社区
• Maton 支持