Fájl másolása

Cikk
07/26/2023

A Copy File művelet egy blobot vagy fájlt másol egy célfájlba a tárfiókon belül.

A 2015-02-21-es és újabb verzióban érhető el.

Protokoll rendelkezésre állása

Engedélyezett fájlmegosztási protokoll	Elérhető
SMB
NFS

Kérés

A kérést a Copy File következőképpen hozhatja létre. A HTTPS használatát javasoljuk.

A 2013-08-15-ös verziótól kezdődően megadhat megosztott hozzáférési aláírást a célfájlhoz, ha az ugyanabban a fiókban található, mint a forrásfájl. A 2015-04-05-ös verziótól kezdődően megadhatja a célfájl megosztott hozzáférési aláírását is, ha az egy másik tárfiókban található.

Metódus	Kérés URI-ja	HTTP-verzió
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	HTTP/1.1

Cserélje le a kérelem URI-jában látható elérésiút-összetevőket a sajátjára az alábbiak szerint:

Elérésiút-összetevő	Description
`myaccount`	A tárfiók neve.
`myshare`	A fájlmegosztás neve.
`mydirectorypath`	Választható. A szülőkönyvtár elérési útja.
`myfile`	A fájl neve.

Az elérésiút-elnevezési korlátozások részleteiért lásd: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

URI-paraméterek

A kérelem URI-ján a következő további paramétereket adhatja meg:

