Создание файла
Операция Create File создает новый файл или заменяет файл. При вызове Create Fileфайл инициализируется только. Чтобы добавить содержимое в файл, вызовите операцию Put Range.
Доступность протокола
| Протокол общей папки с включенным доступом | Доступный |
|---|---|
| SMB |
|
| NFS |
|
Просьба
Вы можете создать запрос Create File, выполнив указанные ниже действия. Рекомендуется использовать ПРОТОКОЛ HTTPS.
| Метод | URI запроса | ВЕРСИЯ HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Замените компоненты пути, отображаемые в URI запроса собственным, как описано в следующей таблице:
| Компонент path | Описание |
|---|---|
myaccount |
Имя учетной записи хранения. |
myshare |
Имя общей папки. |
mydirectorypath |
Необязательный. Путь к каталогу, в котором создается файл. Если путь к каталогу опущен, файл будет создан в указанной общей папке. Если указан каталог, он уже должен существовать в общей папке, прежде чем создать файл. |
myfile |
Имя создаваемого файла. |
Сведения об ограничениях именования путей см. в разделе Имя и справочные ресурсы, каталоги, файлы и метаданные.
Параметры URI
Можно указать следующие дополнительные параметры в URI запроса:
| Параметр | Описание |
|---|---|
timeout |
Необязательный. Параметр timeout выражается в секундах. Дополнительные сведения см. в разделе Установка времени ожидания для операций службы файлов. |
Заголовки запросов
Обязательные и необязательные заголовки запросов описаны в следующей таблице:
| Заголовок запроса | Описание |
|---|---|
Authorization |
Обязательно. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
Date или x-ms-date |
Обязательно. Указывает время универсального времени (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
x-ms-version |
Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure. |
Content-Length |
Необязательный. Должно быть равно нулю, если присутствует. |
x-ms-content-length: byte value |
Обязательно. Этот заголовок задает максимальный размер файла до 4 тбибайтов (TiB). |
Content-Type или x-ms-content-type |
Необязательный. Тип контента MIME файла. Тип по умолчанию — application/octet-stream. |
Content-Encoding или x-ms-content-encoding |
Необязательный. Указывает, какие кодировки содержимого были применены к файлу. Это значение возвращается клиенту при выполнении операции получения файла |
Content-Language или x-ms-content-language |
Необязательный. Указывает естественные языки, используемые этим ресурсом. |
Cache-Control или x-ms-cache-control |
Необязательный. Файлы Azure хранят это значение, но не используют или не изменяют его. |
x-ms-content-md5 |
Необязательный. Задает хэш MD5 файла. |
x-ms-content-disposition |
Необязательный. Задает заголовок Content-Disposition файла. |
x-ms-type: file |
Обязательно. Задайте для этого заголовка значение file. |
x-ms-meta-name:value |
Необязательный. Пары "Имя-значение", связанные с файлом в качестве метаданных. Имена метаданных должны соответствовать правилам именования для идентификаторов C#. Примечание. Метаданные файлов, указанные с помощью файлов Azure, недоступны из клиента SMB. |
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } |
В версии 2019-02-02–2021-04-10 этот заголовок требуется, если x-ms-file-permission-key не указан. По состоянию на версию 2021-06-08 оба заголовка являются необязательными. Это разрешение является дескриптором безопасности для файла, указанного в языке определения дескриптора безопасности (SDDL) или (версия 2024-11-04 или более поздней) в формате дескриптора безопасности в кодировке Base64 в формате дескриптора двоичной безопасности . Можно указать формат, используемый с заголовком x-ms-file-permission-format. Этот заголовок можно использовать, если размер разрешений составляет 8 кибибайт (KiB) или меньше. В противном случае можно использовать x-ms-file-permission-key. Если указать заголовок, он должен иметь владельца, группу и список управления доступом (DACL). Можно передать значение inherit для наследования от родительского каталога. |
x-ms-file-permission-format: { sddl ¦ binary } |
Необязательный. Версия 2024-11-04 или более поздняя. Указывает, является ли значение, переданное в x-ms-file-permission, в SDDL или в двоичном формате. Если x-ms-file-permission-key задано значение inherit, этот заголовок не должен быть задан. Если x-ms-file-permission-key задано любое другое значение, отличное от inherit, и если этот заголовок не задан, используется значение по умолчанию sddl. |
x-ms-file-permission-key: <PermissionKey> |
В версии 2019-02-02–2021-04-10 этот заголовок требуется, если x-ms-file-permission не указан. По состоянию на версию 2021-06-08 оба заголовка являются необязательными. Если ни заголовок не указан, значение по умолчанию inherit используется для заголовка x-ms-file-permission.Ключ можно создать, вызвав API Create Permission. |
x-ms-file-attributes |
Обязательный: версия 2019-02-02–2021-04-10. Необязательно: версия 2021-06-08 и более поздняя. Этот заголовок содержит атрибуты файловой системы, которые необходимо задать в файле. Дополнительные сведения см. в списке доступных атрибутов . Значение по умолчанию — None. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Обязательный: версия 2019-02-02–2021-04-10. Необязательно: версия 2021-06-08 и более поздняя. Свойство времени создания в формате UTC для файла. Значение now может использоваться для указания времени запроса. Значение по умолчанию — now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Обязательный: версия 2019-02-02–2021-04-10. Необязательно: версия 2021-06-08 и более поздняя. Последнее свойство записи в формате UTC для файла. Значение now можно использовать для указания времени запроса. Значение по умолчанию — now. |
x-ms-lease-id: <ID> |
Требуется, если файл имеет активную аренду. Доступно для версии 2019-02-02 и более поздних версий. |
x-ms-client-request-id |
Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitor Azure Files. |
x-ms-file-change-time: { now ¦ <DateTime> } |
Необязательный. Версия 2021-06-08 и более поздних версий. Свойство времени изменения времени в формате ISO 8601 (UTC) изменится в формате ISO 8601. Значение now можно использовать для указания времени запроса. Значение по умолчанию — now. |
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-адресе запроса. Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные. |
Текст запроса
Никакой.
Пример запроса
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1
Request Headers:
x-ms-version: 2020-02-10
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT
Content-Type: text/plain; charset=UTF-8
x-ms-content-length: 1024
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Ответ
Ответ включает код состояния HTTP и набор заголовков ответа.
Код состояния
Успешная операция возвращает код состояния 201 (создан).
Сведения о кодах состояния см. в коды состояния и коды ошибок.
Заголовки ответа
Ответ для этой операции содержит заголовки, описанные в следующей таблице. Ответ также может включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.
| Заголовок ответа | Описание |
|---|---|
ETag |
ETag содержит значение, представляющее версию файла. Значение заключено в кавычки. |
Last-Modified |
Возвращает дату и время последнего изменения файла. Формат даты следует RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция, которая изменяет каталог или его свойства, обновляет время последнего изменения. Операции с файлами не влияют на время последнего изменения каталога. |
x-ms-request-id |
Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса. Дополнительные сведения см. в статье Устранение неполадок с операциями API |
x-ms-version |
Указывает версию файлов Azure, используемую для выполнения запроса. |
Date |
Значение даты и времени в формате UTC, созданное службой, указывающее время, когда был инициирован ответ. |
x-ms-request-server-encrypted: true/false |
Версия 2017-04-17 и более поздних версий. Для этого заголовка задано значение true, если вы успешно зашифровали содержимое запроса с помощью указанного алгоритма. Если шифрование не выполнено, значение false. |
x-ms-file-permission-key |
Ключ разрешения файла. |
x-ms-file-attributes |
Атрибуты файловой системы в файле. Дополнительные сведения см. в списке доступных атрибутов . |
x-ms-file-creation-time |
Значение даты и времени в формате UTC, представляющее свойство времени создания файла. |
x-ms-file-last-write-time |
Значение даты и времени в формате UTC, представляющее свойство времени последней записи для файла. |
x-ms-file-change-time |
Значение даты и времени в формате UTC, представляющее свойство времени изменения для файла. |
x-ms-file-file-id |
Идентификатор файла. |
x-ms-file-parent-id |
Идентификатор родительского файла файла. |
x-ms-client-request-id |
Используется для устранения неполадок запросов и их соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id, если оно присутствует в запросе, а значение содержит не более 1024 видимых символов ASCII. Если в запросе отсутствует заголовок x-ms-client-request-id, он отсутствует в ответе. |
Текст ответа
Никакой.
Пример ответа
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Date: Mon, 27 Jan 2014 23:00:12 GMT
ETag: "0x8CB14C3E29B7E82"
Last-Modified: Mon, 27 Jan 2014 23:00:06 GMT
x-ms-version: 2014-02-14
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Авторизация
Только владелец учетной записи может вызвать эту операцию.
Атрибуты файловой системы
| Атрибут | Атрибут файла Win32 | Определение |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | Файл, доступный только для чтения. Приложения могут считывать файл, но они не могут записывать в него или удалять его. |
| Скрытый | FILE_ATTRIBUTE_HIDDEN | Файл скрыт. Он не включен в обычный список каталогов. |
| Система | FILE_ATTRIBUTE_SYSTEM | Файл, который операционная система использует часть или использует исключительно. |
| Никакой | FILE_ATTRIBUTE_NORMAL | Файл, который не имеет других атрибутов. Этот атрибут действителен только при использовании в одиночку. |
| Архив | FILE_ATTRIBUTE_ARCHIVE | Файл, который является архивным файлом. Приложения обычно используют этот атрибут для пометки файлов для резервного копирования или удаления. |
| Временный | FILE_ATTRIBUTE_TEMPORARY | Файл, используемый для временного хранилища. |
| Автономный | FILE_ATTRIBUTE_OFFLINE | Данные файла недоступны немедленно. Этот атрибут файловой системы представлен в основном для обеспечения совместимости с Windows. Файлы Azure не поддерживают его с параметрами автономного хранилища. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | Файл не индексируется службой индексирования содержимого. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | Поток данных пользователя, который не для чтения с помощью средства проверки целостности фоновых данных. Этот атрибут файловой системы представлен в основном для обеспечения совместимости с Windows. |
Замечания
Чтобы создать новый файл, сначала инициализируйте его, вызвав Create File и указав максимальный размер до 4 ТиБ. При выполнении этой операции не включайте содержимое в текст запроса. После создания файла вызовите Put Range добавить содержимое в файл или изменить его.
Размер файла можно изменить, вызвав Set File Properties.
Если общий ресурс или родительский каталог не существует, операция завершается ошибкой с кодом состояния 412 (сбой предварительных условий).
Заметка
Свойства файла cache-control, content-type, content-md5, content-encodingи content-language отличаются от свойств файловой системы, доступных клиентам SMB. Клиенты SMB не могут считывать, записывать или изменять эти значения свойств.
Чтобы создать файл, если существующий файл имеет активную аренду, клиент должен указать действительный идентификатор аренды для запроса. Если клиент либо не указывает идентификатор аренды, либо указывает недопустимый идентификатор аренды, Служба файлов Azure возвращает код состояния 412 (сбой предварительных условий). Если клиент указывает идентификатор аренды, но файл не имеет активной аренды, Служба файлов Azure возвращает код состояния 412 (сбой предварительных условий) в этом экземпляре. Если клиент указывает идентификатор аренды файла, который еще не существует, Служба файлов Azure возвращает код состояния 412 (предварительный сбой) для запросов, выполненных в версии 2019-02-02 и более поздних версиях.
Если существующий файл с активной арендой перезаписывается операцией Create File, аренда сохраняется в обновленном файле до тех пор, пока он не будет освобожден.
Create File не поддерживается в моментальном снимке общего ресурса, который является копией общего ресурса только для чтения. Попытка выполнить эту операцию на моментальном снимке общего ресурса завершается ошибкой с кодом состояния 400 (InvalidQueryParameterValue).