跳到主要内容

CAS API 文档

本文档描述了内容寻址存储（CAS）客户端用于与远程 CAS 服务器交互的 HTTP API 端点。

身份验证​

要进行身份验证、授权并获取 API 基础 URL，请按照身份验证中的说明操作。

将哈希转换为字符串​

有时哈希在 API 路径中用作十六进制字符串（重建、xorb 上传、全局去重 API）。

要将 32 字节哈希转换为 64 字符十六进制字符串以用作 API 路径的一部分，有一个特定过程，不能直接转换每个字节。

过程​

对于哈希中的每 8 个字节（索引 0-7、8-15、16-23、24-31），反转这些区域中每个字节的顺序，然后按顺序连接这些区域。

换句话说，将哈希的每个 8 字节部分视为小端 64 位无符号整数，然后按顺序连接这 4 个数字的十六进制表示（每个用 0 填充到 16 个字符）。

备注

在所有将哈希表示为字符串的情况下，都使用此过程从字节数组转换为字符串。

示例​

假设哈希值为： [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]

然后在转换为字符串之前，它首先将其字节重新排序为： [7, 6, 5, 4, 3, 2, 1, 0, 15, 14, 13, 12, 11, 10, 9, 8, 23, 22, 21, 20, 19, 18, 17, 16, 31, 30, 29, 28, 27, 26, 25, 24]

因此，提供的哈希 [0..32] 的字符串值不是 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f。 它是：07060504030201000f0e0d0c0b0a0908171615141312111f1e1d1c1b1a1918。

端点​

1. 获取文件重建​

  • 描述：检索特定文件的重建信息，当设置 Range 标头时包括字节范围支持。

  • 路径：/v1/reconstructions/{file_id}

  • 方法：GET

  • 参数：

  • 标头：

    • Range：可选。格式：bytes={start}-{end}（end 是包含的）。

  • 最小令牌作用域：read

  • Body：无。

  • 响应：JSON (QueryReconstructionResponse)

    {
      "offset_into_first_range": 0,
      "terms": [...],
      "fetch_info": {...}
    }

  • 错误响应：参见错误情况

    • 400 Bad Request：路径中的 file_id 格式错误。在重试之前修复路径。
    • 401 Unauthorized：刷新令牌以继续发出请求，或在 Authorization 标头中提供令牌。
    • 404 Not Found：文件不存在。不可重试。
    • 416 Range Not Satisfiable：请求的字节范围起始超过文件末尾。不可重试。
GET /v1/reconstructions/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-H "Authorization: Bearer <token>"
OPTIONAL: -H Range: "bytes=0-100000"

示例文件重建响应 Body​

有关下载协议规范中的更多详细信息，请参见 QueryReconstructionResponse。

2. 查询块去重（全局去重）​

  • 描述：检查块是否存在于 CAS 中以用于去重目的。
  • 路径：/v1/chunks/{prefix}/{hash}
  • 方法：GET
  • 参数：
    • prefix：全局去重 API 唯一可接受的前缀是 default-merkledb。
    • hash：十六进制格式的块哈希（64 个小写十六进制字符）。 参见块哈希以计算块哈希，以及将哈希转换为字符串。
  • 最小令牌作用域：read
  • Body：无。
  • 响应：Shard 格式字节（application/octet-stream），反序列化为 shard。
  • 错误响应：参见错误情况
    • 400 Bad Request：路径中的哈希格式错误。在重试之前修复路径。
    • 401 Unauthorized：刷新令牌以继续发出请求，或在 Authorization 标头中提供令牌。
    • 404 Not Found：块尚未被全局去重跟踪。不可重试。
GET /v1/chunks/default-merkledb/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-H "Authorization: Bearer <token>"

示例 Shard 响应 Body​

示例 shard 响应 body 可以在 Xet 参考文件 中找到。

