Копирование файла

Статья
03/29/2023

Операция Copy File копирует большой двоичный объект или файл в целевой файл в учетной записи хранения.

Доступно в версии 21.02.2015 и более поздних версиях.

Доступность протокола

Включенный протокол общей папки	Доступно
SMB
NFS

Запрос

Запрос можно создать Copy File следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS.

Начиная с версии 2013-08-15, можно указать подписанный URL-адрес для целевого файла, если он находится в той же учетной записи, что и исходный файл. Начиная с версии 2015-04-05, вы также можете указать подписанный URL-адрес для целевого файла, если он находится в другой учетной записи хранения.

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	HTTP/1.1

Замените компоненты пути, показанный в URI запроса, следующим образом:

Компонент path	Описание
`myaccount`	Имя учетной записи хранения.
`myshare`	Имя файлового ресурса.
`mydirectorypath`	Необязательный элемент. Родительский каталог файла.
`myfile`	Имя файла.

Дополнительные сведения об ограничениях именования путей см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

Параметры универсального кода ресурса (URI)

В запросе URI можно указать следующие дополнительные параметры.

Параметр	Описание
`timeout`	Необязательный элемент. Параметр времени ожидания указывается в секундах. Дополнительные сведения см. в разделе Установка времени ожидания для операций Файлы Azure.

Заголовки запросов

В следующей таблице описаны обязательные и необязательные заголовки запросов.

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Эта операция доступна только в версии 2015-02-21 и более поздних версиях. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-meta-name:value`	Необязательный элемент. Указывает пары "имя-значение", связанные с файлом в качестве метаданных. Если пары "имя-значение" не указаны, операция копирует метаданные из исходного большого двоичного объекта или файла в целевой файл. Если указана одна или несколько пар "имя-значение", целевой файл создается с указанными метаданными, а метаданные не копируются из исходного BLOB-объекта или файла. Имена метаданных должны соответствовать правилам именования для идентификаторов C#. Обратите внимание, что метаданные файла, указанные с помощью Файлы Azure, недоступны из клиента SMB.
`x-ms-copy-source:name`	Обязательный. Указывает URL-адрес исходного файла или большого двоичного объекта длиной до 2 киб (КиБ). Чтобы скопировать файл в другой файл в той же учетной записи хранения, можно использовать общий ключ для авторизации исходного файла. При копировании файла из другой учетной записи хранения или копирования большого двоичного объекта из той же или другой учетной записи хранения необходимо авторизовать исходный файл или большой двоичный объект с помощью подписанного URL-адреса. Если источником является общедоступный BLOB-объект, для выполнения операции копирования авторизация не требуется. Вы также можете указать файл в общей snapshot в качестве источника копирования. Ниже приведены некоторые примеры URL-адресов исходного объекта: `https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile` `https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken` `http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>`
`x-ms-lease-id:<ID>`	Требуется, если целевой файл имеет активную аренду. Доступно для версии 2019-02-02 и более поздних версий. Идентификатор аренды, указанный для этого заголовка, должен совпадать с идентификатором аренды целевого файла. Если запрос не содержит идентификатор аренды или идентификатор недопустим, операция завершается ошибкой с кодом состояния 412 (сбой условия). Если этот заголовок указан и целевой файл в настоящее время не имеет активной аренды, операция завершается ошибкой с кодом состояния 412 (сбой предварительного условия).
`x-ms-file-permission-copy-mode: { source ¦ override }`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Определяет поведение копирования дескриптора безопасности файла: `source`: дескриптор безопасности в целевом файле копируется из исходного файла. `override`: дескриптор безопасности в целевом файле определяется с помощью заголовка `x-ms-file-permission` или `x-ms-file-permission-key` .
`x-ms-file-permission`	Требуется, если `x-ms-file-permission-copy-mode` параметр указан как `override` , а `x-ms-file-permission-key` не указан. Доступно для версии 2019-07-07 и более поздних версий. Это разрешение является дескриптором безопасности для файла, указанного на языке определения дескриптора безопасности (SDDL). Этот заголовок можно использовать, если размер разрешений составляет 8 кибит (КиБ) или меньше. В противном случае можно использовать `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-copy-ignore-readonly`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Это логическое значение указывает, следует ли `ReadOnly` учитывать атрибут в уже существовавовавев файле назначения. Если это `true`значение , операция копирования завершается успешно. В противном случае предыдущий файл в месте назначения с заданным атрибутом `ReadOnly` приведет к сбою операции копирования.
`x-ms-file-attributes`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок указывает атрибуты файловой системы, которые необходимо задать в целевом файле. См. список доступных атрибутов. Для копирования атрибутов `source` из исходного файла в целевой можно использовать значение . Для очистки всех атрибутов `none` в целевом файле можно использовать значение .
`x-ms-file-creation-time`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок задает свойство времени создания в формате UTC, которое необходимо задать для целевого файла. Для копирования `source` времени создания из исходного файла в целевой можно использовать значение .
`x-ms-file-last-write-time`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Этот заголовок задает свойство для времени последней записи в формате UTC, которое необходимо задать в целевом файле. Можно использовать значение `source` , чтобы скопировать время последней записи из исходного файла в целевой файл.
`x-ms-file-copy-set-archive`	Необязательный элемент. Доступно для версии 2019-07-07 и более поздних версий. Это логическое значение указывает, следует ли `Archive` задавать атрибут независимо от значения заголовка `x-ms-file-attributes` .
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 КиБ символов, которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Хранилище BLOB-объектов Azure.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Необязательный элемент. Версия 08.06.2021 и более поздняя. Свойство времени изменения в формате UTC для файла, отформатированного в формате ISO 8601. Значение можно использовать для копирования `source` времени изменения из исходного файла в целевой. Метка времени по умолчанию — это время запроса.
`x-ms-file-request-intent`	Требуется, если `Authorization` заголовок указывает токен OAuth. Допустимое значение — `backup`. Этот заголовок указывает, что `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` или должны быть предоставлены, если они включены в политику RBAC, назначенную удостоверению, которое авторизовано с помощью заголовка `Authorization` . Доступно для версии 2022-11-02 и более поздних версий.
`x-ms-allow-trailing-dot: { <Boolean> }`	Необязательный элемент. Версия 2022-11-02 и более поздние версии. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Необязательный элемент. Версия 2022-11-02 и более поздние версии. Логическое значение указывает, следует ли обрезать конечную точку в исходном URL-адресе. Этот заголовок следует указывать только в том случае, если источником копирования является файл Azure. Этот заголовок не поддерживается для любого другого типа источника копирования. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

Текст запроса

Нет.

Ответ

Ответ включает код состояния 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` отсутствует в запросе, этот заголовок не будет присутствовать в ответе.