Paraméter	Leírás
`timeout`	Választható. Az időtúllépési paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása Azure Files műveletekhez.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérésfejléceket ismerteti:

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérések engedélyezése az Azure Storage-ba.
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérések engedélyezése az Azure Storage-ba.
`x-ms-version`	Minden engedélyezett kéréshez szükséges. A kérelemhez használni kívánt művelet verzióját adja meg. Ez a művelet csak a 2015-02-21-es és újabb verziókban érhető el. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`x-ms-meta-name:value`	Választható. Metaadatként adja meg a fájlhoz társított név-érték párokat. Ha nincs megadva név/érték pár, a művelet átmásolja a metaadatokat a forrásblobból vagy fájlból a célfájlba. Ha egy vagy több név-érték pár van megadva, a célfájl a megadott metaadatokkal jön létre, és a metaadatok nem lesznek átmásolva a forrásblobból vagy fájlból. A metaadatok nevének meg kell felelnie a C#-azonosítók elnevezési szabályainak. Vegye figyelembe, hogy a Azure Files által megadott fájl metaadatai nem érhetők el SMB-ügyfélről.
`x-ms-copy-source:name`	Kötelező. A forrásfájl vagy blob URL-címét adja meg, legfeljebb 2 kibibájt (KiB) hosszúságú. Ha egy fájlt egy másik fájlba szeretne másolni ugyanabban a tárfiókban, megosztott kulccsal engedélyezheti a forrásfájlt. Ha egy fájlt egy másik tárfiókból másol, vagy ha egy blobot ugyanabból a tárfiókból vagy egy másik tárfiókból másol, engedélyeznie kell a forrásfájlt vagy a blobot közös hozzáférésű jogosultságkód használatával. Ha a forrás nyilvános blob, a másolási művelet végrehajtásához nincs szükség engedélyezésre. A megosztási pillanatképekben lévő fájlokat másolási forrásként is megadhatja. Íme néhány példa a forrásobjektum URL-címére: `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>`	Akkor szükséges, ha a célfájl aktív bérletet kapott. A 2019-02-02-es és újabb verzióhoz érhető el. A fejléchez megadott bérletazonosítónak meg kell egyeznie a célfájl bérletazonosítójával. Ha a kérelem nem tartalmazza a bérletazonosítót, vagy az azonosító érvénytelen, a művelet a 412-s állapotkóddal meghiúsul (az előfeltétel sikertelen). Ha ez a fejléc meg van adva, és a célfájl jelenleg nem rendelkezik aktív bérlettel, a művelet a 412-s állapotkóddal meghiúsul (az előfeltétel sikertelen).
`x-ms-file-permission-copy-mode: { source ¦ override }`	Választható. A 2019-07-07-es és újabb verzióhoz érhető el. Meghatározza a fájl biztonsági leírójának másolási viselkedését: `source`: A célfájl biztonsági leíróját a rendszer a forrásfájlból másolja. `override`: A célfájl biztonsági leíróját a vagy `x-ms-file-permission-key` a `x-ms-file-permission` fejléc határozza meg.
`x-ms-file-permission`	Kötelező, ha `x-ms-file-permission-copy-mode` a meg van adva, `override` és `x-ms-file-permission-key` nincs megadva. A 2019-07-07-es és újabb verzióhoz érhető el. Ez az engedély a biztonsági leíró definíciós nyelvében (SDDL) megadott fájl biztonsági leírója. Ezt a fejlécet akkor használhatja, ha az engedélyek mérete 8 kibibájt (KiB) vagy annál kisebb. Ellenkező esetben használhatja a következőt `x-ms-file-permission-key`: . Ha meg van adva, tulajdonosi, csoport - és diszkréciós hozzáférés-vezérlési listával (DACL) kell rendelkeznie. Vegye figyelembe, hogy csak az egyik `x-ms-file-permission` vagy `x-ms-file-permission-key` a megadható.
`x-ms-file-permission-key`	Kötelező, ha `x-ms-file-permission-copy-mode` a meg van adva, `override` és `x-ms-file-permission` nincs megadva. A 2019-07-07-es és újabb verzióhoz érhető el. Ez a fejléc határozza meg a fájlhoz beállítandó engedély kulcsát. Ezt a kulcsot a `Create Permission` művelettel hozhatja létre. Vegye figyelembe, hogy csak az egyik `x-ms-file-permission` vagy `x-ms-file-permission-key` a megadható.
`x-ms-file-copy-ignore-readonly`	Választható. A 2019-07-07-es és újabb verzióhoz érhető el. Ez a logikai érték azt határozza meg, hogy egy `ReadOnly` már nem használt célfájl attribútumát tiszteletben kell-e tartani. Ha igen `true`, a másolási művelet sikeres lesz. Ellenkező esetben a célhelyen az attribútumkészlettel rendelkező `ReadOnly` korábbi fájl miatt a másolási művelet meghiúsul.
`x-ms-file-attributes`	Választható. A 2019-07-07-es és újabb verzióhoz érhető el. Ez a fejléc határozza meg a célfájlon beállítani kívánt fájlrendszerattribútumokat. Tekintse meg az elérhető attribútumok listáját. Az attribútumokat `source` a forrásfájlból a célfájlba másolhatja. Az érték `none` használatával törölheti a célfájl összes attribútumát.
`x-ms-file-creation-time`	Választható. A 2019-07-07-es és újabb verzióhoz érhető el. Ez a fejléc adja meg a létrehozási idő (UTC) tulajdonságát a célfájlon való beállításhoz. Az értékével `source` másolhatja a létrehozási időt a forrásfájlból a célfájlba.
`x-ms-file-last-write-time`	Választható. A 2019-07-07-es és újabb verziókhoz érhető el. Ez a fejléc az utolsó írási idő (UTC) tulajdonságát adja meg a célfájlon való beállításhoz. A értékével `source` másolhatja az utolsó írási időt a forrásfájlból a célfájlba.
`x-ms-file-copy-set-archive`	Választható. A 2019-07-07-es és újabb verziókhoz érhető el. Ez a logikai érték határozza meg, hogy az `Archive` attribútumot be kell-e állítani, függetlenül a `x-ms-file-attributes` fejléc értékétől.
`x-ms-client-request-id`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít 1 KiB karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel. További információ: Azure Blob Storage figyelése.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Választható. 2021-06-08-es és újabb verzió. A fájl UTC-változási idő tulajdonsága ISO 8601 formátumban. A érték használatával `source` másolhatja a módosítási időt a forrásfájlból a célfájlba. Az alapértelmezett időbélyeg a kérés időpontja.
`x-ms-file-request-intent`	Kötelező, ha `Authorization` a fejléc OAuth-jogkivonatot ad meg. Elfogadható érték: `backup`. Ez a fejléc azt adja meg, hogy a `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` vagy `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` értéket kell megadni, ha szerepelnek a fejléc használatával `Authorization` engedélyezett identitáshoz rendelt RBAC-szabályzatban. A 2022-11-02-es és újabb verziókhoz érhető el.
`x-ms-allow-trailing-dot: { <Boolean> }`	Választható. 2022-11-02-es és újabb verzió. A logikai érték azt határozza meg, hogy a kérelem URL-címében található záró pont legyen-e levágva vagy sem. További információ: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Választható. 2022-11-02-es és újabb verzió. A logikai érték azt határozza meg, hogy a forrás URL-címében található záró pont legyen-e levágva vagy sem. Ezt a fejlécet csak akkor szabad megadni, ha a másolási forrás egy Azure-fájl. Ez a fejléc más másolási forrástípus esetében nem támogatott. További információ: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

