API:Upload/zh

使用POST请求来上传一个文件.

有三种方法通过API上传文件：


 * 1) 直接上传本地文件
 * 2) 从URL复制上传一个文件
 * 3) 分块上传一个本地文件

所有这些方法需要一个拥有 权限的账号.



-{zh-hans:API帮助文档; zh-hant:API說明文件;}-


上傳警告
请注意，由于许多警告条件，上传可能会失败. 这可以通过设置  来覆盖. 以下列举了一些值得注意的警告：


 * exists: 存在同名文件. 如果忽略此警告，上传的文件将替换现有文件.
 * no-change: 存在同名且内容一致的文件.
 * duplicate-version: 存在同名文件，且您上传的文件是已存在文件的一个较旧版本.
 * was-deleted: 存在已被删除的同名文件.
 * duplicate: 您要上传的文件在站点中已有同名（或不同名）版本. 上传这个文件的副本可能是不可取的.
 * duplicate-archive: 您要上传的文件在站点中曾经以不同（或相同）的名称存在，但已被删除. 这可能表明该文件不合适且不应上传.
 * badfilename: The file name supplied is not acceptable on this wiki, for instance because it contains forbidden characters

-{zh-hans:示例; zh-hant:範例;}-
任何POST请求都是一个多步骤的过程：

 使用中描述的方法之一登录.  获取：

 发送包含CSRF令牌的POST请求以上传文件.  



示例一：直接上传本地文件
直接上传文件时，请求必须使用  作为content-type或enctype，同时   不起作用.



响应


示例代码


示例二：从URL上传文件
这需要 wiki 的本地设置中的  和具有   用户权限的帐户.



响应


示例代码
<span id="Example_3:_Upload_file_in_chunks">

示例三：分块上传文件
由于在单个POST请求中上传大文件可能不可靠，因此 API 还支持分块上传模式，您可以使用文件的多部分发出多个请求. 这在 MediaWiki 1.20 及更高版本中可用，尽管在 1.25 版本之前，SVG文件无法通过分块上传上传. 这在支持 FileAPI 的浏览器中由 使用，以1MB的块上传文件，但您可以选择自己的大小. 这与stash模式结合使用，将文件分段构建，然后在最后提交.

<span id="Step_1:_Pass_content_for_the_first_chunk">

第一步：发送第一个块中的内容


对于除最后一个块之外的所有块，您将收到以下信息：

<span id="Step_2:_Pass_filekey_parameter_for_second_and_further_chunks">

第二步：为第二个以及更多块传递参数filekey
您还将从之前的 continue 结果中获得参数 ：



对最后一个块，您将接收到：

<span id="Step_3:_Final_upload_using_the_filekey_to_commit_the_upload_out_of_the_stash_area">

第三步：使用 filekey 将上传提交到存储区之外的最终上传


最终上传的结果将包括完整、准确的对象 ，这与您从非分块上传获得的结果一致.

<span id="Sample_code">

示例代码
<span id="Possible_errors">

可能的错误
另请参阅上面关于 #Upload warnings 的部分.

<span id="Parameter_history">

参数历史

 * v1.21: 启用
 * v1.19: 启用
 * v1.18: 启用
 * v1.17: 启用, ,  ,
 * v1.18: 弃用
 * v1.17: 弃用

<span id="Additional_notes">

补充资料

 * 若要检查正在上传到stash的状态或从stash发布的文件的进度，则应当使用POST请求：


 * 以下是一个multipart POST到 的示例，它展示了单个块是如何工作的. 请注意，一旦您成功上传了所有块，您必须取消存储文件以使其出现在 Wiki 中.

User-Agent: <YOUR USER-AGENT> Content-Type: multipart/form-data; boundary=--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Host: commons.wikimedia.org Cookie: Connection: Keep-Alive

--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filename" Content-Length: 20

UploadTest356456.png --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="offset" Content-Length: 1

0 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="format" Content-Length: 4

json --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="ignorewarnings" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filesize" Content-Length: 3

971 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="token" Content-Length: 42

<YOUR_CSRF_TOKEN_HERE> --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="stash" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="chunk"; filename="1.png" Content-Type: application/octet-stream Content-Length: 971

<RAW_BYTES_FROM_FILE_HERE> --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b--

<span id="See_also">

參見

 * - 允许用户登录
 * - 允许用户导入页面
 * - 依照用户组的上传限制