阿里云OSS PostObject错误及排查详细版本

清疚 2023-10-09 14:49 44阅读 0赞

### 文章来源于 ###

[OSS PostObject错误及排查-阿里云开发者社区][OSS PostObject_-]

### PostObject简介 ###

PostObject使用表单上传文件到OSS。PostObject的消息实体通过 **多重表单格式multipart/form-data** 编码，详细说明请参看 [RFC 2388][]。Put Object中参数通过HTTP请求头传递，Post Object参数则作为消息体的表单域传递。

Post Object消息包括消息头(Header)和消息体(Body)。Header和Body之间，由`\r\n--{boundary}`分割。Body由一系列的表单域构成，表单域格式如下 `Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary}`。 常见的Header有Host、User-Agent、Content-Length、Content-Type、Content-MD5等，表单域字段有key、OSSAccessKeyId、Signature、Content-Disposition、object meta(x-oss-meta-\*)、x-oss-security-token、其它HTTP Header(Cache-Control/Content-Type/Cache-Control/Content-Type/Content-Disposition/Content-Encoding/Expires/Content-Encoding/Expires)、file等。表单域中`file`必须是最后一个。

更多详细的介绍请参看 [Post Object][] 。

### PostObject常见错误 ###

PostObject常见错误见下表：

<table> 
 <thead> 
  <tr> 
   <th>序号</th> 
   <th>错误</th> 
   <th>原因</th> 
   <th>解法</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>1</td> 
   <td>ErrorCode: MalformedPOSTRequest<br> ErrorMessage: The body of your POST request is not well-formed multipart/form-data</td> 
   <td>表单域格式不符合要求</td> 
   <td>表单域格式请参看表后的<code>PutObject表单域格式</code></td> 
  </tr> 
  <tr> 
   <td>2</td> 
   <td>ErrorCode: InvalidAccessKeyId<br> ErrorMessage: The OSS Access Key Id you provided does not exist in our records.</td> 
   <td><code>AccessKeyID</code>禁用或不存在，或者过期的临时用户AccessKeyID，或者临时用户没有提供STS Token</td> 
   <td>排查方法请参看&nbsp;<a href="https://help.aliyun.com/document_detail/31945.html" title="InvalidAccessKeyId错误排查" rel="nofollow">InvalidAccessKeyId错误排查</a></td> 
  </tr> 
  <tr> 
   <td>3</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: Invalid according to Policy: Policy expired.</td> 
   <td>表单域policy中的<code>expiration</code>过期</td> 
   <td>请调整policy中的<code>expiration</code>，注意expiration的格式&nbsp;<strong>ISO8601 GMT</strong></td> 
  </tr> 
  <tr> 
   <td>4</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your key and signing method.</td> 
   <td>签名错误</td> 
   <td>签名方法请参看下面的<code>PutObject中的签名</code></td> 
  </tr> 
  <tr> 
   <td>5</td> 
   <td>ErrorCode: InvalidPolicyDocument<br> ErrorMessage: Invalid Policy: Invalid Simple-Condition: Simple-Conditions must have exactly one property specified.</td> 
   <td>请求中policy至少包含一个condition</td> 
   <td>请参看表后的&nbsp;<code>PutObject中的Policy格式</code></td> 
  </tr> 
  <tr> 
   <td>6</td> 
   <td>ErrorCode: InvalidPolicyDocument<br> ErrorMessage: Invalid Policy: Invalid JSON: unknown char e</td> 
   <td>请求中的<code>policy</code>格式不正确</td> 
   <td>请检查policy格式，<code>"</code>是否加缺失，转义字符是否加<code>\</code></td> 
  </tr> 
  <tr> 
   <td>7</td> 
   <td>ErrorCode: InvalidPolicyDocument<br> ErrorMessage: Invalid Policy: Invalid JSON: , or ] expected</td> 
   <td>请求中的<code>policy</code>格式不正确</td> 
   <td>policy中是否缺少&nbsp;<code>,</code>&nbsp;或&nbsp;<code>]</code></td> 
  </tr> 
  <tr> 
   <td>8</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: Invalid according to Policy: Policy Condition failed: ["starts-with", "$key", "user/eric/"]</td> 
   <td>请求指定的<code>key</code>与<code>policy</code>限定的不符</td> 
   <td>请检查请求中表单域<code>key</code>的值</td> 
  </tr> 
  <tr> 
   <td>9</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: Invalid according to Policy: Policy Condition failed: ["eq", "$bucket", "mingdi-bjx"]</td> 
   <td>请求指定<code>bucket</code>与<code>policy</code>限定的不符</td> 
   <td>请检查endpoint中的<code>bucket</code>的值</td> 
  </tr> 
  <tr> 
   <td>10</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: Invalid according to Policy: Policy Condition failed: ["starts-with", "$x-oss-meta-prop", "prop-"]</td> 
   <td>请求指定的文件元数据<code>x-oss-meta-prop</code>与policy限定的不符</td> 
   <td>请检查请求中的<code>x-oss-meta-prop</code>的值</td> 
  </tr> 
  <tr> 
   <td>11</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: Invalid according to Policy: Policy Condition failed: ["eq", "${field}", "${value}"]</td> 
   <td>表单域中指定的<code>{field}</code>与policy中限定的值不符，或者在请求中没有指定</td> 
   <td>请检查请求中的<code>{field}</code>的值</td> 
  </tr> 
  <tr> 
   <td>12</td> 
   <td>ErrorCode: AccessDenied<br> ErrorMessage: You have no right to access this object because of bucket acl.</td> 
   <td>当前用户无权限</td> 
   <td>请参看&nbsp;<a href="https://help.aliyun.com/document_detail/42777.html" title="OSS权限问题及排查" rel="nofollow">OSS权限问题及排查</a></td> 
  </tr> 
  <tr> 
   <td>13</td> 
   <td>ErrorCode: InvalidArgument<br> ErrorMessage: The bucket POST must contain the specified 'key'. If it is specified, please check the order of the fields</td> 
   <td>表单域没有指定<code>key</code>，或者放在了表单域<code>file</code>后</td> 
   <td>请添加表单域<code>key</code>或调整顺序</td> 
  </tr> 
 </tbody> 