A kérés törzse

Nincsenek.

Reagálás

A válasz egy HTTP-állapotkódot és válaszfejléceket tartalmaz.

Állapotkód

A sikeres művelet a 202-s állapotkódot adja vissza (elfogadva).

Az állapotkódokkal kapcsolatos információkért lásd: Állapot- és hibakódok.

Válaszfejlécek

A műveletre adott válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmaz. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Válaszfejléc	Description
`ETag`	Ha a másolási művelet befejeződött, a `ETag` célfájl értékét tartalmazza. Ha a másolási művelet nem fejeződött be, a `ETag` művelet elején létrehozott üres fájl értékét tartalmazza.
`Last-Modified`	Azt a dátumot/időpontot adja vissza, amikor a célfájlba történő másolási művelet befejeződött.
`x-ms-request-id`	Egyedileg azonosítja a végrehajtott kérést. Ezzel a fejléccel elháríthatja a kérést. További információ: API-műveletek hibaelhárítása.
`x-ms-version`	A kérés végrehajtásához használt Azure Files verzióját jelzi.
`Date`	UTC dátum/idő érték, amely azt az időpontot jelzi, amikor a szolgáltatás elküldte a választ.
`x-ms-copy-id: <id>`	Sztringazonosítót biztosít ehhez a másolási művelethez. Használja a vagy `Get File Properties` a parancsot `Get File` a másolási művelet állapotának ellenőrzéséhez, vagy adja át a parancsot a függőben lévő másolási művelet megszakításához`Abort Copy File`.
`x-ms-copy-status: <success ¦ pending>`	A másolási művelet állapotát jelzi az alábbi értékekkel: - `success`: A másolási művelet sikeresen befejeződött. - `pending`: A másolási művelet még folyamatban van.
`x-ms-client-request-id`	A kérések és a megfelelő válaszok hibaelhárítására használható. A fejléc értéke megegyezik a `x-ms-client-request-id` kérelemben szereplő fejléc értékével, és az érték legfeljebb 1024 látható ASCII-karakterből áll. Ha a `x-ms-client-request-id` fejléc nincs jelen a kérelemben, ez a fejléc nem lesz jelen a válaszban.

Választörzs

None

Mintaválasz

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>

Engedélyezés

Ezt a műveletet a fiók tulajdonosa vagy egy olyan közös hozzáférésű jogosultságkóddal rendelkező ügyfél hívhatja meg, amely engedéllyel rendelkezik a célfájlba vagy a megosztásba való íráshoz. Vegye figyelembe, hogy a kérelemben megadott közös hozzáférésű jogosultságkód csak a célfájlra vonatkozik.

