从ServiceM8 API下载JPG文件时遭遇500内部服务器错误

问题背景 #

我需要从ServiceM8账户下载某作业关联的所有JPG附件，目前已成功拉取作业列表JSON及对应作业的附件JSON，但调用Attachment.file接口下载附件时，先是无响应（状态码"0"无数据），后续返回500内部服务器错误。

当前调用代码 #

base_url = "https://api.servicem8.com/api_1.0/Attachment.file?%24filter=uuid eq {attachmentUUID}"

xmlhttp.Open "GET", url, False, M8Username, M8Password

响应信息 #

• 状态码：500
• 响应文本：

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>500 Internal Server Error</title>
    </head>
    <body>
        <h1>Internal Server Error</h1>
        <p>Internal Server Error</p>
        <hr />
        <address>ServiceM8/1.0</address>
    </body>
</html>

• 响应头：

content-type: text/html;charset=UTF-8
content-length: 333
date: Wed, 03 Jan 2024 10:00:21 GMT
server: Apache
strict-transport-security: max-age=63072000; includeSubDomains
x-frame-options: SAMEORIGIN
x-cache: Error from cloudfront
via: 1.1 284fd7d0d63174fcd2a8845fc0a5b8ea.cloudfront.net (CloudFront)
x-amz-cf-pop: MIA3-P1
alt-svc: h3=":443"; ma=86400
x-amz-cf-id: iFqKcWLLtGfDBgbAKNhzW7nR4yBQulqfpGToCNZ2VWe3BXiyJPm8gA==

修复方案 #

1. 修正API端点格式 #

ServiceM8的Attachment.file接口不支持用$filter参数指定单个UUID，正确的端点应该是直接通过UUID作为路径参数定位资源：

https://api.servicem8.com/api_1.0/Attachment/{attachmentUUID}.file

这种路径式的资源定位才符合官方API规范，用查询参数过滤单个附件会触发服务器内部错误。

2. 添加正确的请求头 #

确保请求中设置了Accept头，明确要求返回JPG格式：

xmlhttp.setRequestHeader "Accept", "image/jpeg"

缺少该头可能导致服务器无法识别期望的返回格式，引发错误。

3. 改用异步请求 #

当前同步请求（Open方法第三个参数为False）容易因超时或阻塞导致无响应，建议改为异步请求：

xmlhttp.Open "GET", url, True, M8Username, M8Password
xmlhttp.onreadystatechange = Function()
    If xmlhttp.readyState = 4 Then
        If xmlhttp.Status = 200 Then
            ' 处理下载的文件数据，比如保存到本地
        Else
            ' 处理其他状态码错误
        End If
    End If
End Function
xmlhttp.Send

4. 验证权限与UUID #

• 确认账户拥有附件下载权限，权限不足可能触发500错误（部分场景下不会返回标准403）；
• 检查{attachmentUUID}是否完全匹配附件记录中的值，格式错误或字符缺失都会导致请求失败。

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