使用Azure Storage Copy Blob From Url REST API时x-ms-requires-sync标头报错

问题 #

我通过带x-ms-copy-source标头的PUT REST API，将互联网上可公开访问的大文件上传至Azure Blob，PUT URI包含SAS token，使用以下标头时可正常运行：

x-ms-version: 2023-11-03
x-ms-blob-type: BlockBlob
x-ms-copy-source: https://mypublicfile/filename.csv

但添加x-ms-requires-sync:true标头后，出现如下错误：

<?xml version="1.0" encoding="utf-8"?>
<Error>
    <Code>InvalidHeaderValue</Code>
    <Message>The value for one of the HTTP headers is not in the correct format.
RequestId:935f1ff5-a01e-0065-6f34-80e89b000000
Time:2024-03-27T10:51:11.7886167Z</Message>
    <HeaderName>x-ms-requires-sync</HeaderName>
    <HeaderValue>true</HeaderValue>
</Error>

请问我哪里操作有误？此外，除了Blob存储的官方最大Blob大小限制外，是否存在其他大小限制？目前5GiB以内的文件可正常上传，但更大的文件会报错。

解答 #

1. x-ms-requires-sync标头错误的原因 #

你混淆了两个不同的Azure Blob存储API：

• 你当前使用的是Put Blob from URL（PUT请求，带x-ms-copy-source），这个API用于直接从源URL创建单个Blob，它并不支持x-ms-requires-sync标头。
• x-ms-requires-sync是Copy Blob（POST请求）操作的专属标头，用于强制同步完成复制操作。

在Put Blob from URL请求中添加不属于它的标头，就会触发InvalidHeaderValue错误。只需移除这个标头即可解决问题。

2. 大文件上传的额外限制 #

Put Blob from URL操作有单次请求最大5GiB的限制，这就是你上传超过5GiB文件失败的原因。这个限制不属于Blob存储的全局最大Blob大小（对于Block Blob是190.7TiB），而是该特定API的单次操作上限。

如果要上传超过5GiB的文件，需要改用分块上传方案：

• 使用Put Block from URL API，将大文件分割成多个不超过5GiB的块（每个块大小最多5GiB），分别从源URL复制到Blob存储的块中。
• 所有块复制完成后，调用Put Block List API将这些块组装成完整的Blob。

内容的提问来源于stack exchange，提问作者Jaap Mosselman