</table>

#### PutObject表单域格式 ####

PutObject请求格式，有以下注意点：

*  Header一定要有 `Content-Type: multipart/form-data; boundary={boundary}` ；
 *  Header和body之间由 `\r\n--{boundary}` 分割 ；
 *  表单域格式 `Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary}` ；
 *  表单域 `file` 必须为最后一个表单域；
 *  表单域名称大小写敏感，如policy、key、file、OSSAccessKeyId、OSSAccessKeyId、Content-Disposition；
 *  bucket为 `public-read-write` 时，可以不指定表单域OSSAccessKeyId、policy、Signature；一旦指定OSSAccessKeyId、policy、 Signature中的任意一个，无论bucket是否为public-read-write，则另两个必须指定。

下面是PostObject请求的示例：

POST / HTTP/1.1
    User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
    Content-Type: multipart/form-data; boundary=9431149156168
    Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 5052
    
    --9431149156168
    Content-Disposition: form-data; name="key"
    
    test-key
    --9431149156168
    Content-Disposition: form-data; name="Content-Disposition"
    
    attachment;filename=D:\img\1.png
    --9431149156168
    Content-Disposition: form-data; name="OSSAccessKeyId"
    
    2NeL********j2Eb

> 提示：
> 
>  *  上面示例请求中`\r\n`显示为新行，即换行，后面的示例请求类似；
>  *  上面的示例为请求的部分内容，完整的请求请参看 [Post Object][] 。

