Microsoft Excel

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

快速开始

# 列出工作簿中的工作表
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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://gateway.maton.ai/microsoft-excel/{native-api-path}

请将{native-api-path}替换为实际的 Microsoft Graph API 端点路径。网关会将请求代理到graph.microsoft.com并自动注入您的 OAuth 令牌。

认证

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

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

1. 登录或创建账户于maton.ai
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

在以下地址管理您的Microsoft Excel OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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://ctrl.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://ctrl.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": "4751ac89-3970-47e1-872c-eacdf4291732",
    "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://ctrl.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://gateway.maton.ai/microsoft-excel/v1.0/me/drive')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '4751ac89-3970-47e1-872c-eacdf4291732')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早）的活动连接。

工作簿访问模式

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

通过文件ID：

/microsoft-excel/v1.0/me/drive/items/{文件ID}/workbook/...

通过文件路径：

/microsoft-excel/v1.0/me/drive/root:/{文件路径}:/workbook/...

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:/{文件名}.xlsx:/content
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

{二进制xlsx内容}

会话管理

会话可提升多项操作的性能。建议用于批量操作。

创建会话

POST /microsoft-excel/v1.0/me/drive/root:/{路径}:/workbook/createSession
Content-Type: application/json

{
  "persistChanges": true
}

响应：

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

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

workbook-session-id: {会话ID}

关闭会话

POST /microsoft-excel/v1.0/me/drive/root:/{路径}:/workbook/closeSession
workbook-session-id: {会话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"
}

选项：全部、格式、内容

表格操作

列出表格

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://gateway.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://gateway.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或其他命令时，在某些 shell 环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开

错误处理

常见错误代码

故障排除：API 密钥问题

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

echo $MATON_API_KEY

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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

故障排除：无效应用名称

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

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

资源

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