Copiar Ficheiro
A Copy File operação copia um blob ou ficheiro para um ficheiro de destino na conta de armazenamento.
Disponível na versão 2015-02-21 e posterior.
Disponibilidade do protocolo
| Protocolo de partilha de ficheiros ativado | Disponível |
|---|---|
| SMB |
|
| NFS |
|
Pedir
Pode construir o pedido da Copy File seguinte forma. Recomendamos HTTPS.
A partir da versão 2013-08-15, pode especificar uma assinatura de acesso partilhado para o ficheiro de destino se estiver na mesma conta que o ficheiro de origem. A partir da versão 2015-04-05, também pode especificar uma assinatura de acesso partilhado para o ficheiro de destino se estiver numa conta de armazenamento diferente.
| Método | URI do pedido | Versão HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Substitua os componentes de caminho apresentados no URI do pedido pelo seu, da seguinte forma:
| Componente caminho | Description |
|---|---|
myaccount |
O nome da sua conta de armazenamento. |
myshare |
O nome da partilha de ficheiros. |
mydirectorypath |
Opcional. O caminho para o diretório principal. |
myfile |
O nome do ficheiro. |
Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.
Parâmetros URI
Pode especificar os seguintes parâmetros adicionais no URI do pedido:
| Parâmetro | Description |
|---|---|
timeout |
Opcional. O parâmetro de tempo limite é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações de Ficheiros do Azure. |
Cabeçalhos do pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais:
| Cabeçalho do pedido | Description |
|---|---|
Authorization |
Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
x-ms-version |
Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Esta operação só está disponível na versão 2015-02-21 e posterior. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure. |
x-ms-meta-name:value |
Opcional. Especifica pares de nome/valor associados ao ficheiro como metadados. Se não forem especificados pares de nomes/valores, a operação copia os metadados do blob ou ficheiro de origem para o ficheiro de destino. Se forem especificados um ou mais pares de nomes/valores, o ficheiro de destino é criado com os metadados especificados e os metadados não são copiados do blob ou ficheiro de origem. Os nomes de metadados têm de cumprir as regras de nomenclatura dos identificadores C#. Tenha em atenção que os metadados de ficheiro especificados através de Ficheiros do Azure não estão acessíveis a partir de um cliente SMB. |
x-ms-copy-source:name |
Obrigatório. Especifica o URL do ficheiro de origem ou blob, até 2 kibibytes (KiB) de comprimento. Para copiar um ficheiro para outro ficheiro na mesma conta de armazenamento, pode utilizar uma chave partilhada para autorizar o ficheiro de origem. Se estiver a copiar um ficheiro de outra conta de armazenamento ou se estiver a copiar um blob da mesma conta de armazenamento ou de outra conta de armazenamento, tem de autorizar o ficheiro de origem ou o blob através de uma assinatura de acesso partilhado. Se a origem for um blob público, não é necessária autorização para efetuar a operação de cópia. Também pode especificar um ficheiro num instantâneo de partilha como uma origem de cópia. Eis alguns exemplos de URLs de objetos de origem:
|
x-ms-lease-id:<ID> |
Necessário se o ficheiro de destino tiver uma concessão ativa. Disponível para a versão 2019-02-02 e posterior. O ID de concessão especificado para este cabeçalho tem de corresponder ao ID de concessão do ficheiro de destino. Se o pedido não incluir o ID de concessão ou o ID não for válido, a operação falha com o código de estado 412 (Falha na Pré-condição). Se este cabeçalho for especificado e o ficheiro de destino não tiver atualmente uma concessão ativa, a operação falha com o código de estado 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 da cópia do descritor de segurança do ficheiro:
|
x-ms-file-permission |
Necessá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. Esta permissão é o descritor de segurança do ficheiro especificado na Linguagem de Definição do Descritor de Segurança (SDDL). Pode utilizar este cabeçalho se o tamanho das permissões for 8 kibibytes (KiB) ou menos. Caso contrário, pode utilizar x-ms-file-permission-key. Se especificado, tem de ter uma lista de controlo de acesso discricionário (DACL) de proprietário, grupo e grupo. Tenha em atenção que apenas um de x-ms-file-permission ou x-ms-file-permission-key pode ser especificado. |
x-ms-file-permission-key |
Necessá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. Este cabeçalho especifica a chave da permissão a definir para o ficheiro. Pode criar esta chave com a Create Permission operação.Tenha em atenção 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. Este valor booleano especifica se o ReadOnly atributo num ficheiro de destino pré-instalado deve ser respeitado. Se for true, a operação de cópia é bem-sucedida. Caso contrário, um ficheiro anterior no destino com o ReadOnly conjunto de atributos faz 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. Este cabeçalho especifica os atributos do sistema de ficheiros a definir no ficheiro de destino. Veja a lista de atributos disponíveis. Pode utilizar um valor de source para copiar os atributos do ficheiro de origem para o ficheiro de destino. Pode utilizar um valor de none para limpar todos os atributos no ficheiro de destino. |
x-ms-file-creation-time |
Opcional. Disponível para a versão 2019-07-07 e posterior. Este cabeçalho especifica a propriedade para a hora de criação, em UTC, a definir no ficheiro de destino. Pode utilizar um valor de para copiar a hora de source criação do ficheiro de origem para o ficheiro de destino. |
x-ms-file-last-write-time |
Opcional. Disponível para a versão 2019-07-07 e posterior. Este cabeçalho especifica a propriedade para a hora da última escrita, em UTC, a definir no ficheiro de destino. Pode utilizar um valor de source para copiar a hora da última escrita do ficheiro de origem para o ficheiro de destino. |
x-ms-file-copy-set-archive |
Opcional. Disponível para a versão 2019-07-07 e posterior. Este valor booleano 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 carateres de 1 KiB que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Armazenamento de Blobs do Azure. |
x-ms-file-change-time: { <DateTime> ¦ source } |
Opcional. Versão 2021-06-08 e posterior. A propriedade HORA UTC para o ficheiro, formatada no formato ISO 8601. Um valor de source pode ser utilizado para copiar a hora de alteração do ficheiro de origem para o ficheiro de destino. O carimbo de data/hora predefinido é a hora do pedido. |
x-ms-file-request-intent |
Necessário se o Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Este cabeçalho especifica que o Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve ser concedido se estiver incluído na política RBAC atribuída à identidade autorizada com 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 Booleano especifica se um ponto à direita presente no URL do pedido deve ser cortado ou não. Para obter mais informações, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados). |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Opcional. Versão 2022-11-02 e posterior. O valor Booleano especifica se um ponto à direita presente no URL de origem deve ser cortado ou não. Este cabeçalho só deve ser especificado se a origem de cópia for um Ficheiro do Azure. Este cabeçalho não é suportado para qualquer outro tipo de origem de cópia. Para obter mais informações, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados). |
Corpo do pedido
Nenhum.
Resposta
A resposta inclui um código de estado HTTP e um conjunto de cabeçalhos de resposta.
Código de estado
Uma operação bem-sucedida devolve o código de estado 202 (Aceite).
Para obter informações sobre códigos de estado, veja Códigos de estado e de erro.
Cabeçalhos de resposta
A resposta para esta operação inclui os seguintes cabeçalhos. A resposta também inclui cabeçalhos HTTP padrão 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 estiver concluída, contém o ETag valor do ficheiro de destino. Se a operação de cópia não estiver concluída, contém o ETag valor do ficheiro vazio criado no início da operação. |
Last-Modified |
Devolve a data/hora em que a operação de cópia foi concluída para o ficheiro de destino. |
x-ms-request-id |
Identifica exclusivamente o pedido que foi feito. Pode utilizar este cabeçalho para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API. |
x-ms-version |
Indica a versão do Ficheiros do Azure utilizada para executar o pedido. |
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 para esta operação de cópia. Utilize com Get File ou Get File Properties para verificar o estado desta operação de cópia ou passe para para Abort Copy File 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 curso. |
x-ms-client-request-id |
Pode ser utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente no pedido e o valor for, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta. |
Corpo da resposta
Nenhuma
Resposta de amostra
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
Esta operação pode ser chamada pelo proprietário da conta ou por um cliente que possua uma assinatura de acesso partilhado que tenha permissão para escrever no ficheiro de destino ou na respetiva partilha. Tenha em atenção que a assinatura de acesso partilhado especificada no pedido aplica-se apenas ao ficheiro de destino.
O acesso ao ficheiro de origem ou blob é autorizado separadamente, conforme descrito nos detalhes do cabeçalho x-ms-copy-sourcedo pedido .
A tabela seguinte descreve como o destino e os objetos de origem de uma Copy File operação podem ser autorizados:
| Ficheiro | Autorização com Chave Partilhada ou Chave Partilhada Lite | Autorização com assinatura de acesso partilhado | O objeto público não necessita de autorização |
|---|---|---|---|
| Ficheiro de destino | Yes | Yes | Não aplicável |
| Ficheiro de origem na mesma conta | Yes | Yes | Não aplicável |
| Ficheiro de origem noutra conta | No | Yes | Não aplicável |
| Blob de origem na mesma conta ou noutra conta | No | Yes | Yes |
Atributos do sistema de ficheiros
| Atributo | Atributo de ficheiro Win32 | Definição |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
O ficheiro é só de leitura. As aplicações podem ler o ficheiro, mas não podem escrevê-lo ou eliminá-lo. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
O ficheiro está oculto. Não está incluído numa lista de diretórios comuns. |
System |
FILE_ATTRIBUTE_SYSTEM |
O sistema operativo utiliza uma parte do ficheiro ou utiliza exclusivamente o ficheiro. |
None |
FILE_ATTRIBUTE_NORMAL |
O ficheiro não tem outros atributos definidos. Este atributo só é válido quando é utilizado individualmente. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
O ficheiro é um ficheiro de arquivo. Normalmente, as aplicações utilizam este atributo para marcar ficheiros para cópia de segurança ou remoção. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
O ficheiro está a ser utilizado para armazenamento temporário. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Os dados do ficheiro não estão disponíveis imediatamente. Este atributo do sistema de ficheiros fornece principalmente compatibilidade com o Windows. Ficheiros do Azure não o suporta com opções de armazenamento offline. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
O serviço de indexação de conteúdos não indexa o ficheiro. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
O detetor de integridade de dados em segundo plano não lê o fluxo de dados do utilizador. Este atributo do sistema de ficheiros fornece principalmente compatibilidade com o Windows. |
Observações
A Copy File operação pode ser concluída de forma assíncrona. Pode utilizar o ID de cópia devolvido pelo x-ms-copy-id cabeçalho de resposta para verificar o estado da operação de cópia ou cancelá-lo. Ficheiros do Azure copia ficheiros numa base de melhor esforço.
Se o ficheiro de destino existir, será substituído. Não pode modificar o ficheiro de destino enquanto a operação de cópia estiver em curso.
A Copy File operação copia sempre todo o blob ou ficheiro de origem. A cópia de um intervalo de bytes ou conjunto de blocos não é suportada.
A origem de uma Copy File operação pode ser um ficheiro que reside num instantâneo de partilha. O destino de uma Copy File operação não pode ser um ficheiro que reside num instantâneo de partilha.
Quando a origem de uma operação de cópia fornece valores ETag , se existirem alterações na origem enquanto a operação estiver em curso, falhará. Uma tentativa de alterar o ficheiro de destino enquanto uma operação de cópia estiver em curso falhará com o código de estado 409 (Conflito).
O ETag valor do ficheiro de destino é alterado quando a Copy File operação é iniciada. Continua a ser alterado frequentemente durante a operação de cópia.
Copiar propriedades e metadados
Quando um blob ou ficheiro é copiado, as seguintes propriedades do sistema são copiadas para o ficheiro de destino com os mesmos valores:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
O ficheiro de destino tem sempre o mesmo tamanho que o blob ou ficheiro de origem. O valor do cabeçalho do Content-Length ficheiro de destino corresponde ao valor desse cabeçalho para o blob ou ficheiro de origem.
Copiar um blob ou ficheiro alugado para um ficheiro
A Copy File operação só lê a partir do blob ou ficheiro de origem, pelo que uma concessão no objeto de origem não afeta a operação. A Copy File operação guarda o ETag valor do blob ou ficheiro 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á. Pode impedir alterações ao blob de origem do ficheiro ao alugá-lo durante a operação de cópia.
Se o ficheiro de destino tiver uma concessão infinita ativa, tem de especificar o respetivo ID de concessão na chamada para a Copy File operação. Enquanto a operação de cópia está pendente, qualquer operação de concessão no ficheiro de destino falha com o código de estado 409 (Conflito). Uma concessão infinita no ficheiro de destino é bloqueada desta forma durante a operação de cópia, quer esteja a copiar para um ficheiro de destino que tenha um nome diferente da origem ou a copiar para um ficheiro de destino com o mesmo nome que a origem. Se o cliente especificar um ID de concessão num ficheiro que ainda não existe, Ficheiros do Azure devolve o código de estado 412 (Falha na Pré-condição).
Trabalhar com uma operação de cópia pendente
A Copy File operação pode terminar de copiar os ficheiros de forma assíncrona. Utilize a tabela seguinte para determinar o passo seguinte com base no código de estado que Copy File devolve:
| Código de estado | Significado |
|---|---|
| 202 (Aceite), x-ms-copy-status: success | A operação de cópia foi concluída com êxito. |
| 202 (Aceite), x-ms-copy-status: pendente | A operação de cópia ainda não foi concluída. Consulte o blob de destino com Get File Properties o para examinar x-ms-copy-status até que a operação de cópia seja concluída ou falhe. |
| 4xx, 500 ou 503 | A operação de cópia falhou. |
Durante e após uma Copy File operação, as propriedades do ficheiro de destino contêm o ID de cópia da Copy File operação e o URL do blob ou ficheiro de origem. Quando a operação for concluída, Ficheiros do Azure escreve o valor de hora e resultado (success, failedou aborted) nas propriedades do ficheiro de destino. Se a operação tiver um failed resultado, o x-ms-copy-status-description cabeçalho contém uma cadeia de detalhes do erro.
Uma operação pendente Copy File tem um tempo limite de duas semanas. Uma tentativa de cópia que não terminou após duas semanas excede o tempo limite e deixa um ficheiro vazio com o x-ms-copy-status campo definido como failed 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 a falha. Nestes casos, x-ms-copy-status-description descreve os erros intermitentes.
Qualquer tentativa de modificar o ficheiro de destino durante a operação de cópia falhará com o código de estado 409 (Conflito), "Copiar Ficheiro em Curso".
Se chamar uma Abort Copy File operação, verá um x-ms-copy-status:aborted cabeçalho. O ficheiro de destino terá metadados intactos e um comprimento de ficheiro de 0 bytes. Pode repetir a chamada original para Copy File tentar a operação novamente.
Faturação
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 numa transação para cada pedido para cancelar ou pedir o estado da operação de cópia.
Quando o ficheiro de origem ou blob está noutra conta, a conta de origem incorre em custos de transação. Além disso, se as contas de origem e de destino residiram em regiões diferentes (por exemplo, Eua Norte e E.U.A. Sul), a largura de banda que utiliza para transferir o pedido é cobrada para a conta de origem como saída. A saída entre contas na mesma região é gratuita.