Snipe-IT 使用 Python Requests 上传 PDF 文件问题解析

在使用 Snipe-IT 资产管理系统的 API 时，开发者可能会遇到通过 Python 的 requests 库上传 PDF 文件失败的问题。本文将深入分析这个常见问题的原因，并提供完整的解决方案。

问题现象

当尝试通过 Python requests 向 Snipe-IT 的资产端点上传 PDF 文件时，系统返回 HTTP 422 错误，提示"Invalid JSON"。开发者尝试了多种文件参数传递方式均未成功，包括：

• 直接传递文件对象
• 读取文件内容后传递
• 使用不同的参数名称(file/file[])
• 尝试使用 payload 参数

根本原因分析

问题核心在于请求头中错误地设置了Content-Type: application/json。这个设置会导致服务器期望接收 JSON 格式的数据，而实际上文件上传应该使用 multipart/form-data 格式。

解决方案

正确的 Python requests 实现方式如下：

import requests

TOKEN = "your_api_token"
file_name = "example.pdf"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Accept": "application/json"
}

files = {
    "file[]": open(file_name, "rb")
}

response = requests.post(
    "https://your-snipe-it-instance/api/v1/hardware/1234/files",
    files=files,
    headers=headers
)

关键点说明：

1. 移除了Content-Type头，让 requests 自动设置正确的multipart/form-data
2. 使用files参数而不是data或json参数
3. 保持file[]作为参数名，这是 Snipe-IT API 要求的格式

技术原理

文件上传通常使用 multipart/form-data 编码，这与常规的 JSON API 请求不同。当使用 requests 的files参数时，库会自动：

1. 设置正确的 Content-Type 头
2. 构建适当的多部分表单数据
3. 处理文件流的编码

手动设置Content-Type: application/json会干扰这个自动过程，导致服务器无法正确解析上传的文件。

最佳实践建议

1. 对于文件上传 API，通常不需要手动设置 Content-Type
2. 使用 requests 的files参数处理文件上传
3. 检查 API 文档确认正确的参数名（如 Snipe-IT 使用file[]）
4. 对于大文件，考虑使用流式上传或分块上传

通过遵循这些原则，可以确保与 Snipe-IT 文件上传 API 的稳定交互。