Copia file
L'operazione Copy File copia un BLOB o un file in un file di destinazione all'interno dell'account di archiviazione.
Disponibile nella versione 2015-02-21 e versioni successive.
Disponibilità del protocollo
| Protocollo di condivisione file abilitato | Disponibile |
|---|---|
| SMB |
|
| NFS |
|
Richiesta
È possibile costruire la Copy File richiesta come indicato di seguito. È consigliabile HTTPS.
A partire dalla versione 2013-08-15, è possibile specificare una firma di accesso condiviso per il file di destinazione se si trova nello stesso account del file di origine. A partire dalla versione 2015-04-05, è anche possibile specificare una firma di accesso condiviso per il file di destinazione se si trova in un account di archiviazione diverso.
| Metodo | URI richiesta | Versione HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Sostituire i componenti del percorso mostrati nell'URI di richiesta con valori personalizzati, come illustrato di seguito:
| Componente percorso | Descrizione |
|---|---|
myaccount |
nome dell'account di archiviazione. |
myshare |
Nome della condivisione file. |
mydirectorypath |
Facoltativa. Percorso della directory padre. |
myfile |
Nome del file. |
Per informazioni dettagliate sulle restrizioni di denominazione del percorso, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.
Parametri URI
Nell'URI della richiesta puoi specificare i parametri seguenti:
| Parametro | Descrizione |
|---|---|
timeout |
Facoltativa. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostare timeout per le operazioni di File di Azure. |
Intestazioni della richiesta
Nella tabella seguente vengono descritte le intestazioni richieste e facoltative:
| Intestazione della richiesta | Descrizione |
|---|---|
Authorization |
Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure. |
Date o x-ms-date |
Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure. |
x-ms-version |
Obbligatorio per tutte le richieste autorizzate. Specifica la versione dell'operazione da usare per questa richiesta. Questa operazione è disponibile solo nella versione 2015-02-21 e versioni successive. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure. |
x-ms-meta-name:value |
Facoltativa. Specifica coppie nome/valore associate al file come metadati. Se non vengono specificate coppie nome/valore, l'operazione copia i metadati dal BLOB di origine o dal file di destinazione. Se vengono specificate una o più coppie nome/valore, il file di destinazione viene creato con i metadati specificati e i metadati non vengono copiati dal BLOB o dal file di origine. I nomi dei metadati devono rispettare le regole di denominazione per gli identificatori C#. Si noti che i metadati dei file specificati tramite File di Azure non sono accessibili da un client SMB. |
x-ms-copy-source:name |
Obbligatorio. Specifica l'URL del file di origine o del BLOB, fino a 2 kibibyte (KiB) in lunghezza. Per copiare un file in un altro file all'interno dello stesso account di archiviazione, è possibile usare una chiave condivisa per autorizzare il file di origine. Se si copia un file da un altro account di archiviazione o se si copia un BLOB dallo stesso account di archiviazione o da un altro account di archiviazione, è necessario autorizzare il file di origine o il BLOB usando una firma di accesso condiviso. Se l'origine è un BLOB pubblico, non è necessaria alcuna autorizzazione per eseguire l'operazione di copia. È anche possibile specificare un file in uno snapshot di condivisione come origine di copia. Ecco alcuni esempi di URL dell'oggetto di origine:
|
x-ms-lease-id:<ID> |
Obbligatorio se il file di destinazione ha un lease attivo. Disponibile per la versione 2019-02-02 e successiva. L'ID lease specificato per questa intestazione deve corrispondere all'ID lease del file di destinazione. Se la richiesta non include l'ID lease o l'ID non è valido, l'operazione non riesce con il codice di stato 412 (Precondizione non riuscita). Se questa intestazione è specificata e il file di destinazione non ha attualmente un lease attivo, l'operazione non riesce con il codice di stato 412 (Precondizione non riuscita). |
x-ms-file-permission-copy-mode: { source ¦ override } |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Determina il comportamento di copia del descrittore di sicurezza del file:
|
x-ms-file-permission |
Obbligatorio se x-ms-file-permission-copy-mode viene specificato come override e x-ms-file-permission-key non specificato. Disponibile per la versione 2019-07-07 e versioni successive. Questa autorizzazione è il descrittore di sicurezza per il file specificato nel linguaggio SDDL (Security Descriptor Definition Language). È possibile usare questa intestazione se le dimensioni delle autorizzazioni sono pari a 8 kibibyte (KiB) o meno. In caso contrario, è possibile usare x-ms-file-permission-key. Se specificato, deve avere un proprietario, un gruppo e un elenco di controllo di accesso discrezionale (DACL). Si noti che è possibile specificare uno solo di x-ms-file-permission o x-ms-file-permission-key . |
x-ms-file-permission-key |
Obbligatorio se x-ms-file-permission-copy-mode viene specificato come override e x-ms-file-permission non specificato. Disponibile per la versione 2019-07-07 e versioni successive. Questa intestazione specifica la chiave dell'autorizzazione da impostare per il file. È possibile creare questa chiave usando l'operazione Create Permission .Si noti che è possibile specificare uno solo di x-ms-file-permission o x-ms-file-permission-key . |
x-ms-file-copy-ignore-readonly |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Questo valore booleano specifica se l'attributo ReadOnly in un file di destinazione preesistente deve essere rispettato. Se è true, l'operazione di copia ha esito positivo. In caso contrario, un file precedente nella destinazione con il ReadOnly set di attributi causa l'esito negativo dell'operazione di copia. |
x-ms-file-attributes |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Questa intestazione specifica gli attributi del file system da impostare nel file di destinazione. Vedere l'elenco degli attributi disponibili. È possibile usare un valore di per copiare gli attributi dal file di origine al file di source destinazione. È possibile usare un valore di per cancellare tutti gli attributi nel file di none destinazione. |
x-ms-file-creation-time |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Questa intestazione specifica la proprietà per l'ora di creazione, in FORMATO UTC, da impostare nel file di destinazione. È possibile usare un valore di per copiare il tempo di source creazione dal file di origine al file di destinazione. |
x-ms-file-last-write-time |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Questa intestazione specifica la proprietà per l'ultima ora di scrittura, in FORMATO UTC, da impostare nel file di destinazione. È possibile usare un valore di per copiare l'ultima ora di scrittura dal file di source origine al file di destinazione. |
x-ms-file-copy-set-archive |
Facoltativa. Disponibile per la versione 2019-07-07 e versioni successive. Questo valore booleano specifica se l'attributo deve essere impostato, indipendentemente dal valore dell'intestazione Archivex-ms-file-attributes . |
x-ms-client-request-id |
Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri 1 KiB registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare Archiviazione BLOB di Azure. |
x-ms-file-change-time: { <DateTime> ¦ source } |
Facoltativa. Versione 2021-06-08 e versioni successive. Proprietà ora di modifica UTC per il file, formattata nel formato ISO 8601. Un valore di può essere usato per copiare il tempo di modifica dal file di source origine al file di destinazione. Il timestamp predefinito è l'ora della richiesta. |
x-ms-file-request-intent |
Obbligatorio se Authorization l'intestazione specifica un token OAuth. Il valore accettabile è backup. Questa intestazione specifica che l'oggetto Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action o Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata usando l'intestazione Authorization . Disponibile per la versione 2022-11-02 e versioni successive. |
x-ms-allow-trailing-dot: { <Boolean> } |
Facoltativa. Versione 2022-11-02 e versioni successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno. Per altre informazioni, vedere Denominazione e riferimenti a condivisioni, directory, file e metadati. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Facoltativa. Versione 2022-11-02 e versioni successive. Il valore booleano specifica se un punto finale presente nell'URL di origine deve essere tagliato o meno. Questa intestazione deve essere specificata solo se l'origine di copia è un file di Azure. Questa intestazione non è supportata per qualsiasi altro tipo di origine di copia. Per altre informazioni, vedere Denominazione e riferimenti a condivisioni, directory, file e metadati. |
Testo della richiesta
Nessuno.
Risposta
Nella risposta sono inclusi un codice di stato HTTP e un set di intestazioni per la risposta.
Codice stato
Un'operazione completata correttamente restituisce il codice di stato 202 (Accettato).
Per informazioni sui codici di stato, vedere Codici di stato e di errore.
Intestazioni di risposta
Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta include inoltre intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.
| Intestazione risposta | Descrizione |
|---|---|
ETag |
Se l'operazione di copia viene completata, contiene il ETag valore del file di destinazione. Se l'operazione di copia non viene completata, contiene il ETag valore del file vuoto creato all'inizio dell'operazione. |
Last-Modified |
Restituisce la data/ora in cui è stata completata l'operazione di copia nel file di destinazione. |
x-ms-request-id |
Identifica in modo univoco la richiesta effettuata. È possibile usare questa intestazione per risolvere i problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api. |
x-ms-version |
Indica la versione di File di Azure usata per eseguire la richiesta. |
Date |
Valore di data/ora UTC che indica l'ora in cui il servizio ha inviato la risposta. |
x-ms-copy-id: <id> |
Fornisce un identificatore di stringa per questa operazione di copia. Usare o Get FileGet File Properties per controllare lo stato di questa operazione di copia o passare a Abort Copy File per annullare un'operazione di copia in sospeso. |
x-ms-copy-status: <success ¦ pending> |
Indica lo stato dell'operazione di copia con questi valori: - success: operazione di copia completata correttamente.- pending: l'operazione di copia è ancora in corso. |
x-ms-client-request-id |
Può essere usato per risolvere le richieste e le risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id se presente nella richiesta e il valore è al massimo 1.024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, questa intestazione non sarà presente nella risposta. |
Corpo della risposta
Nessuno
Risposta di esempio
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>
Autorizzazione
Questa operazione può essere chiamata dal proprietario dell'account o da un client che possiede una firma di accesso condiviso che dispone dell'autorizzazione per scrivere nel file di destinazione o nella relativa condivisione. Si noti che la firma di accesso condiviso specificata nella richiesta si applica solo al file di destinazione.
L'accesso al file di origine o al BLOB è autorizzato separatamente, come descritto nei dettagli per l'intestazione x-ms-copy-sourcedella richiesta.
La tabella seguente descrive come è possibile autorizzare gli oggetti di destinazione e di origine per un'operazione Copy File :
| File | Autorizzazione con chiave condivisa o Shared Key Lite | Autorizzazione con firma di accesso condiviso | Oggetto pubblico che non richiede l'autorizzazione |
|---|---|---|---|
| File di destinazione | Sì | Sì | Non applicabile |
| File di origine nello stesso account | Sì | Sì | Non applicabile |
| File di origine in un altro account | No | Sì | Non applicabile |
| BLOB di origine nello stesso account o in un altro account | No | Sì | Sì |
Attributi del file system
| Attributo | Attributo file Win32 | Definizione |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scriverlo o eliminarlo. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
Il file è nascosto. Non è incluso in un elenco di directory normale. |
System |
FILE_ATTRIBUTE_SYSTEM |
Il sistema operativo usa una parte del file oppure usa esclusivamente il file. |
None |
FILE_ATTRIBUTE_NORMAL |
Il file non ha altri attributi impostati. Questo attributo è valido solo quando viene usato da solo. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
Il file è un file di archivio. Le applicazioni in genere usano questo attributo per contrassegnare i file per il backup o la rimozione. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
Il file viene usato per l'archiviazione temporanea. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
I dati del file non sono immediatamente disponibili. Questo attributo del file system offre principalmente la compatibilità con Windows. File di Azure non lo supporta con le opzioni di archiviazione offline. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
Il servizio di indicizzazione del contenuto non indicizza il file. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
Lo scanner di integrità dei dati in background non leggerà il flusso di dati utente. Questo attributo del file system offre principalmente la compatibilità con Windows. |
Commenti
L'operazione Copy File può terminare in modo asincrono. È possibile usare l'ID di copia restituito dall'intestazione x-ms-copy-id della risposta per controllare lo stato dell'operazione di copia o annullarlo. File di Azure copia i file su base ottimale.
Se il file di destinazione esiste, verrà sovrascritto. Non è possibile modificare il file di destinazione mentre l'operazione di copia è in corso.
L'operazione Copy File copia sempre l'intero BLOB di origine o il file. La copia di un intervallo di byte o set di blocchi non è supportata.
L'origine di un'operazione Copy File può essere un file che si trova in uno snapshot di condivisione. La destinazione di un'operazione Copy File non può essere un file che risiede in uno snapshot di condivisione.
Quando l'origine di un'operazione di copia fornisce ETag valori, se sono presenti modifiche all'origine mentre l'operazione è in corso, avrà esito negativo. Un tentativo di modificare il file di destinazione durante l'esecuzione di un'operazione di copia avrà esito negativo con il codice di stato 409 (Conflitto).
Il ETag valore per il file di destinazione viene modificato all'avvio dell'operazione Copy File . Continua a cambiare spesso durante l'operazione di copia.
Copia di proprietà e metadati
Quando viene copiato un BLOB o un file, le proprietà del sistema seguenti vengono copiate nel file di destinazione con gli stessi valori:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
Il file di destinazione è sempre la stessa dimensione del BLOB di origine o del file. Il valore dell'intestazione per il Content-Length file di destinazione corrisponde al valore di tale intestazione per il BLOB o il file di origine.
Copia di un BLOB o di un file lease in un file
L'operazione Copy File legge solo dal BLOB o dal file di origine, quindi un lease sull'oggetto di origine non influisce sull'operazione. L'operazione Copy File salva il ETag valore del BLOB di origine o del file all'avvio dell'operazione. Se il valore cambia prima del completamento dell'operazione ETag di copia, l'operazione ha esito negativo. È possibile impedire modifiche al BLOB di origine del file tramite leasing durante l'operazione di copia.
Se il file di destinazione ha un lease infinito attivo, è necessario specificare il relativo ID lease nella chiamata all'operazione Copy File . Mentre l'operazione di copia è in sospeso, qualsiasi operazione di lease nel file di destinazione ha esito negativo con il codice di stato 409 (Conflitto). Un lease infinito sul file di destinazione viene bloccato in questo modo durante l'operazione di copia, se si esegue la copia in un file di destinazione con un nome diverso dall'origine o copiando in un file di destinazione che corrisponde al nome dell'origine. Se il client specifica un ID lease in un file che non esiste ancora, File di Azure restituisce il codice di stato 412 (Precondizione non riuscita).
Uso di un'operazione di copia in sospeso
L'operazione Copy File potrebbe terminare la copia dei file in modo asincrono. Usare la tabella seguente per determinare il passaggio successivo in base al codice di stato che Copy File restituisce:
| Codice stato | Significato |
|---|---|
| 202 (Accettato), x-ms-copy-status: success | Operazione di copia completata correttamente. |
| 202 (Accettato), x-ms-copy-status: pending | L'operazione di copia non è stata completata. Eseguire il polling del BLOB di destinazione usando Get File Properties per esaminare x-ms-copy-status finché l'operazione di copia non viene completata o non riesce. |
| 4xx, 500 o 503 | Operazione di copia non riuscita. |
Durante e dopo un'operazione Copy File , le proprietà del file di destinazione contengono l'ID copia dell'operazione Copy File e l'URL del BLOB o del file di origine. Al termine dell'operazione, File di Azure scrive il valore di tempo e risultato (success, failedo aborted) nelle proprietà del file di destinazione. Se l'operazione ha un risultato, l'intestazione x-ms-copy-status-description contiene una failed stringa di dettaglio errore.
Un'operazione in sospeso Copy File ha un timeout di due settimane. Tentativo di copia che non è stato completato dopo due settimane e lascia un file x-ms-copy-status vuoto impostato su e il x-ms-status-description campo impostato su failed 500 (OperationCancelled). Errori intermittenti e non irreversibili che possono verificarsi durante un'operazione di copia potrebbero impedire lo stato di avanzamento dell'operazione, ma non causarne l'esito negativo. In questi casi, gli errori intermittenti vengono descritti nell'intestazione x-ms-copy-status-description.
Qualsiasi tentativo di modifica del file di destinazione durante l'operazione di copia avrà esito negativo con il codice di stato 409 (conflitto), "Copia file in corso".
Se si chiama un'operazione, verrà visualizzata un'intestazione Abort Copy Filex-ms-copy-status:aborted . Il file di destinazione avrà metadati intatti e una lunghezza di file di 0 byte. È possibile ripetere la chiamata originale per Copy File provare di nuovo l'operazione.
Fatturazione
L'account di destinazione di un'operazione Copy File viene addebitato per un'unica transazione per avviare l'operazione. L'account di destinazione comporta anche una transazione per ogni richiesta di annullamento o richiesta dello stato dell'operazione di copia.
Quando il file di origine o il BLOB si trova in un altro account, l'account di origine comporta costi delle transazioni. Inoltre, se gli account di origine e di destinazione risiedono in aree diverse (ad esempio Stati Uniti settentrionali e Stati Uniti meridionali), la larghezza di banda usata per trasferire la richiesta viene addebitata all'account di origine come uscita. L'uscita tra account della stessa area geografica è gratuita.