A forrásfájlhoz vagy blobhoz való hozzáférés külön engedélyezve van, a kérelem fejlécének x-ms-copy-sourcerészleteiben leírtak szerint.

Az alábbi táblázat azt ismerteti, hogyan engedélyezhetők a művelet cél- és forrásobjektumai Copy File :

Fájl	Engedélyezés megosztott kulccsal vagy megosztott kulccsal Lite	Engedélyezés közös hozzáférésű jogosultságkóddal	A nyilvános objektum nem igényel engedélyezést
Célfájl	Igen	Igen	Nem alkalmazható
Forrásfájl ugyanabban a fiókban	Igen	Igen	Nem alkalmazható
Forrásfájl egy másik fiókban	Nem	Igen	Nem alkalmazható
Forrásblob ugyanabban a fiókban vagy egy másik fiókban	Nem	Igen	Igen

Fájlrendszerattribútumok

Attribútum	Win32 fájlattribútum	Definíció
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	A fájl írásvédett. Az alkalmazások beolvashatják a fájlt, de nem írhatnak rá vagy nem törölhetnek.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	A fájl rejtett. Ez nem szerepel egy szokásos könyvtárlistán.
`System`	`FILE_ATTRIBUTE_SYSTEM`	Az operációs rendszer a fájl egy részét használja, vagy kizárólag a fájlt használja.
`None`	`FILE_ATTRIBUTE_NORMAL`	A fájl nem rendelkezik más attribútumokkal. Ez az attribútum csak akkor érvényes, ha egyedül használja.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	A fájl egy archív fájl. Az alkalmazások általában ezt az attribútumot használják a fájlok biztonsági mentésre vagy eltávolításra való megjelölésére.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	A fájl ideiglenes tárolásra van használva.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	A fájl adatai nem érhetők el azonnal. Ez a fájlrendszerattribútum elsősorban a Windowssal való kompatibilitást biztosítja. Azure Files nem támogatja offline tárolási lehetőségekkel.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	A tartalomindexelő szolgáltatás nem indexeli a fájlt.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	A háttéradat-integritás-ellenőrző nem olvassa be a felhasználói adatfolyamot. Ez a fájlrendszerattribútum elsősorban a Windowssal való kompatibilitást biztosítja.

Megjegyzések

A Copy File művelet aszinkron módon fejeződhet be. A válaszfejléc által visszaadott másolási azonosítóval x-ms-copy-id ellenőrizheti a másolási művelet állapotát, vagy megszakíthatja azt. Azure Files a fájlokat a lehető legjobb erőfeszítéssel másolja.

Ha a célfájl létezik, a program felülírja. A célfájl nem módosítható, amíg a másolási művelet folyamatban van.

A Copy File művelet mindig a teljes forrásblobot vagy fájlt másolja át. A bájtok vagy blokkok egy tartományának másolása nem támogatott.

A művelet forrása Copy File lehet egy megosztási pillanatképben található fájl. A művelet célja Copy File nem lehet megosztási pillanatképben található fájl.

Ha a másolási művelet forrása értékeket ad ETag meg, ha a művelet folyamatban van, a forrás módosítása sikertelen lesz. A célfájl módosítására tett kísérlet, amíg a másolási művelet folyamatban van, a 409-s állapotkód (ütközés) meghiúsul.

A ETag célfájl értéke a Copy File művelet indításakor megváltozik. A másolási művelet során továbbra is gyakran változik.

Tulajdonságok és metaadatok másolása

Blob vagy fájl másolásakor a rendszer a következő rendszertulajdonságokat másolja a célfájlba ugyanazokkal az értékekkel:

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

A célfájl mérete mindig megegyezik a forrásblob vagy a fájl méretével. A célfájl fejlécének Content-Length értéke megegyezik a forrásblob vagy fájl fejlécének értékével.

Bérelt blob vagy fájl másolása fájlba

