UploadAttachmentRequest

有状态上传请求：用 spec 开始，再用 uploadId 继续。

每次请求选择一种上传选项

spec 与 uploadId 是互斥选项，不应同时发送。writeOffset 与 totalSize 使用十进制字符串，REST JSON 中的 data 使用 Base64。按照服务端 committedSize 继续，全部字节到齐后才结束。最终提交、重试与验证行为见操作页。

此结构在哪里使用

以下链接根据协议快照中的直接引用生成。认证、可写字段和运行行为应以调用操作为准；可复用资源结构本身并不是完整的写入请求。

POSTUpload Attachment/api/v1/attachments:upload

结构与字段

object

字段	类型 / 是否必需	描述
`spec`	allOf UploadAttachmentSpec	Starts a new upload. The same call may also carry data and finish_write.
`uploadId`	string	Continues the upload identified by a previous response.
`writeOffset`	string 必需	Required. Zero-based byte offset at which data is written. Must equal the committed size, except when retrying the most recently accepted chunk with identical bytes and offset, which is accepted without writing again.
`data`	string (bytes)	Optional. File bytes, at most max_chunk_size long. With no data and finish_write false, the call reports progress without writing, and write_offset is ignored.
`finishWrite`	boolean	Optional. Finalize the upload after writing data. The committed size must then equal total_size. Any later call for the same upload_id returns the created attachment.

完整结构

约束与嵌套结构请以这份完整 JSON 定义为准。字段出现在这里，并不意味着每位调用者都能修改它。

{
  "required": [
    "writeOffset"
  ],
  "type": "object",
  "properties": {
    "spec": {
      "allOf": [
        {
          "$ref": "#/components/schemas/UploadAttachmentSpec"
        }
      ],
      "description": "Starts a new upload. The same call may also carry data and finish_write."
    },
    "uploadId": {
      "type": "string",
      "description": "Continues the upload identified by a previous response."
    },
    "writeOffset": {
      "type": "string",
      "description": "Required. Zero-based byte offset at which data is written. Must equal the\n committed size, except when retrying the most recently accepted chunk\n with identical bytes and offset, which is accepted without writing again."
    },
    "data": {
      "type": "string",
      "description": "Optional. File bytes, at most max_chunk_size long. With no data and\n finish_write false, the call reports progress without writing, and\n write_offset is ignored.",
      "format": "bytes"
    },
    "finishWrite": {
      "type": "boolean",
      "description": "Optional. Finalize the upload after writing data. The committed size must\n then equal total_size. Any later call for the same upload_id returns the\n created attachment."
    }
  }
}