Текст ответа

Нет

Пример ответа

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-адрес, который имеет разрешение на запись в целевой файл или его общую папку. Обратите внимание, что подписанный URL-адрес, указанный в запросе, применяется только к целевому файлу.

Доступ к исходному файлу или большому двоичному объекту авторизован отдельно, как описано в сведениях о заголовке x-ms-copy-sourceзапроса .

В следующей таблице показано, как можно авторизовать целевые и исходные Copy File объекты для операции.

File	Авторизация с помощью общего ключа или общего ключа Lite	Авторизация с подписанным URL-адресом	Открытый объект, не требующий авторизации
Целевой файл	Да	Да	Неприменимо
Исходный файл в той же учетной записи	Да	Да	Неприменимо
Исходный файл в другой учетной записи	Нет	Да	Неприменимо
Исходный BLOB-объект в той же или другой учетной записи	Нет	Да	Да

Атрибуты файловой системы

attribute	Атрибут файла 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.

Операция Copy File может завершиться асинхронно. Идентификатор копирования, возвращаемый заголовком x-ms-copy-id ответа, можно использовать для проверка состояния операции копирования или для ее отмены. Файлы Azure копирует файлы на основе наилучших усилий.

Если целевой файл существует, он будет перезаписан. Вы не можете изменить целевой файл, пока выполняется операция копирования.

Операция Copy File всегда копирует весь исходный BLOB-объект или файл. Копирование диапазона байтов или набора блоков не поддерживается.

Источником Copy File операции может быть файл, который находится в общей snapshot. Назначением Copy File операции не может быть файл, который находится в общей snapshot.

Если источник операции копирования предоставляет ETag значения, то при наличии изменений в источнике во время выполнения операции произойдет сбой. Попытка изменить целевой файл во время выполнения операции копирования завершится ошибкой с кодом состояния 409 (конфликт).

Значение ETag целевого файла изменяется при Copy File запуске операции. Он продолжает часто изменяться во время операции копирования.

Копирование свойств и метаданных

При копировании большого двоичного объекта или файла в целевой файл копируются следующие системные свойства с теми же значениями:

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
Content-Disposition

Целевой файл всегда имеет тот же размер, что и исходный большой двоичный объект или файл. Значение заголовка Content-Length для целевого файла совпадает со значением этого заголовка для исходного большого двоичного объекта или файла.

Копирование арендованного BLOB-объекта или файла в файл

Операция Copy File считывает только из исходного BLOB-объекта или файла, поэтому аренда исходного объекта не влияет на операцию. Операция Copy File сохраняет ETag значение исходного большого двоичного объекта или файла при запуске операции. ETag Если значение изменится до завершения операции копирования, операция завершается ошибкой. Вы можете предотвратить изменения в исходном BLOB-объекте файла, арендовав его во время операции копирования.

Если целевой файл имеет активную бесконечную аренду, необходимо указать его идентификатор аренды в вызове Copy File операции. Пока операция копирования находится в состоянии ожидания, любая операция аренды в целевом файле завершается ошибкой с кодом состояния 409 (конфликт). Таким образом, во время операции копирования блокируется бесконечная аренда целевого файла независимо от того, копируете ли вы в целевой файл, имя которого отличается от исходного, или копирование в целевой файл с тем же именем, что и у источника. Если клиент указывает идентификатор аренды для файла, который еще не существует, Файлы Azure возвращает код состояния 412 (сбой условия).

Работа с ожидающей операцией копирования

Операция Copy File может завершить асинхронное копирование файлов. Используйте следующую таблицу, чтобы определить следующий шаг на основе возвращаемого кода Copy File состояния:

Код состояния	Значение
202 (принято), x-ms-copy-status: success	Операция копирования успешно завершена.
202 (принято), x-ms-copy-status: pending	Операция копирования не завершена. Опрашивает целевой BLOB-объект с помощью `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 записи операции взимается плата за одну транзакцию для запуска операции. Целевая учетная запись также выполняет одну транзакцию для каждого запроса отмены или запроса состояния операции копирования.

Если исходный файл или большой двоичный объект находится в другой учетной записи, на исходную учетную запись взимается плата за транзакции. Кроме того, если исходная и целевая учетные записи находятся в разных регионах (например, в северной части США и южной части США), пропускная способность, используемая для передачи запроса, взимается в исходную учетную запись как исходящий трафик. Передача исходящих данных между учетными записями в пределах одного и того же региона осуществляется бесплатно.