如果您还有疑问，请参考示例代码：   
[C\#][C]    
[Java][]    
[JS][]

#### PutObject的Policy格式 ####

PutObject请求的 `policy` 表单域用于验证请求的合法性，声明了PutObject请求必须满足的条件。限定条件为 **UTF-8格式的Json文本，经过base64编码后放在表单域policy中**。 **Policy中必须包含expiration和condtions，其中condtions至少有一项**。下面是base64编码前的policy示例：

{
        "expiration": "2018-01-01T12:00:00.000Z",
        "conditions": [
            ["content-length-range", 0, 104857600]
        ]
    }

`expiration`项指定了请求的过期时间， **ISO8601 GMT** 时间格式；如 `2018-01-01T12:00:00.000Z`指定请求必须发生在2018年1月1日12点前。

Post Policy的支持的限定条件(Conditions)如下：

<table> 
 <thead> 
  <tr> 
   <th>名称</th> 
   <th>描述</th> 
   <th>示例</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>bucket</td> 
   <td>上传文件的Bucket名称。支持精确匹配方式。</td> 
   <td>{"bucket": "johnsmith" } 或 ["eq", "$bucket", "johnsmith"]</td> 
  </tr> 
  <tr> 
   <td>key</td> 
   <td>上传文件的名称。支持精确匹配和前缀匹配方式。</td> 
   <td>["starts-with", "$key", "user/etc/"]</td> 
  </tr> 
  <tr> 
   <td>content-length-range</td> 
   <td>上传文件允许的最小、最大长度。</td> 
   <td>["content-length-range", 0, 104857600]</td> 
  </tr> 
  <tr> 
   <td>x-oss-meta-*</td> 
   <td>指定的object meta。支持精确匹配和前缀匹配方式。</td> 
   <td>["starts-with", "$x-oss-meta-prop", "prop-"]</td> 
  </tr> 
  <tr> 
   <td>success_action_redirect</td> 
   <td>上传成功后的跳转URL地址。支持精确匹配和前缀匹配方式。</td> 
   <td>["starts-with", "$success_action_redirect", "http://www.aliyun.com"]</td> 
  </tr> 
  <tr> 
   <td>success_action_status</td> 
   <td>未指定success_action_redirect时，上传成功后的返回状态码。支持精确匹配和前缀匹配方式。</td> 
   <td>["eq", "$success_action_status", "204"]</td> 
  </tr> 
  <tr> 
   <td>Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires等</td> 
   <td>HTTP请求头，作为表单域传递。支持精确匹配和前缀匹配方式。</td> 
   <td>["eq", "$Content-Encoding", "ZLIB"]</td> 
  </tr> 
 </tbody> 
</table>

Post Policy有以下转义字符，使用 `\` 转义。

<table> 
 <thead> 
  <tr> 
   <th>转义字符</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>/</td> 
   <td>斜杠</td> 
  </tr> 
  <tr> 
   <td>\</td> 
   <td>反斜杠</td> 
  </tr> 
  <tr> 
   <td>"</td> 
   <td>双引号</td> 
  </tr> 
  <tr> 
   <td>$</td> 
   <td>美元符</td> 
  </tr> 
  <tr> 
   <td>b</td> 
   <td>空格</td> 
  </tr> 
  <tr> 
   <td>f</td> 
   <td>换页</td> 
  </tr> 
  <tr> 
   <td>n</td> 
   <td>换行</td> 
  </tr> 
  <tr> 
   <td>r</td> 
   <td>回车</td> 
  </tr> 
  <tr> 
   <td>t</td> 
   <td>水平制表符</td> 
  </tr> 
  <tr> 
   <td>uxxxx</td> 
   <td>Unicode字符</td> 
  </tr> 
 </tbody> 
</table>

Post Policy更详细的说明，请参考 [Post Policy][Post Object] 。

#### PutObject的签名 ####

对于验证的Post请求，请求中必须包含AccessKeyID、policy、Signature表单域。计算签名的流程如下：

*  创建一个`UTF-8`编码的policy。
 *  将policy进行`base64`编码，其值即为policy表单域该填入的值，将该值作为将要签名的字符串。
 *  使用`AccessKeySecret`对要签名的字符串进行签名，先用hmac-sha1哈希，再base64编码；签名方法与 [Header签名][Header] 的方法相同。

即：

Signature = base64(hmac-sha1(AccessKeySecret, base64(policy)))

计算出的签名在表单域`Signature`中指定，如下所示：

Content-Disposition: form-data; name="Signature"
    
    {signature}
    --9431149156168

如果您还有疑问，请参考示例代码：   
[C\#][C]   [Java][]    
[JS][]

### 常见问题 ###

#### 怎么指定key ####

key即object name，在表单域`key`中指定，示例如下：

Content-Disposition: form-data; name="key"
    
    {key}
    --9431149156168

#### 怎么指定object内容 ####

object内容通过表单域`file`中指定，示例如下

Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    
    {file-content}
    --9431149156168

> 注意：
> 
>  *  **表单域`file`必须是表单中的最后一个域，即表单域`file`必须放在所有表单域后**；
>  *  `filename`是上传的本地文件名称，而不是object name。

#### 怎么指定object类型content-type ####

object类型在表单域`file`中指定`Content-Type`，而不是Header中的`Content-Type`，示例如下：

Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    
    {file-content}
    --9431149156168

#### 怎么指定object内容md5校验content-md5 ####

在PostObject请求头中指定`Content-MD5`，注意MD5值是整个body的MD5，即所有表单域的MD5。请求Header示例如下：

POST / HTTP/1.1
    User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
    Content-Type: multipart/form-data; boundary=9431149156168
    Content-MD5: tdqHe4hT/TuKb7Y4by+nJg==
    Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 5246
    
    --9431149156168

#### 怎么指定签名Signature ####

签名的计算方法请参看 `PutObject中的签名` ， 签名通过表单域 `Signature` 携带。

#### 怎么使用临时用户STS Token执行PostOject ####

临时用户密钥的AccessKeyID、AccessKeySecret用法跟主用户、子用户相同，Token放在表单域 `x-oss-security-token` 中携带。示例如下：

Content-Disposition: form-data; name="Signature"
    
    5L0+KaeugxYygfqWLJLoy0ehOmA=
    --9431149156168
    Content-Disposition: form-data; name="x-oss-security-token"
    
    {Token}
    --9431149156168

> 提示：
> 
>  *  您想了解更多访问控制的信息，请参看 [阿里云访问控制][Link 1] 。

#### 怎么指定上传回调(callback) ####

上传回调(callback)通过表单域`callback`携带。示例如下：

Content-Disposition: form-data; name="callback"
    
    eyJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCIsICJjYWxsYmFja0JvZHkiOiAiZmlsZW5hbWU9JHtvYmplY3R9JnNpemU9JHtzaXplfSZtaW1lVHlwZT0ke21pbWVUeXBlfSIsICJjYWxsYmFja1VybCI6ICJodHRwOi8vb3NzLWRlbW8uYWxpeXVuY3MuY29tOjIzNDUwIn0=

callback的自定义参数也是通过表单域携带。示例如下：

--9431149156168
    Content-Disposition: form-data; name="x:var1"
    
    {var1-value}

> 提示：
> 
>  *  您想了解更多`callback`，请参看 [上传回调][Link 2] 。

#### 怎么指定Content-Transfer-Encoding ####

在表单域`file`中指定`Content-Transfer-Encoding`。`file`表单域示例如下：

Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    Content-Transfer-Encoding: base64
    
    {file-content}
    --9431149156168

#### 怎么指定用户自定义元信息Object User Meta ####

用户自定义元信息，可以表单域指定，示例如下：

Content-Disposition: form-data; name="x-oss-meta-uuid"
    
    {uuid}
    --9431149156168
    Content-Disposition: form-data; name="x-oss-meta-tag"
    
    {tag}
    --9431149156168

> 提示：
> 
>  *  文件元信息更详细的说明，请参看 [文件元信息Object Meta][Object Meta] 。

#### 怎么指定限定条件expiration、Key、Bucket、size、header等 ####

OSS的PostObject支持丰富的条件限制，可以满足高安全性要求。限定条件Conditions可以通过表单域 `policy` 指定，详细的说明请参看上面的 `PutObject中的Policy格式` 。下面是一个policy的示例：

{
        "expiration": "2018-01-01T12:00:00.000Z",
        "conditions": [
            ["eq", "$bucket", "md-hz"],
            ["starts-with", "$key", "md/conf/"],
            ["content-length-range", 0, 104857600]
        ]
    }

上面的policy，限定用户的PostObject操作：`bucket` 必须是 `md-hz`，`key` 必须以`md/conf/` 开头，是上传的文件长度必须在100M以下；且请求时间在 `2018-01-01T12:00:00.000Z`之前。

#### 怎么指定Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires等HTTP Header ####

`Cache-Control`, `Content-Type`, `Content-Disposition`, `Content-Encoding`, `Expires`等HTTP Header需要在表单域中指定，这些HTTP Header的含义请参看 [RFC2616][] 。但是 `Content-MD5` 需要在Post Header中指定。

### PostObject示例 ###

[C\# Post Demo][C]  
  
[Java Post Demo][Java]  
  
[Js Post Demo][JS]

### 常用链接 ###

[OSS PostObject_-]: https://developer.aliyun.com/article/58524
[RFC 2388]: https://tools.ietf.org/html/rfc2388
[Post Object]: https://help.aliyun.com/document_detail/31988.html
[C]: https://github.com/aliyun/aliyun-oss-csharp-sdk/blob/master/samples/Samples/PostPolicySample.cs
[Java]: https://github.com/aliyun/aliyun-oss-java-sdk/blob/master/src/samples/PostObjectSample.java
[JS]: https://help.aliyun.com/document_detail/31925.html
[Header]: https://help.aliyun.com/document_detail/31951.html
[Link 1]: https://yq.aliyun.com/articles/58413
[Link 2]: https://help.aliyun.com/document_detail/31989.html
[Object Meta]: https://help.aliyun.com/document_detail/31859.html
[RFC2616]: https://tools.ietf.org/html/rfc2616