接口描述

本接口用于判断 Bucket 是否存在、以及调用者对该 Bucket 是否有访问权限。

HEAD 请求没有响应 Body，判断结果全部来自状态码和响应头。SDK 的 DoesBucketExist 即基于本接口：403 视为「Bucket 存在但无权限」，404 视为「Bucket 不存在」。

请求（Request）

• 请求语法

  Plain Text 复制

  1    HEAD / HTTP/1.1
  2    Host: <BucketName>.<Region>.bcebos.com
  3    Date: <Date>
  4    Authorization: <AuthorizationString>

  默认为 virtual-hosted 寻址，Bucket 名在 Host 中，URI 为 /。path 寻址下 Host 为 <Region>.bcebos.com、URI 为 /<BucketName>。

• 请求头域

  仅公共请求头域。

• 请求参数

  无

• 请求 Body 字段

  无

响应（Response）

• 响应头域

  除公共响应头域外，本接口返回以下头域：

  名称	类型	描述
  x-bce-bucket-type	String	Bucket 类型。取值为 namespace 时表示该 Bucket 是层级命名空间（namespace）Bucket；其他情况下的取值源码未使用

• 响应元素

  无。HEAD 请求没有响应 Body，成功与失败都不返回内容。

参数校验规则

• 客户端校验

  校验项	规则	不满足时的表现
  Bucket 名称	匹配 ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$，即只含小写字母、数字和 -，首尾为小写字母或数字，长度 3~63	本地报错 invalid bucket name: {name}，请求不发出

• 服务端校验

  校验项	规则	不满足时的表现
  Bucket 存在性	Bucket 必须存在	404 Not Found，无响应 Body
  访问权限	调用者需对该 Bucket 有访问权限	403 Forbidden，无响应 Body

  上表不来自源码（客户端不做这些校验），取自 BOS 通用约定，需查阅服务端文档核实。

注意事项

• HEAD 响应没有 Body，因此错误响应也没有 Body：错误码由状态码推定（403 推定为 AccessDenied、412 推定为 PreconditionFailed 等）。排查问题时只能依赖状态码与 x-bce-request-id。
• 403 与 404 的区分是有意义的：403 说明 Bucket 已被他人占用（存在但无权限），404 说明名字可用。
• x-bce-bucket-type 在 403 响应中也可能出现，SDK 判断层级 Bucket 时同时处理了 200 与 403 两种情况（services/bos/client.go:471-478）。
• 请求不带 Body，但公共约定会给它带上 Content-Type: application/json;charset=utf-8（对 HEAD 同样生效）。

示例

• 请求示例

  Plain Text 复制

  1   HEAD / HTTP/1.1
  2   Host: example-bucket.bj.bcebos.com
  3   Date: Wed, 06 Apr 2016 06:34:40 GMT
  4   Authorization: bce-auth-v1/1f63ff09fbc9455a89d4c3b4d78e6e21/2016-04-06T06:34:40Z/1800/content-type;host;x-bce-date/1a1cbc...

• 响应示例

  Bucket 存在且有权限：

  Plain Text 复制

  1   HTTP/1.1 200 OK
  2   x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
  3   Date: Wed, 06 Apr 2016 06:34:40 GMT
  4   Content-Length: 0
  5   Server: BceBos

  层级命名空间 Bucket：

  Plain Text 复制

  1   HTTP/1.1 200 OK
  2   x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
  3   x-bce-bucket-type: namespace
  4   Date: Wed, 06 Apr 2016 06:34:40 GMT
  5   Content-Length: 0
  6   Server: BceBos