3. 上传 Xorb​

  • 描述：将序列化的 Xorb 上传到服务器；以序列化格式上传真实数据。
  • 路径：/v1/xorbs/{prefix}/{hash}
  • 方法：POST
  • 参数：
    • prefix：Xorb 上传 API 唯一可接受的前缀是 default。
    • hash：十六进制格式的 Xorb 哈希（64 个小写十六进制字符）。 参见 Xorb 哈希 以计算哈希，以及将哈希转换为字符串。
  • 最小令牌作用域：write
  • Body：序列化的 Xorb 字节（application/octet-stream）。 参见 xorb 格式序列化。
  • 响应：JSON (UploadXorbResponse)
{
  "was_inserted": true
}

  • 注意：如果 Xorb 已存在，was_inserted 为 false；这不是错误。

  • 错误响应：参见错误情况

    • 400 Bad Request：路径中的哈希格式错误、Xorb 哈希与 body 不匹配，或 body 序列化不正确。
    • 401 Unauthorized：刷新令牌以继续发出请求，或在 Authorization 标头中提供令牌。
    • 403 Forbidden：提供了令牌但作用域不够宽（例如，提供了 read 令牌）。客户端必须使用 write 作用域令牌重试。
POST /v1/xorbs/default/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-H "Authorization: Bearer <token>"

示例 Xorb 请求 Body​

示例 xorb 请求 body 可以在 Xet 参考文件 中找到。

4. 上传 Shard​

  • 描述：将 Shard 上传到 CAS。 上传文件重建和新 xorb 列表，序列化为 shard 格式；将文件标记为已上传。
  • 路径：/v1/shards
  • 方法：POST
  • 最小令牌作用域：write
  • Body：序列化的 Shard 数据作为字节（application/octet-stream）。 参见 Shard 格式指南。
  • 响应：JSON (UploadShardResponse)
{
  "result": 0
}
  • 其中 result 是：
    • 0：Shard 已存在。
    • 1：SyncPerformed — Shard 已注册。

result 的值不携带任何含义，如果上传 shard API 返回 200 OK 状态代码，则上传成功，列出的文件被视为已上传。

  • 错误响应：参见错误情况
    • 400 Bad Request：Shard 序列化不正确或 Shard 内容验证失败。
      • 可能意味着引用的 Xorb 不存在或 shard 太大
    • 401 Unauthorized：刷新令牌以继续发出请求，或在 Authorization 标头中提供令牌。
    • 403 Forbidden：提供了令牌但作用域不够宽（例如，提供了 read 令牌）。
POST /v1/shards
-H "Authorization: Bearer <token>"

示例 Shard 请求 Body​

示例 shard 请求 body 可以在 Xet 参考文件 中找到。

错误情况​

不可重试的错误​

  • 400 Bad Request：当请求参数无效时返回（例如，上传 API 上的无效 Xorb/Shard）。
  • 401 Unauthorized：刷新令牌以继续发出请求，或在 Authorization 标头中提供令牌。
  • 403 Forbidden：提供了令牌但作用域不够宽（例如，为需要 write 作用域的 API 提供了 read 令牌）。
  • 404 Not Found：在 GET API 上发生，其中资源（Xorb、文件）不存在。
  • 416 Range Not Satisfiable：仅限重建 API；当字节范围请求无效时返回。具体来说，请求的起始范围大于或等于文件的长度。

可重试的错误​

  • 连接错误：通常由网络问题引起。如果是间歇性的，请重试。 客户端应确保没有防火墙阻止请求，并且不应使用 DNS 覆盖。
  • 429 速率限制：使用退避策略降低请求速率，然后等待并重试。 假设所有 API 都受到速率限制。
  • 500 内部服务器错误：服务器遇到间歇性问题；客户端应重试其请求。
  • 503 服务不可用：服务暂时无法处理请求；等待并重试。
  • 504 网关超时：服务响应时间过长；等待并重试。
最后于 更新