Копирование файла
Операция Copy File копирует большой двоичный объект или файл в целевой файл в учетной записи хранения. Эта операция поддерживается в версии 2015-02-21 и более поздних версиях для общих папок с включенным протоколом SMB и поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.
Доступность протокола
| Протокол общей папки с включенным доступом | Доступный |
|---|---|
| SMB |
|
| NFS |
|
Просьба
Запрос Copy File создается следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS.
Начиная с версии 2013-08-15, можно указать подписанный URL-адрес для целевого файла, если он находится в той же учетной записи, что и исходный файл. Начиная с версии 2015-04-05, можно также указать подписанный URL-адрес для целевого файла, если он находится в другой учетной записи хранения.
| Метод | URI запроса | ВЕРСИЯ HTTP |
|---|---|---|
| КЛАСТЬ | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Замените компоненты пути, отображаемые в URI запроса собственным, следующим образом:
| Компонент path | Описание |
|---|---|
myaccount |
Имя учетной записи хранения. |
myshare |
Имя общей папки. |
mydirectorypath |
Необязательный. Путь к родительскому каталогу. |
myfile |
Имя файла. |
Дополнительные сведения об ограничениях именования путей см. в разделе Именование и ссылка на общие папки, каталоги, файлы и метаданные.
Параметры URI
Можно указать следующие дополнительные параметры в URI запроса:
| Параметр | Описание |
|---|---|
timeout |
Необязательный. Параметр timeout выражается в секундах. Дополнительные сведения см. в статье Настройка времени ожидания операций службы "Файлы Azure". |
Заголовки запросов
Обязательные и необязательные заголовки запросов описаны в следующих таблицах:
Общие заголовки запросов
| Заголовок запроса | Описание |
|---|---|
Authorization |
Обязательно. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
Date или x-ms-date |
Обязательно. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
x-ms-version |
Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Эта операция поддерживается в версии 2015-02-21 и более поздних версиях для общих папок с включенным протоколом SMB и поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS. Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure. |
x-ms-meta-name:value |
Необязательный. Указывает пары name/value, связанные с файлом в виде метаданных. Если пары имени и значения не указаны, операция копирует метаданные из исходного большого двоичного объекта или файла в целевой файл. Если задана одна или несколько пар имени или значения, целевой файл создается с указанными метаданными, а метаданные не копируются из исходного большого двоичного объекта или файла. Имена метаданных должны соответствовать правилам именования для идентификаторов C#. Метаданные файлов, указанные с помощью файлов Azure, недоступны из клиента SMB. |
x-ms-copy-source:name |
Обязательно. Указывает URL-адрес исходного файла или большого двоичного объекта до 2 кибибайтов (KiB). Чтобы скопировать файл в другой файл в той же учетной записи хранения, можно использовать общий ключ для авторизации исходного файла. Если вы копируете файл из другой учетной записи хранения или копируете большой двоичный объект из той же учетной записи хранения или другой учетной записи хранения, необходимо авторизовать исходный файл или большой двоичный объект с помощью подписанного URL-адреса. Если источник является общедоступным BLOB-объектом, для выполнения операции копирования не требуется авторизация. Вы также можете указать файл в моментальном снимке общего ресурса в качестве источника копирования. Ниже приведены некоторые примеры URL-адресов исходного объекта:
|
x-ms-lease-id:<ID> |
Требуется, если целевой файл имеет активную аренду. Доступно для версии 2019-02-02 и более поздних версий. Идентификатор аренды, указанный для этого заголовка, должен соответствовать идентификатору аренды целевого файла. Если запрос не содержит идентификатор аренды или идентификатор недействителен, операция завершается ошибкой с кодом состояния 412 (сбой условия). Если этот заголовок указан, а целевой файл в настоящее время не имеет активной аренды, операция завершается ошибкой с кодом состояния 412 (сбой предварительных условий). Этот заголовок игнорируется, если целевой файл находится в общей папке с включенным протоколом NFS, который не поддерживает аренду файлов. |
x-ms-file-creation-time |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок указывает свойство для времени создания в формате UTC, которое необходимо задать в целевом файле. Можно использовать значение source для копирования времени создания из исходного файла в целевой файл. |
x-ms-file-last-write-time |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок указывает свойство для последнего времени записи в формате UTC, которое необходимо задать в целевом файле. Значение source можно использовать для копирования последнего времени записи из исходного файла в целевой файл. |
x-ms-client-request-id |
Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-KiB, записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitorхранилища BLOB-объектов Azure. |
x-ms-file-request-intent |
Требуется, если заголовок Authorization указывает токен OAuth. Допустимое значение равно backup. Этот заголовок указывает, что Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action или Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action следует предоставить, если они включены в политику RBAC, назначенную удостоверению, авторизованному с помощью заголовка Authorization. Доступно для версии 2022-11-02 и более поздних версий. |
x-ms-allow-trailing-dot: { <Boolean> } |
Необязательный. Версия 2022-11-02 и более поздних версий. Логическое значение указывает, следует ли обрезать конечную точку в URL-адресе запроса. Этот заголовок игнорируется, если целевой объект находится в общей папке с включенным протоколом NFS, который поддерживает конечную точку по умолчанию. Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Необязательный. Версия 2022-11-02 и более поздних версий. Логическое значение указывает, следует ли обрезать конечную точку в исходном URL-адресе. Этот заголовок следует указать, только если источник копирования находится в общей папке Azure. Этот заголовок не поддерживается для любого другого типа источника копирования. Этот заголовок игнорируется, если источник копирования находится в общей папке с включенным протоколом NFS, который поддерживает конечную точку по умолчанию. Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные. |
Только заголовки запросов SMB
| Заголовок запроса | Описание |
|---|---|
x-ms-file-change-time: { <DateTime> ¦ source } |
Необязательный. Версия 2021-06-08 и более поздних версий. Свойство времени изменения в формате UTC для файла, отформатированного в формате ISO 8601. Значение source можно использовать для копирования времени изменения из исходного файла в целевой файл. Метка времени по умолчанию — это время запроса. |
x-ms-file-permission-copy-mode: { source ¦ override } |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Определяет поведение копирования дескриптора безопасности файла:
|
x-ms-file-permission: { <SDDL> ¦ <binary> } |
Обязательный, если x-ms-file-permission-copy-mode указан как override и x-ms-file-permission-key не указан. Доступно для версии 2019-07-07 и более поздних версий. Это разрешение является дескриптором безопасности для файла, указанного в языке определения дескриптора безопасности (SDDL) или (версия 2025-01-05 или более поздней) в формате дескриптора безопасности в кодировке Base64 двоичного дескриптора безопасности. Можно указать формат, используемый с заголовком x-ms-file-permission-format. Этот заголовок можно использовать, если размер разрешений составляет 8 кибибайт (KiB) или меньше. В противном случае можно использовать x-ms-file-permission-key. Если он указан, он должен иметь владельца, группу и список управления доступом (DACL). Можно указать только одну из x-ms-file-permission или x-ms-file-permission-key. |
x-ms-file-permission-key |
Обязательный, если x-ms-file-permission-copy-mode указан как override и x-ms-file-permission не указан. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок задает ключ разрешения для файла. Этот ключ можно создать с помощью операции Create Permission.Можно указать только одну из x-ms-file-permission или x-ms-file-permission-key. |
x-ms-file-permission-format: { sddl ¦ binary } |
Необязательный. Версия 2025-01-05 или более поздняя. Указывает, является ли значение, переданное в x-ms-file-permission, в SDDL или в двоичном формате. Если этот заголовок не задан, используется значение по умолчанию sddl. |
x-ms-file-attributes |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок указывает атрибуты файловой системы, заданные в целевом файле. См. список доступных атрибутов . Можно использовать значение source для копирования атрибутов из исходного файла в целевой файл. Значение none можно использовать для очистки всех атрибутов в целевом файле. |
x-ms-file-copy-ignore-readonly |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Это логическое значение указывает, следует ли учитывать атрибут ReadOnly в предварительном целевом файле. Если это true, операция копирования завершается успешно. В противном случае предыдущий файл в месте назначения с набором атрибутов ReadOnly приводит к сбою операции копирования. |
x-ms-file-copy-set-archive |
Необязательный. Доступно для версии 2019-07-07 и более поздних версий. Это логическое значение указывает, следует ли задать атрибут Archive независимо от значения заголовка x-ms-file-attributes. |
Только заголовки запросов NFS
Текст запроса
Никакой.
Ответ
Ответ включает код состояния HTTP и набор заголовков ответа.
Код состояния
Успешная операция возвращает код состояния 202 (принято). Сведения о кодах состояния см. в коды состояния и коды ошибок.
Заголовки ответа
Ответ для этой операции содержит заголовки в следующих таблицах. Ответ также может включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.
Общие заголовки ответов
| Заголовок ответа | Описание |
|---|---|
ETag |
Если операция копирования завершена, содержит значение ETag целевого файла. Если операция копирования не завершена, содержит значение ETag пустого файла, созданного в начале операции. |
Last-Modified |
Возвращает дату и время завершения операции копирования в целевой файл. |
x-ms-request-id |
Уникально идентифицирует выполненный запрос. Этот заголовок можно использовать для устранения неполадок запроса. Дополнительные сведения см. в статье Устранение неполадок с операциями API. |
x-ms-version |
Указывает версию файлов Azure, которая используется для выполнения запроса. |
Date |
Значение даты и времени в формате UTC, указывающее время отправки ответа службой. |
x-ms-copy-id: <id> |
Предоставляет строковый идентификатор для этой операции копирования. Используйте Get File или Get File Properties для проверки состояния этой операции копирования или передачи Abort Copy File для отмены ожидающей операции копирования. |
x-ms-copy-status: <success ¦ pending> |
Указывает состояние операции копирования со следующими значениями: - success: операция копирования завершена успешно.- pending: операция копирования по-прежнему выполняется. |
x-ms-client-request-id |
Можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id, если оно присутствует в запросе, а значение — не более 1024 видимых символов ASCII. Если в запросе отсутствует заголовок x-ms-client-request-id, этот заголовок не будет присутствовать в ответе. |
Заголовки ответов SMB только
Никакой.
Заголовки ответов NFS только
Никакой.
Текст ответа
Никакой
Пример ответа
Response Status:
HTTP/1.1 202 Accepted
Response Headers:
Last-Modified: <date>
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2015-02-21
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>
Авторизация
Эта операция может вызываться владельцем учетной записи или клиентом, имеющим подписанный URL-адрес, имеющий разрешение на запись в целевой файл или его общую папку. Обратите внимание, что подпись общего доступа, указанная в запросе, применяется только к целевому файлу.
Доступ к исходному файлу или большому двоичному объекту разрешен отдельно, как описано в сведениях о заголовке запроса x-ms-copy-source.
В следующей таблице описывается, как можно авторизовать конечные и исходные объекты для операции Copy File:
| Файл | Авторизация с помощью общего ключа или общего ключа Lite | Авторизация с помощью подписанного URL-адреса | Общедоступный объект, не требующий авторизации |
|---|---|---|---|
| Целевой файл | Да | Да | Неприменимо |
| Исходный файл в той же учетной записи | Да | Да | Неприменимо |
| Исходный файл в другой учетной записи | Нет | Да | Неприменимо |
| Исходный большой двоичный объект в той же учетной записи или другой учетной записи | Нет | Да | Да |
Атрибуты файловой системы
| Атрибут | Атрибут файла Win32 | Определение |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Файл доступен только для чтения. Приложения могут считывать файл, но не могут записывать в него или удалять его. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
Файл скрыт. Он не включен в обычный список каталогов. |
System |
FILE_ATTRIBUTE_SYSTEM |
Операционная система использует часть файла или использует этот файл исключительно. |
None |
FILE_ATTRIBUTE_NORMAL |
Файл не имеет других атрибутов. Этот атрибут действителен только в том случае, если он используется отдельно. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
Файл является архивным файлом. Приложения обычно используют этот атрибут для пометки файлов для резервного копирования или удаления. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
Файл используется для временного хранилища. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Данные файла недоступны немедленно. Этот атрибут файловой системы в основном обеспечивает совместимость с Windows. Файлы Azure не поддерживают его с параметрами автономного хранилища. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
Служба индексирования содержимого не будет индексировать файл. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
Средство проверки целостности фоновых данных не считывает поток данных пользователя. Этот атрибут файловой системы в основном обеспечивает совместимость с Windows. |
Разрешения ФАЙЛА POSIX (режим)
Разрешения POSIX-файла можно указать в 12-разрядном числовом формате или в символьном формате rwx. Примеры:
- "0644" или "rw-r-r--": пользователь (владелец файла) имеет разрешение на чтение, запись. Группа имеет разрешение на чтение. Другие имеют разрешение на чтение.
- "0755" или "rwxr-xr-x": пользователь (владелец файла) имеет разрешение на чтение, запись и выполнение. Группа имеет разрешение на чтение и выполнение. Другие имеют разрешение на чтение и выполнение.
Числовый восьмеричный формат
Три наименьших октальных числа представляют разрешения для владельца или пользователя, группы и других пользователей и указываются с помощью восьмеричного числа (0-7), сформированного с помощью побитового сочетания "4" (чтение), "2" (запись), "1" (выполнение). Наибольшее число порядка (0–7) используется для указания сочетания разрешений "4" (SetUID), "2" (SetGID), "1" (StickyBit).
| Формат | Разрешение |
|---|---|
| 0700 | Пользователь (владелец файла) имеет разрешение на чтение, запись и выполнение. |
| 0400 | У пользователя есть разрешение на чтение. |
| 0200 | У пользователя есть разрешение на запись. |
| 0100 | У пользователя есть разрешение на выполнение. |
| 0070 | Группа имеет разрешение на чтение, запись и выполнение. |
| 0040 | Группа имеет разрешение на чтение. |
| 0020 | Группа имеет разрешение на запись. |
| 0010 | Группа имеет разрешение на выполнение. |
| 0007 | Другие имеют разрешение на чтение, запись и выполнение. |
| 0004 | Другие имеют разрешение на чтение. |
| 0002 | Другие имеют разрешение на запись. |
| 0001 | Другие имеют разрешение на выполнение. |
| 4000 | Задайте эффективный идентификатор пользователя в файле. |
| 2000 | Задайте действующий идентификатор группы в файле. |
| 1000 | Задайте для указания, что файл можно удалить или переименовать только владельцем файла, владельцем каталога или корневым пользователем. |
Символьный формат rwx
Разрешения для владельца или пользователя, группы и других пользователей указываются с помощью сочетания символов "r" (чтение), "w" (запись) и "x" (выполнение).
| Формат | Разрешение |
|---|---|
| rwx------ | Пользователь (владелец файла) имеет разрешение на чтение, запись и выполнение. |
| r-------- | У пользователя есть разрешение на чтение. |
| -w------- | У пользователя есть разрешение на запись. |
| --x------ | У пользователя есть разрешение на выполнение. |
| ---rwx--- | Группа имеет разрешение на чтение, запись и выполнение. |
| ---r----- | Группа имеет разрешение на чтение. |
| ----w---- | Группа имеет разрешение на запись. |
| -----x--- | Группа имеет разрешение на выполнение. |
| ------rwx | Другие пользователи имеют разрешение на чтение, запись и выполнение. |
| ------r-- | Другие имеют разрешение на чтение. |
| -------w- | Другие имеют разрешение на запись. |
| --------x | Другие имеют разрешение на выполнение. |
Замечания
Операция Copy File может завершиться асинхронно. Можно использовать идентификатор копирования, возвращаемый заголовком ответа x-ms-copy-id, чтобы проверить состояние операции копирования или отменить его. Файлы Azure копируют файлы на основе лучших усилий.
Если целевой файл существует, он перезаписывается. Невозможно изменить целевой файл во время выполнения операции копирования.
Операция Copy File всегда копирует весь исходный большой двоичный объект или файл. Копирование диапазона байтов или набора блоков не поддерживается.
Источником операции Copy File может быть файл, который находится в моментальном снимке общего ресурса. Назначение операции Copy File не может быть файлом, который находится в моментальном снимке общего ресурса.
Если источник операции копирования предоставляет ETag значения, если во время выполнения операции изменения отсутствуют, она завершается ошибкой. Попытка изменить целевой файл во время выполнения операции копирования завершается ошибкой с кодом состояния 409 (конфликт).
Значение ETag для целевого файла изменяется при запуске операции Copy File. Он продолжает часто изменяться во время операции копирования.
Копирование свойств и метаданных
При копировании большого двоичного объекта или файла в целевой файл копируются следующие системные свойства с теми же значениями:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
Целевой файл всегда совпадает с размером исходного большого двоичного объекта или файла. Значение заголовка Content-Length для целевого файла соответствует значению этого заголовка для исходного большого двоичного объекта или файла.
Копирование арендованного большого двоичного объекта или файла в файл
Операция Copy File считывается только из исходного большого двоичного объекта или файла, поэтому аренда исходного объекта не влияет на операцию. Операция Copy File сохраняет значение ETag исходного большого двоичного объекта или файла при запуске операции. Если значение ETag изменяется до завершения операции копирования, операция завершается ошибкой. Вы можете предотвратить изменения исходного большого двоичного объекта файла, арендовав его во время операции копирования.
Если целевой файл имеет активную бесконечную аренду, необходимо указать его идентификатор аренды в вызове операции Copy File. Пока операция копирования ожидается, любая операция аренды в целевом файле завершается ошибкой с кодом состояния 409 (конфликт). Бесконечная аренда целевого файла блокируется таким образом во время операции копирования, независимо от того, копируетесь ли вы в целевой файл, имеющий другое имя от источника или копирование в целевой файл, который совпадает с именем источника. Если клиент указывает идентификатор аренды файла, который еще не существует, Служба файлов Azure возвращает код состояния 412 (сбой предварительных условий).
Работа с ожидающей операцией копирования
Операция Copy File может завершить копирование файлов асинхронно. Используйте следующую таблицу, чтобы определить следующий шаг на основе кода состояния, который Copy File возвращает:
| Код состояния | Значение |
|---|---|
| 202 (принято), x-ms-copy-status: success | Операция копирования завершена успешно. |
| 202 (принято), состояние x-ms-copy-status: ожидание | Операция копирования не завершена. Опрос целевого большого двоичного объекта с помощью Get File Properties для проверки x-ms-copy-status до завершения или сбоя операции копирования. |
| 4xx, 500 или 503 | Сбой операции копирования. |
Во время и после операции Copy File свойства целевого файла содержат идентификатор копирования операции Copy File и URL-адрес исходного большого двоичного объекта или файла. После завершения операции файлы Azure записывают значение времени и результата (success, failedили aborted) в свойства целевого файла. Если операция имеет failed результат, заголовок x-ms-copy-status-description содержит строку сведений об ошибке.
Ожидающая операция Copy File имеет двухнедельное время ожидания. Попытка копирования, которая не завершилась после двух недель ожидания и оставляет пустой файл с полем x-ms-copy-status, равным failed, и поле x-ms-status-description имеет значение 500 (OperationCancelled). Периодические неустранимые ошибки, которые могут возникать во время операции копирования, могут препятствовать выполнению операции, но не привести к сбою. В этих случаях x-ms-copy-status-description описывает периодические ошибки.
Любая попытка изменить целевой файл во время операции копирования завершается ошибкой с кодом состояния 409 (конфликт), "Копировать файл в процессе выполнения".
При вызове операции Abort Copy File появится заголовок x-ms-copy-status:aborted. Целевой файл будет иметь нетронутые метаданные и длину файла в 0 байтов. Вы можете повторить исходный вызов Copy File, чтобы повторить операцию.
Выставления счетов
Целевая учетная запись операции Copy File взимается за одну транзакцию, чтобы запустить операцию. Целевая учетная запись также вызывает одну транзакцию для каждого запроса, чтобы отменить или запросить состояние операции копирования.
Если исходный файл или большой двоичный объект находится в другой учетной записи, исходная учетная запись несет затраты на транзакции. Кроме того, если исходные и целевые учетные записи находятся в разных регионах (например, северная часть США и южная часть США), пропускная способность, используемая для передачи запроса, взимается в исходную учетную запись в качестве исходящего трафика. Исходящие данные между учетными записями в одном регионе бесплатны.