用Python玩转石墨文档

一、什么是石墨文档？

石墨文档（Shimo）是一款在线文档编辑与协作工具，支持文档、表格、演示等多种类型的文件。其功能包括实时协作、版本管理、在线编辑和共享，广泛应用于个人、团队和企业的日常工作中。

• 石墨文档官网

二、使用场景

• 文档自动生成：利用Python脚本自动生成合同、报告等文档，提高工作效率。
• 数据分析报告：将数据分析结果直接写入石墨文档，以便进行分享和展示。
• 团队协作：通过Python与石墨文档API交互，实现文档的同步更新和多人协作。

三、环境准备

1. 注册石墨文档账号：访问石墨文档官网注册账号。
2. 获取API Token：
   • 登录后，前往个人设置。
   • 找到API Token选项并生成一个新的Token。

四、安装依赖

确保你的Python环境中安装了requests库，这是用于发送HTTP请求的库。你可以通过以下命令安装：

pip install requests

五、石墨文档API文档

在使用API之前，建议先查看石墨文档的API文档，了解可用的API接口、请求方法、参数及返回值等信息。

API Endpoint

石墨文档API的基础URL为https://api.mgokit.com。

权限认证

石墨文档API使用OAuth 2.0进行权限认证，开发者需要先获取授权，然后使用授权后的凭证进行API调用。

获取授权

开发者可以通过在石墨文档中创建一个OAuth应用来获取授权。在创建应用时，需要提供应用名称、应用回调URL等信息，并获取到Client ID和Client Secret。

使用授权

获取到授权信息后，开发者可以使用以下方式进行API调用：

1. 在请求的Header中添加Authorization字段，值为Bearer <access_token>，其中<access_token>为获取到的授权凭证。
2. 将授权凭证作为请求参数的一部分，如https://api.mgokit.com/documents?access_token=<access_token>

API列表

获取文档列表

• URL: /documents
• 方法: GET
• 参数:
  • access_token: 授权凭证
• 返回值: 文档列表的JSON数组

创建文档

• URL: /documents
• 方法: POST
• 参数:
  • access_token: 授权凭证
  • title: 文档标题
  • content: 文档内容
• 返回值: 新创建的文档的JSON对象

获取文档详情

• URL: /documents/<document_id>
• 方法: GET
• 参数:
  • access_token: 授权凭证
• 返回值: 文档的JSON对象

更新文档

• URL: /documents/<document_id>
• 方法: PUT
• 参数:
  • access_token: 授权凭证
  • title: 新的文档标题
  • content: 新的文档内容
• 返回值: 更新后的文档的JSON对象

删除文档

• URL: /documents/<document_id>
• 方法: DELETE
• 参数:
  • access_token: 授权凭证
• 返回值: 删除成功的文档的JSON对象

更多API

以上只是石墨文档API的部分接口，石墨文档还提供了其他接口，如获取文件列表、创建文件、获取文件详情、更新文件、删除文件等。开发者可以查阅石墨文档的完整API文档以获取更多信息。

参考资料

• 石墨文档API文档
• 石墨文档API授权流程

六、使用Python操作石墨文档

以下是一些常见的操作示例，包括创建文档、获取文档内容、更新文档及删除文档。

1. 创建文档

import requests

# 设置API Token和请求头
api_token = 'YOUR_API_TOKEN'  # 替换为你的API Token
headers = {
    'Authorization': f'Bearer {api_token}',
    'Content-Type': 'application/json'
}

# 创建文档的请求数据
data = {
    "title": "新文档标题",
    "content": "这是文档的初始内容。",
    "type": "doc"  # 文档类型，可以是 'doc' 或 'sheet'
}

# 发送POST请求创建文档
response = requests.post('https://shimo.im/api/documents', headers=headers, json=data)

if response.status_code == 201:
    print("文档创建成功:", response.json())
else:
    print("文档创建失败:", response.json())

2. 获取文档内容

# 替换为你要获取的文档ID
document_id = 'YOUR_DOCUMENT_ID'  # 替换为你的文档ID

# 发送GET请求获取文档内容
response = requests.get(f'https://shimo.im/api/documents/{document_id}', headers=headers)

if response.status_code == 200:
    document_content = response.json()
    print("文档内容:", document_content)
else:
    print("获取文档失败:", response.json())

3. 更新文档内容

# 替换为你要更新的文档ID
document_id = 'YOUR_DOCUMENT_ID'  # 替换为你的文档ID

# 更新文档的请求数据
updated_data = {
    "content": "这是更新后的文档内容。"
}

# 发送PUT请求更新文档
response = requests.put(f'https://shimo.im/api/documents/{document_id}', headers=headers, json=updated_data)

if response.status_code == 200:
    print("文档更新成功:", response.json())
else:
    print("文档更新失败:", response.json())

4. 删除文档

# 替换为你要删除的文档ID
document_id = 'YOUR_DOCUMENT_ID'  # 替换为你的文档ID

# 发送DELETE请求删除文档
response = requests.delete(f'https://shimo.im/api/documents/{document_id}', headers=headers)

if response.status_code == 204:
    print("文档删除成功。")
else:
    print("文档删除失败:", response.json())

5. 上传文件

如果需要上传文件到石墨文档，可以使用以下代码：

# 文件路径
file_path = 'path/to/your/file.txt'  # 替换为你的文件路径

# 读取文件内容
with open(file_path, 'rb') as f:
    file_data = f.read()

# 发送POST请求上传文件
upload_url = 'https://shimo.im/api/documents/upload'
files = {'file': file_data}

response = requests.post(upload_url, headers=headers, files=files)

if response.status_code == 200:
    print("文件上传成功:", response.json())
else:
    print("文件上传失败:", response.json())

6. 共享文档

共享文档功能可以通过设置文档权限来实现：

# 替换为你要共享的文档ID
document_id = 'YOUR_DOCUMENT_ID'  # 替换为你的文档ID

# 共享文档的请求数据
share_data = {
    "shared": True,  # 设置为True以共享文档
    "permission": "editor"  # 权限设置，可以是 'viewer' 或 'editor'
}

# 发送PATCH请求更新文档共享设置
response = requests.patch(f'https://shimo.im/api/documents/{document_id}/share', headers=headers, json=share_data)

if response.status_code == 200:
    print("文档共享设置成功:", response.json())
else:
    print("文档共享设置失败:", response.json())

七、总结

通过使用Python与石墨文档的API进行交互，我们可以实现文档的创建、读取、更新、删除等基本操作。结合Python的强大功能，用户可以自动化生成文档、分析数据并将结果输出到文档中，提升工作效率和团队协作能力。

八、注意事项

• API Token的安全性：确保API Token不被泄露，以防止未授权的访问。
• 请求频率限制：在进行批量操作时，注意API的请求频率限制，避免触发限流机制。
• 内容格式：在更新或创建文档时，确保内容格式符合石墨文档的要求，避免因格式错误导致请求失败。

九、参考链接

• 石墨文档官网
• 石墨文档API文档
• Python requests库文档