A Copy File művelet csak a forrásblobból vagy fájlból olvas be, így a forrásobjektum bérlete nem befolyásolja a műveletet. A Copy File művelet a művelet indításakor menti a ETag forrásblob vagy fájl értékét. Ha az ETag érték a másolási művelet befejeződése előtt megváltozik, a művelet sikertelen lesz. A fájl forrásblobjának módosítását megakadályozhatja, ha a másolási művelet során lízingeli azt.

Ha a célfájl aktív végtelen bérlettel rendelkezik, meg kell adnia annak bérletazonosítóját a Copy File művelet hívásában. Amíg a másolási művelet függőben van, a célfájlon lévő bérletműveletek a 409-es (Ütközés) állapotkóddal meghiúsulnak. A másolási művelet során a célfájl végtelen bérlete zárolva van, függetlenül attól, hogy a forrástól eltérő nevű célfájlba vagy a forrás nevével azonos nevű célfájlba másol. Ha az ügyfél olyan fájl bérletazonosítóját adja meg, amely még nem létezik, Azure Files a 412-s állapotkódot adja vissza (az előfeltétel sikertelen).

Függőben lévő másolási művelet használata

Előfordulhat, hogy a Copy File művelet befejezi a fájlok aszinkron másolását. A következő táblázat segítségével határozza meg a következő lépést a visszaadott Copy File állapotkód alapján:

Állapotkód	Értelmezés
202 (Elfogadva), x-ms-copy-status: success	A másolási művelet sikeresen befejeződött.
202 (Elfogadva), x-ms-copy-status: pending	A másolási művelet még nem fejeződött be. A célblob lekérdezéséhez használja `Get File Properties` a vizsgálathoz `x-ms-copy-status` , amíg a másolási művelet befejeződik vagy meghiúsul.
4xx, 500 vagy 503	A másolási művelet nem sikerült.

A Copy File művelet során és után a célfájl tulajdonságai tartalmazzák a művelet másolási azonosítóját Copy File és a forrásblob vagy fájl URL-címét. Amikor a művelet befejeződik, Azure Files az idő és az eredmény értékét (success, failedvagy aborted) a célfájl tulajdonságaiba írja. Ha a művelet eredménye van failed , a x-ms-copy-status-description fejléc tartalmaz egy hibainformációs sztringet.

Egy függőben lévő Copy File művelet kéthetes időtúllépéssel rendelkezik. Egy másolási kísérlet, amely két hét után nem fejeződött be, és üres fájlt x-ms-copy-status hagy, amelynek a mező értéke failedx-ms-status-description 500 (OperationCancelled). A másolási művelet során előforduló időszakos, nem végzetes hibák akadályozhatják a művelet előrehaladását, de nem okoznak hibát. Ezekben az esetekben x-ms-copy-status-description az időszakos hibákat írja le.

A másolási művelet során a célfájl módosítására tett kísérletek a 409-es állapotkóddal (ütközés), a "Fájl másolása folyamatban" hibával meghiúsulnak.

Ha meghív egy Abort Copy File műveletet, megjelenik egy x-ms-copy-status:aborted fejléc. A célfájl érintetlen metaadatokkal és 0 bájt fájlhosszsal rendelkezik. Az eredeti hívás megismétlése után Copy File próbálja újra a műveletet.

Számlázás

A művelet célfiókja Copy File egy tranzakcióért lesz felszámítva a művelet elindításához. A célfiók egy tranzakcióval is jár minden egyes, a másolási művelet visszavonására vagy állapotának igénylésére irányuló kéréshez.

Ha a forrásfájl vagy blob egy másik fiókban található, a forrásfiók tranzakciós költségekkel jár. Ezenkívül ha a forrás- és célfiókok különböző régiókban (például az USA északi régiójában és az USA déli régiójában) találhatók, a kérés átviteléhez használt sávszélességet kimenő forgalomként számítjuk fel a forrásfióknak. Az ugyanazon régión belüli fiókok közötti kimenő forgalom ingyenes.