Kopírovat soubor
Operace Copy File zkopíruje objekt blob nebo soubor do cílového souboru v rámci účtu úložiště.
K dispozici ve verzi 2015-02-21 a novější.
Dostupnost protokolu
| Povolený protokol sdílených složek | K dispozici. |
|---|---|
| SMB |
|
| NFS |
|
Žádost
Požadavek můžete vytvořit Copy File následujícím způsobem. Doporučujeme HTTPS.
Od verze 2013-08-15 můžete pro cílový soubor zadat sdílený přístupový podpis, pokud je ve stejném účtu jako zdrojový soubor. Počínaje verzí 2015-04-05 můžete také zadat sdílený přístupový podpis pro cílový soubor, pokud je v jiném účtu úložiště.
| Metoda | Identifikátor URI žádosti | Verze PROTOKOLU HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Následujícím způsobem nahraďte komponenty cesty uvedené v identifikátoru URI požadavku vlastními:
| Komponenta Cesta | Popis |
|---|---|
myaccount |
Název vašeho účtu úložiště. |
myshare |
Název sdílené složky. |
mydirectorypath |
Nepovinný parametr. Cesta k nadřazené adresáři. |
myfile |
Název souboru. |
Podrobnosti o omezeních pojmenování cest najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich.
Parametry identifikátoru URI
V identifikátoru URI požadavku můžete zadat následující další parametry:
| Parametr | Popis |
|---|---|
timeout |
Nepovinný parametr. Parametr časového limitu je vyjádřen v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace Azure Files. |
Hlavičky požadavku
Následující tabulka popisuje požadované a volitelné hlavičky požadavků:
| Hlavička požadavku | Popis |
|---|---|
Authorization |
Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage. |
Date nebo x-ms-date |
Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage. |
x-ms-version |
Povinné pro všechny autorizované žádosti. Určuje verzi operace, která se má použít pro tento požadavek. Tato operace je k dispozici pouze ve verzi 2015-02-21 a novější. Další informace najdete v tématu Správa verzí pro služby Azure Storage. |
x-ms-meta-name:value |
Nepovinný parametr. Určuje páry název/hodnota přidružené k souboru jako metadata. Pokud nejsou zadány žádné páry název/hodnota, operace zkopíruje metadata ze zdrojového objektu blob nebo souboru do cílového souboru. Pokud je zadán jeden nebo více dvojic název/hodnota, vytvoří se cílový soubor se zadanými metadaty a metadata se nezkopírují ze zdrojového objektu blob nebo souboru. Názvy metadat musí splňovat pravidla pojmenování identifikátorů jazyka C#. Upozorňujeme, že metadata souborů zadaná prostřednictvím Azure Files nejsou přístupná z klienta SMB. |
x-ms-copy-source:name |
Povinná hodnota. Určuje adresu URL zdrojového souboru nebo objektu blob o délce až 2 kibibajtů (KiB). Pokud chcete zkopírovat soubor do jiného souboru ve stejném účtu úložiště, můžete použít sdílený klíč k autorizaci zdrojového souboru. Pokud kopírujete soubor z jiného účtu úložiště nebo pokud kopírujete objekt blob ze stejného účtu úložiště nebo jiného účtu úložiště, musíte zdrojový soubor nebo objekt blob autorizovat pomocí sdíleného přístupového podpisu. Pokud je zdrojem veřejný objekt blob, nevyžaduje se k provedení operace kopírování žádná autorizace. Jako zdroj kopie můžete také zadat soubor ve snímku sdílené složky. Tady je několik příkladů adres URL zdrojových objektů:
|
x-ms-lease-id:<ID> |
Vyžaduje se, pokud má cílový soubor aktivní zapůjčení. K dispozici pro verzi 2019-02-02 a novější. ID zapůjčení zadané pro tuto hlavičku se musí shodovat s ID zapůjčení cílového souboru. Pokud požadavek neobsahuje ID zapůjčení nebo id není platné, operace selže se stavovým kódem 412 (Předběžná podmínka selhala). Pokud je tato hlavička zadána a cílový soubor aktuálně nemá aktivní zapůjčení, operace selže se stavovým kódem 412 (Předběžná podmínka selhala). |
x-ms-file-permission-copy-mode: { source ¦ override } |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Určuje chování kopírování popisovače zabezpečení souboru:
|
x-ms-file-permission |
Povinný argument, pokud x-ms-file-permission-copy-mode je zadán jako override a x-ms-file-permission-key není zadán. K dispozici pro verzi 2019-07-07 a novější. Toto oprávnění je popisovač zabezpečení pro soubor zadaný v jazyce SDDL (Security Descriptor Definition Language). Tuto hlavičku můžete použít, pokud je velikost oprávnění 8 kibibajtů (KiB) nebo menší. V opačném případě můžete použít x-ms-file-permission-key. Pokud je zadaný, musí mít vlastníka, skupinu a volitelný seznam řízení přístupu (DACL). Všimněte si, že je možné zadat pouze jeden z x-ms-file-permission nebo x-ms-file-permission-key . |
x-ms-file-permission-key |
Povinný argument, pokud x-ms-file-permission-copy-mode je zadán jako override a x-ms-file-permission není zadán. K dispozici pro verzi 2019-07-07 a novější. Tato hlavička určuje klíč oprávnění, které se má pro soubor nastavit. Tento klíč můžete vytvořit pomocí Create Permission operace.Všimněte si, že je možné zadat pouze jeden z x-ms-file-permission nebo x-ms-file-permission-key . |
x-ms-file-copy-ignore-readonly |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Tato logická hodnota určuje, zda ReadOnly má být atribut v existujícím cílovém souboru respektován. Pokud je true, operace kopírování bude úspěšná. V opačném případě předchozí soubor v cíli se ReadOnly sadou atributů způsobí selhání operace kopírování. |
x-ms-file-attributes |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Tato hlavička určuje atributy systému souborů, které se mají nastavit v cílovém souboru. Podívejte se na seznam dostupných atributů. Hodnotu source můžete použít ke zkopírování atributů ze zdrojového souboru do cílového souboru. Hodnotu můžete použít none k vymazání všech atributů v cílovém souboru. |
x-ms-file-creation-time |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Tato hlavička určuje vlastnost času vytvoření v UTC, která se má nastavit u cílového souboru. Hodnotu source můžete použít ke zkopírování času vytvoření ze zdrojového souboru do cílového souboru. |
x-ms-file-last-write-time |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Tato hlavička určuje vlastnost pro čas posledního zápisu v UTC, která se má nastavit u cílového souboru. Hodnotu source můžete použít ke zkopírování času posledního zápisu ze zdrojového souboru do cílového souboru. |
x-ms-file-copy-set-archive |
Nepovinný parametr. K dispozici pro verzi 2019-07-07 a novější. Tato logická hodnota určuje, jestli Archive má být atribut nastaven bez ohledu na hodnotu hlavičky x-ms-file-attributes . |
x-ms-client-request-id |
Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem 1 KiB znaků, která se zaznamená v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování Azure Blob Storage. |
x-ms-file-change-time: { <DateTime> ¦ source } |
Nepovinný parametr. Verze 2021-06-08 a novější. Vlastnost času změny UTC pro soubor formátovaná ve formátu ISO 8601. Hodnotu source lze použít ke zkopírování času změny ze zdrojového souboru do cílového souboru. Výchozí časové razítko je čas požadavku. |
x-ms-file-request-intent |
Vyžaduje se, pokud Authorization hlavička určuje token OAuth. Přijatelná hodnota je backup. Tato hlavička určuje, že Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action by se měly udělit nebo Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action , pokud jsou zahrnuté v zásadách RBAC přiřazené identitě, která je autorizována pomocí hlavičky Authorization . K dispozici pro verzi 2022-11-02 a novější. |
x-ms-allow-trailing-dot: { <Boolean> } |
Nepovinný parametr. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli se má koncový tečka v adrese URL požadavku oříznout, nebo ne. Další informace najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Nepovinný parametr. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli má být koncový tečka obsažená ve zdrojové adrese URL oříznutá, nebo ne. Tato hlavička by měla být zadána pouze v případě, že zdrojem kopírování je soubor Azure. Tato hlavička není podporována pro žádný jiný typ zdroje kopírování. Další informace najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich. |
Text požadavku
Žádné
Odpověď
Odpověď obsahuje stavový kód HTTP a sadu hlaviček odpovědi.
Stavový kód
Úspěšná operace vrátí stavový kód 202 (přijato).
Informace o stavových kódech najdete v tématu Stavové kódy a kódy chyb.
Hlavičky odpovědi
Odpověď na tuto operaci obsahuje následující hlavičky. Odpověď obsahuje také další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.
| Hlavička odpovědi | Popis |
|---|---|
ETag |
Pokud je operace kopírování dokončena, obsahuje ETag hodnotu cílového souboru. Pokud operace kopírování není dokončena, obsahuje ETag hodnotu prázdného souboru vytvořeného na začátku operace. |
Last-Modified |
Vrátí datum a čas dokončení operace kopírování do cílového souboru. |
x-ms-request-id |
Jednoznačně identifikuje požadavek, který byl proveden. Tuto hlavičku můžete použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API. |
x-ms-version |
Označuje verzi Azure Files, která se používá ke spuštění požadavku. |
Date |
Hodnota data a času UTC, která určuje čas, kdy služba odeslala odpověď. |
x-ms-copy-id: <id> |
Poskytuje identifikátor řetězce pro tuto operaci kopírování. Pomocí příkazu nebo Get FileGet File Properties zkontrolujte stav této operace kopírování nebo příkazem pass do Abort Copy File zrušte čekající operaci kopírování. |
x-ms-copy-status: <success ¦ pending> |
Určuje stav operace kopírování pomocí těchto hodnot: - success: Operace kopírování byla úspěšně dokončena.- pending: Operace kopírování stále probíhá. |
x-ms-client-request-id |
Dá se použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě x-ms-client-request-id hlavičky, pokud se nachází v požadavku, a hodnota je maximálně 1 024 viditelných znaků ASCII. Pokud se hlavička x-ms-client-request-id v požadavku nenachází, nebude tato hlavička v odpovědi. |
Text odpovědi
Žádné
Ukázková odpověď
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>
Autorizace
Tuto operaci může volat vlastník účtu nebo klient se sdíleným přístupovým podpisem, který má oprávnění k zápisu do cílového souboru nebo jeho sdílené složky. Všimněte si, že sdílený přístupový podpis zadaný v žádosti se vztahuje pouze na cílový soubor.
Přístup ke zdrojovému souboru nebo objektu blob se autorizuje samostatně, jak je popsáno v podrobnostech pro hlavičku x-ms-copy-sourcepožadavku .
Následující tabulka popisuje, jak lze autorizovat cílové a zdrojové objekty pro Copy File operaci:
| File | Autorizace pomocí sdíleného klíče nebo sdíleného klíče Lite | Autorizace se sdíleným přístupovým podpisem | Veřejný objekt nevyžaduje autorizaci |
|---|---|---|---|
| Cílový soubor | Ano | Ano | Nelze použít |
| Zdrojový soubor ve stejném účtu | Ano | Ano | Nelze použít |
| Zdrojový soubor v jiném účtu | Ne | Ano | Nelze použít |
| Zdrojový objekt blob ve stejném nebo jiném účtu | Ne | Ano | Ano |
Atributy systému souborů
| Atribut | Atribut souboru Win32 | Definice |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Soubor je jen pro čtení. Aplikace můžou soubor číst, ale nemůžou do něj zapisovat ani ho odstranit. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
Soubor je skrytý. Není součástí běžného seznamu adresářů. |
System |
FILE_ATTRIBUTE_SYSTEM |
Operační systém používá část souboru nebo výhradně soubor. |
None |
FILE_ATTRIBUTE_NORMAL |
Soubor nemá nastavené další atributy. Tento atribut je platný jenom v případě, že se používá samostatně. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
Soubor je archivní soubor. Aplikace obvykle používají tento atribut k označení souborů pro zálohování nebo odebrání. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
Soubor se používá pro dočasné úložiště. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Data souboru nejsou k dispozici okamžitě. Tento atribut systému souborů zajišťuje hlavně kompatibilitu s Windows. Azure Files ho nepodporuje s možnostmi úložiště offline. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
Služba indexování obsahu nebude soubor indexovat. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
Skener integrity dat na pozadí nepřečte datový proud uživatele. Tento atribut systému souborů zajišťuje hlavně kompatibilitu s Windows. |
Poznámky
Operace může být dokončena Copy File asynchronně. Pomocí ID kopírování, které vrátí hlavička x-ms-copy-id odpovědi, můžete zkontrolovat stav operace kopírování nebo ji zrušit. Azure Files soubory kopíruje s maximálním úsilím.
Pokud cílový soubor existuje, přepíše se. Během probíhající operace kopírování není možné upravit cílový soubor.
Operace Copy File vždy zkopíruje celý zdrojový objekt blob nebo soubor. Kopírování rozsahu bajtů nebo sady bloků není podporováno.
Zdrojem Copy File operace může být soubor, který se nachází ve snímku sdílené složky. Cílem Copy File operace nemůže být soubor, který se nachází ve snímku sdílené složky.
Pokud zdroj operace kopírování poskytuje ETag hodnoty, dojde k selhání, pokud dojde k nějakým změnám zdroje v průběhu operace. Pokus o změnu cílového souboru během probíhající operace kopírování selže se stavovým kódem 409 (konflikt).
Hodnota ETag cílového souboru se změní při Copy File spuštění operace. Během operace kopírování se stále často mění.
Kopírování vlastností a metadat
Při kopírování objektu blob nebo souboru se do cílového souboru zkopírují následující systémové vlastnosti se stejnými hodnotami:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
Cílový soubor má vždy stejnou velikost jako zdrojový objekt blob nebo soubor. Hodnota hlavičky Content-Length cílového souboru odpovídá hodnotě této hlavičky zdrojového objektu blob nebo souboru.
Kopírování zapůjčeného objektu blob nebo souboru do souboru
Operace Copy File čte jenom ze zdrojového objektu blob nebo souboru, takže zapůjčení zdrojového objektu nemá na operaci vliv. Operace Copy File při spuštění uloží ETag hodnotu zdrojového objektu blob nebo souboru. Pokud se ETag hodnota změní před dokončením operace kopírování, operace selže. Změnám zdrojového objektu blob souboru můžete zabránit tím, že si ho pronajímáte během operace kopírování.
Pokud má cílový soubor aktivní nekonečné zapůjčení, musíte zadat ID zapůjčení ve volání Copy File operace. Zatímco operace kopírování čeká na vyřízení, jakákoli operace zapůjčení v cílovém souboru selže se stavovým kódem 409 (konflikt). Během operace kopírování se tímto způsobem uzamkne nekonečné zapůjčení cílového souboru, ať už kopírujete do cílového souboru, který má jiný název než zdroj, nebo kopírujete do cílového souboru se stejným názvem jako zdroj. Pokud klient zadá ID zapůjčení souboru, který ještě neexistuje, vrátí Azure Files stavový kód 412 (Předběžná podmínka se nezdařila).
Práce s čekající operací kopírování
Operace Copy File může asynchronně dokončit kopírování souborů. Následující tabulka slouží k určení dalšího kroku na základě stavového kódu, který Copy File vrátí:
| Stavový kód | Význam |
|---|---|
| 202 (přijato), x-ms-copy-status: success | Operace kopírování byla úspěšně dokončena. |
| 202 (přijato), x-ms-copy-status: pending | Operace kopírování nebyla dokončena. Dotazování cílového objektu blob pomocí k Get File Properties prozkoumání x-ms-copy-status , dokud se operace kopírování nedokončí nebo selže. |
| 4xx, 500 nebo 503 | Operace kopírování selhala. |
Během a po Copy File operaci obsahují vlastnosti cílového souboru ID Copy File kopírování operace a adresu URL zdrojového objektu blob nebo souboru. Po dokončení operace zapíše Azure Files hodnotu času a výsledku (success, failednebo aborted) do vlastností cílového souboru. Pokud má operace výsledek failed , hlavička x-ms-copy-status-description obsahuje řetězec podrobností o chybě.
Čekající Copy File operace má dvoutýdenní časový limit. U pokusu o kopírování, který se nedokončil po dvou týdnech, vyprší časový limit a ponechá prázdný soubor s polem x-ms-copy-status nastaveným na failed hodnotu x-ms-status-description 500 (OperationCancelled). Občasné, ne závažné chyby, ke kterým může dojít během operace kopírování, můžou bránit v průběhu operace, ale nezpůsobí její selhání. V těchto případech x-ms-copy-status-description popisuje přerušované chyby.
Jakýkoli pokus o úpravu cílového souboru během operace kopírování selže se stavovým kódem 409 (konflikt), "Probíhá kopírování souboru".
Pokud zavoláte operaci Abort Copy File , uvidíte x-ms-copy-status:aborted záhlaví. Cílový soubor bude mít neporušená metadata a délku souboru 0 bajtů. Pokud chcete operaci zkusit znovu, můžete původní volání Copy File zopakovat.
Fakturace
Cílový účet operace se Copy File účtuje za jednu transakci pro spuštění operace. U cílového účtu také probíhá jedna transakce pro každou žádost o zrušení nebo vyžádání stavu operace kopírování.
Pokud je zdrojový soubor nebo objekt blob v jiném účtu, účtují se za zdrojový účet transakční náklady. Pokud se navíc zdrojový a cílový účet nacházejí v různých oblastech (například USA – sever a USA – jih), bude šířka pásma, kterou použijete k přenosu žádosti, účtována zdrojovému účtu jako výchozí přenos dat. Výchozí přenos dat mezi účty ve stejné oblasti je bezplatný.