Copiar Arquivo
A Copy File operação copia um blob ou arquivo para um arquivo de destino dentro da conta de armazenamento.
Disponível na versão 2015-02-21 e posterior.
Disponibilidade do protocolo
| Protocolo de compartilhamento de arquivos habilitado | Disponível |
|---|---|
| SMB |
|
| NFS |
|
Solicitação
Você pode construir a solicitação da Copy File seguinte maneira. Recomendamos HTTPS.
A partir da versão 2013-08-15, você pode especificar uma assinatura de acesso compartilhado para o arquivo de destino se ele estiver na mesma conta que o arquivo de origem. A partir da versão 2015-04-05, você também pode especificar uma assinatura de acesso compartilhado para o arquivo de destino se ele estiver em uma conta de armazenamento diferente.
| Método | URI da solicitação | Versão HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:
| Componente Demarcador | Descrição |
|---|---|
myaccount |
O nome da sua conta de armazenamento. |
myshare |
O nome do seu compartilhamento de arquivo. |
mydirectorypath |
Opcional. O caminho para o diretório pai. |
myfile |
O nome do arquivo. |
Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.
Parâmetros do URI
Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:
| Parâmetro | Descrição |
|---|---|
timeout |
Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Arquivos do Azure. |
Cabeçalhos da solicitação
A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais:
| Cabeçalho da solicitação | Descrição |
|---|---|
Authorization |
Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure. |
x-ms-version |
Necessário para todas as solicitações autorizadas. Especifica a versão da operação a ser usada para esta solicitação. Essa operação só está disponível na versão 2015-02-21 e posterior. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure. |
x-ms-meta-name:value |
Opcional. Especifica pares nome/valor associados ao arquivo como metadados. Se nenhum par nome/valor for especificado, a operação copiará os metadados do blob ou arquivo de origem para o arquivo de destino. Se um ou mais pares nome/valor forem especificados, o arquivo de destino será criado com os metadados especificados e os metadados não serão copiados do blob ou arquivo de origem. Os nomes de metadados devem seguir as regras de nomenclatura para identificadores C#. Observe que os metadados de arquivo especificados por meio de Arquivos do Azure não podem ser acessados de um cliente SMB. |
x-ms-copy-source:name |
Obrigatórios. Especifica a URL do arquivo de origem ou blob, com até 2 kibibytes (KiB) de comprimento. Para copiar um arquivo para outro arquivo dentro da mesma conta de armazenamento, você pode usar uma chave compartilhada para autorizar o arquivo de origem. Se você estiver copiando um arquivo de outra conta de armazenamento ou se estiver copiando um blob da mesma conta de armazenamento ou de outra conta de armazenamento, deverá autorizar o arquivo de origem ou o blob usando uma assinatura de acesso compartilhado. Se a origem for um blob público, nenhuma autorização será necessária para executar a operação de cópia. Você também pode especificar um arquivo em um compartilhamento instantâneo como uma fonte de cópia. Aqui estão alguns exemplos de URLs de objeto de origem:
|
x-ms-lease-id:<ID> |
Obrigatório se o arquivo de destino tiver uma concessão ativa. Disponível para a versão 2019-02-02 e posterior. A ID de concessão especificada para esse cabeçalho deve corresponder à ID de concessão do arquivo de destino. Se a solicitação não incluir a ID de concessão ou a ID não for válida, a operação falhará com status código 412 (Falha na pré-condição). Se esse cabeçalho for especificado e o arquivo de destino não tiver uma concessão ativa no momento, a operação falhará com status código 412 (Falha na pré-condição). |
x-ms-file-permission-copy-mode: { source ¦ override } |
Opcional. Disponível para a versão 2019-07-07 e posterior. Determina o comportamento de cópia do descritor de segurança do arquivo:
|
x-ms-file-permission |
Obrigatório se x-ms-file-permission-copy-mode for especificado como override e x-ms-file-permission-key não for especificado. Disponível para a versão 2019-07-07 e posterior. Essa permissão é o descritor de segurança para o arquivo especificado na SDDL (Linguagem de Definição do Descritor de Segurança). Você poderá usar esse cabeçalho se o tamanho das permissões for de 8 kibibytes (KiB) ou menos. Caso contrário, você pode usar x-ms-file-permission-key. Se especificado, ele deve ter um proprietário, um grupo e uma DACL (lista de controle de acesso discricionário) . Observe que apenas um de x-ms-file-permission ou x-ms-file-permission-key pode ser especificado. |
x-ms-file-permission-key |
Obrigatório se x-ms-file-permission-copy-mode for especificado como override e x-ms-file-permission não for especificado. Disponível para a versão 2019-07-07 e posterior. Esse cabeçalho especifica a chave da permissão a ser definida para o arquivo. Você pode criar essa chave usando a Create Permission operação .Observe que apenas um de x-ms-file-permission ou x-ms-file-permission-key pode ser especificado. |
x-ms-file-copy-ignore-readonly |
Opcional. Disponível para a versão 2019-07-07 e posterior. Esse valor booliano especifica se o ReadOnly atributo em um arquivo de destino preexistência deve ser respeitado. Se for true, a operação de cópia terá êxito. Caso contrário, um arquivo anterior no destino com o ReadOnly conjunto de atributos fará com que a operação de cópia falhe. |
x-ms-file-attributes |
Opcional. Disponível para a versão 2019-07-07 e posterior. Esse cabeçalho especifica os atributos do sistema de arquivos a serem definidos no arquivo de destino. Confira a lista de atributos disponíveis. Você pode usar um valor de source para copiar os atributos do arquivo de origem para o arquivo de destino. Você pode usar um valor de none para limpar todos os atributos no arquivo de destino. |
x-ms-file-creation-time |
Opcional. Disponível para a versão 2019-07-07 e posterior. Esse cabeçalho especifica a propriedade para a hora de criação, em UTC, a ser definida no arquivo de destino. Você pode usar um valor de source para copiar o tempo de criação do arquivo de origem para o arquivo de destino. |
x-ms-file-last-write-time |
Opcional. Disponível para a versão 2019-07-07 e posterior. Esse cabeçalho especifica a propriedade para a hora da última gravação, em UTC, a ser definida no arquivo de destino. Você pode usar um valor de source para copiar a última hora de gravação do arquivo de origem para o arquivo de destino. |
x-ms-file-copy-set-archive |
Opcional. Disponível para a versão 2019-07-07 e posterior. Esse valor booliano especifica se o Archive atributo deve ser definido, independentemente do valor do x-ms-file-attributes cabeçalho. |
x-ms-client-request-id |
Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 KiB que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure. |
x-ms-file-change-time: { <DateTime> ¦ source } |
Opcional. Versão 2021-06-08 e posterior. A propriedade UTC change time para o arquivo, formatada no formato ISO 8601. Um valor de pode ser usado para copiar o tempo de alteração do arquivo de origem para o arquivo de source destino. O carimbo de data/hora padrão é a hora da solicitação. |
x-ms-file-request-intent |
Obrigatório se Authorization o cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse cabeçalho especifica que o Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve ser concedido se eles estiverem incluídos na política RBAC atribuída à identidade autorizada usando o Authorization cabeçalho . Disponível para a versão 2022-11-02 e posterior. |
x-ms-allow-trailing-dot: { <Boolean> } |
Opcional. Versão 2022-11-02 e posterior. O valor booliano especifica se um ponto à direita presente na URL da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Opcional. Versão 2022-11-02 e posterior. O valor booliano especifica se um ponto à direita presente na URL de origem deve ser cortado ou não. Esse cabeçalho só deverá ser especificado se a origem da cópia for um Arquivo do Azure. Não há suporte para esse cabeçalho para nenhum outro tipo de origem de cópia. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados. |
Corpo da solicitação
Nenhum.
Resposta
A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.
Código de status
Uma operação bem-sucedida retorna o código de status 202 (Aceito).
Para obter informações sobre códigos de status, consulte Códigos de status e de erro.
Cabeçalhos de resposta
A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também inclui cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.
| Cabeçalho de resposta | Descrição |
|---|---|
ETag |
Se a operação de cópia for concluída, conterá o ETag valor do arquivo de destino. Se a operação de cópia não for concluída, conterá o ETag valor do arquivo vazio criado no início da operação. |
Last-Modified |
Retorna a data/hora em que a operação de cópia para o arquivo de destino foi concluída. |
x-ms-request-id |
Identifica exclusivamente a solicitação que foi feita. Você pode usar esse cabeçalho para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API. |
x-ms-version |
Indica a versão de Arquivos do Azure usada para executar a solicitação. |
Date |
Um valor de data/hora UTC que indica a hora em que o serviço enviou a resposta. |
x-ms-copy-id: <id> |
Fornece um identificador de cadeia de caracteres para esta operação de cópia. Use com Get File ou Get File Properties para marcar o status desta operação de cópia ou passe para Abort Copy File para cancelar uma operação de cópia pendente. |
x-ms-copy-status: <success ¦ pending> |
Indica o estado da operação de cópia com estes valores: - success: a operação de cópia foi concluída com êxito.- pending: a operação de cópia ainda está em andamento. |
x-ms-client-request-id |
Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor for no máximo 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta. |
Corpo da resposta
Nenhum
Resposta de exemplo
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>
Autorização
Essa operação pode ser chamada pelo proprietário da conta ou por um cliente que possui uma assinatura de acesso compartilhado que tenha permissão para gravar no arquivo de destino ou em seu compartilhamento. Observe que a assinatura de acesso compartilhado especificada na solicitação se aplica somente ao arquivo de destino.
O acesso ao arquivo de origem ou blob é autorizado separadamente, conforme descrito nos detalhes do cabeçalho x-ms-copy-sourceda solicitação.
A tabela a seguir descreve como os objetos de destino e de origem de uma Copy File operação podem ser autorizados:
| Arquivo | Autorização com Chave Compartilhada ou Chave Compartilhada Lite | Autorização com assinatura de acesso compartilhado | Objeto público que não exige autorização |
|---|---|---|---|
| Arquivo de destino | Sim | Sim | Não aplicável |
| Arquivo de origem na mesma conta | Sim | Sim | Não aplicável |
| Arquivo de origem em outra conta | No | Sim | Não aplicável |
| Blob de origem na mesma conta ou em outra conta | No | Sim | Sim |
Atributos do sistema de arquivos
| Atributo | Atributo de arquivo Win32 | Definição |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Ele é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
O arquivo está oculto. Ele não está incluído em uma listagem de diretório comum. |
System |
FILE_ATTRIBUTE_SYSTEM |
O sistema operacional usa uma parte do arquivo ou usa o arquivo exclusivamente. |
None |
FILE_ATTRIBUTE_NORMAL |
O arquivo não tem outros atributos definidos. Esse atributo só é válido quando é usado sozinho. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
O arquivo é uma camada de armazenamento de arquivos. Os aplicativos normalmente usam esse atributo para marcar arquivos para backup ou remoção. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
O arquivo está sendo usado para armazenamento temporário. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Os dados do arquivo não estão disponíveis imediatamente. Esse atributo do sistema de arquivos fornece principalmente compatibilidade com o Windows. Arquivos do Azure não dá suporte a ele com opções de armazenamento offline. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
O serviço de indexação de conteúdo não indexa o arquivo. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
O verificador de integridade de dados em segundo plano não lerá o fluxo de dados do usuário. Esse atributo do sistema de arquivos fornece principalmente compatibilidade com o Windows. |
Comentários
A Copy File operação pode ser concluída de forma assíncrona. Você pode usar a ID de cópia que o x-ms-copy-id cabeçalho de resposta retorna para marcar o status da operação de cópia ou cancelá-la. Arquivos do Azure copia arquivos com base no melhor esforço.
Se o arquivo de destino existir, ele será substituído. Não é possível modificar o arquivo de destino enquanto a operação de cópia estiver em andamento.
A Copy File operação sempre copia todo o blob ou arquivo de origem. Não há suporte para a cópia de um intervalo de bytes ou um conjunto de blocos.
A origem de uma Copy File operação pode ser um arquivo que reside em um instantâneo de compartilhamento. O destino de uma Copy File operação não pode ser um arquivo que reside em um instantâneo de compartilhamento.
Quando a origem de uma operação de cópia fornecer ETag valores, se houver alterações na origem enquanto a operação estiver em andamento, ela falhará. Uma tentativa de alterar o arquivo de destino enquanto uma operação de cópia está em andamento falhará com status código 409 (Conflito).
O ETag valor do arquivo de destino é alterado quando a Copy File operação é iniciada. Ele continua a ser alterado com frequência durante a operação de cópia.
Copiando propriedades e metadados
Quando um blob ou arquivo é copiado, as seguintes propriedades do sistema são copiadas para o arquivo de destino com os mesmos valores:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
O arquivo de destino sempre tem o mesmo tamanho que o blob ou arquivo de origem. O valor do Content-Length cabeçalho do arquivo de destino corresponde ao valor desse cabeçalho para o blob ou arquivo de origem.
Copiar um blob ou arquivo concedido para um arquivo
A Copy File operação lê apenas do blob ou arquivo de origem, portanto, uma concessão no objeto de origem não afeta a operação. A Copy File operação salva o ETag valor do blob ou arquivo de origem quando a operação é iniciada. Se o ETag valor for alterado antes da conclusão da operação de cópia, a operação falhará. Você pode impedir alterações no blob de origem do arquivo alugando-o durante a operação de cópia.
Se o arquivo de destino tiver uma concessão infinita ativa, você deverá especificar sua ID de concessão na chamada para a Copy File operação. Embora a operação de cópia esteja pendente, qualquer operação de concessão no arquivo de destino falhará com status código 409 (Conflito). Uma concessão infinita no arquivo de destino é bloqueada dessa forma durante a operação de cópia, seja você copiando para um arquivo de destino que tenha um nome diferente da origem ou copiando para um arquivo de destino com o mesmo nome que a origem. Se o cliente especificar uma ID de concessão em um arquivo que ainda não existe, Arquivos do Azure retornará status código 412 (Falha na pré-condição).
Trabalhando com uma operação de cópia pendente
A Copy File operação pode concluir a cópia dos arquivos de forma assíncrona. Use a tabela a seguir para determinar a próxima etapa com base no código status que Copy File retorna:
| Código de status | Significado |
|---|---|
| 202 (Aceito), x-ms-copy-status: success | Operação de cópia concluída com êxito. |
| 202 (Aceito), x-ms-copy-status: pending | A operação de cópia não foi concluída. Sondar o blob de destino usando Get File Properties para examinar x-ms-copy-status até que a operação de cópia seja concluída ou falhe. |
| 4xx, 500 ou 503 | Falha na operação de cópia. |
Durante e após uma Copy File operação, as propriedades do arquivo de destino contêm a ID de cópia da Copy File operação e a URL do blob ou arquivo de origem. Quando a operação for concluída, Arquivos do Azure gravará o valor de tempo e resultado (success, failedou aborted) nas propriedades do arquivo de destino. Se a operação tiver um failed resultado, o x-ms-copy-status-description cabeçalho conterá uma cadeia de caracteres de detalhes de erro.
Uma operação pendente Copy File tem um tempo limite de duas semanas. Uma tentativa de cópia que não foi concluída após duas semanas atinge o tempo limite e deixa um arquivo vazio com o x-ms-copy-status campo definido failed como e o x-ms-status-description campo definido como 500 (OperationCancelled). Erros intermitentes e não fatais que podem ocorrer durante uma operação de cópia podem impedir o progresso da operação, mas não causar falha. Nesses casos, x-ms-copy-status-description descreve os erros intermitentes.
Qualquer tentativa de modificar o arquivo de destino durante a operação de cópia falhará com status código 409 (Conflito), "Copiar Arquivo em Andamento".
Se você chamar uma Abort Copy File operação, verá um x-ms-copy-status:aborted cabeçalho. O arquivo de destino terá metadados intactos e um comprimento de arquivo de 0 bytes. Você pode repetir a chamada original para Copy File para tentar a operação novamente.
Cobrança
A conta de destino de uma Copy File operação é cobrada por uma transação para iniciar a operação. A conta de destino também incorre em uma transação para cada solicitação cancelar ou solicitar o status da operação de cópia.
Quando o arquivo de origem ou o blob está em outra conta, a conta de origem incorre em custos de transação. Além disso, se as contas de origem e destino residirem em regiões diferentes (por exemplo, Norte dos EUA e Sul dos EUA), a largura de banda usada para transferir a solicitação será cobrada para a conta de origem como saída. A saída entre contas na mesma região é gratuita.