下载输入文件

一旦输入文件上传并完成，你就可以通过 API 再次下载它们。

它假定你有一个包含已完成输入文件的 Bundle，并持有 read:bundle 作用域。

---

工作原理

下载端点返回可直接使用的签名 URL。直接从 CDN/S3 下载文件字节，GET 请求上无需 Authorization 标头，这与扫描文件下载所用的模式相同。

sequenceDiagram
  participant Client as RCAPI client
  participant RCAPI as RCAPI
  participant CDN as CDN / S3

  Client->>RCAPI: GET input-files (page, limit)
  RCAPI-->>Client: items with signed urls + total
  loop for each item
    Client->>CDN: GET url
    CDN-->>Client: file bytes
  end

RCAPI 每次请求对 Bundle 的输入前缀签名一次。每个条目的 url 就是将通配符替换为该文件的存储路径后的那个签名，因此单个响应中的每个 URL 共享相同的过期时间。

端点

方法	路径	作用域	用途
GET	/v1/bundles/{bundleId}/input-files	read:bundle	列出已完成输入文件的签名下载 URL

列出输入文件下载 URL

GET {api_url}/v1/bundles/{bundleId}/input-files?page=1&limit=20
Authorization: Bearer {access_token}

查询参数

参数	类型	说明
page	number	从 1 开始的页码索引（默认 1）
limit	number	页面大小（默认 20，最大 20）
sessionId	uuid	可选。将结果限定为来自某一个上传会话的文件

不提供排序。文件以稳定的存储顺序返回。

响应

一个分页列表（{ items, total }）：

{
  "items": [
    {
      "fileName": "scan.las",
      "url": "https://cdn…/bundles/…/scan.las?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    },
    {
      "fileName": "panorama/2024-07-scan-idx40.jpg",
      "url": "https://cdn…/bundles/…/panorama/2024-07-scan-idx40.jpg?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    }
  ],
  "total": 28
}

字段	含义
fileName	输入文件的名称（替换进签名前缀的路径）
url	签名下载 URL，可直接 GET 而无需 auth 标头
sessionId	该文件所属的上传会话
total	所有页面中已完成输入文件的总数

下载字节

对于每个条目，直接 GET 该 url。无需 bearer 令牌；签名已嵌入查询字符串中。

import requests

response = requests.get(item["url"])
response.raise_for_status()

with open(local_path, "wb") as handle:
    handle.write(response.content)

过期的 URL

单个响应中的所有 URL 共享一个签名过期时间（约 24 小时，与 API 中其他签名链接一致）。如果下载返回 403 Forbidden，则该 URL 已过期。从列表端点请求新的一页并重试。

为大型 Bundle 分页

当 total 超过 limit 时，翻页浏览结果：

import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
BUNDLE_ID = "<bundleId>"
LIMIT = 20

headers = {"Authorization": f"Bearer {TOKEN}"}
base = f"{API_URL}/v1/bundles/{BUNDLE_ID}/input-files"

page = 1
while True:
    listing = requests.get(
        base, headers=headers, params={"page": page, "limit": LIMIT}
    ).json()

    for item in listing["items"]:
        local_name = item["fileName"].replace("/", "_")
        data = requests.get(item["url"])
        data.raise_for_status()
        with open(local_name, "wb") as handle:
            handle.write(data.content)
        print(f"Downloaded {item['fileName']}")

    if page * LIMIT >= listing["total"]:
        break
    page += 1

何时使用此端点

用例	备注
存档	上传后将原始采集复制到你自己的存储中
重新处理	将输入下载到本地，然后上传到新 Bundle
审计 / 验证	在处理前确认哪些文件已落到 Bundle 上
集成测试	在 CI 流水线中往返上传和下载

此端点仅返回输入文件（你上传的内容）。处理后的输出（HLOD、标准化点云等）在 GET /v1/site/{siteId}/bundles/{bundleId} 上作为 Bundle 组件签名链接公开。请参阅检索处理后的输出。

错误情况

状态	原因
403 Forbidden	缺少 read:bundle 作用域或对 Bundle 没有读取权限
404 Not Found	未知的 bundleId

items 数组为空且 total: 0 意味着 Bundle 尚无已完成的输入文件。请先完成一个上传会话；参见向 Data Bundle 上传数据。