Renomear arquivo

Artigo
08/07/2024

A operação Rename File renomeia um arquivo e, opcionalmente, pode definir as propriedades do sistema para o arquivo. Esta API está disponível na versão 2021-04-10 e posterior.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
PME
NFS

Solicitar

Você pode construir a solicitação Rename File da seguinte maneira. HTTPS é recomendado.

Método	Solicitar URI	Versão HTTP
COLOCAR	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rename`	HTTP/1.1

Substitua os componentes de caminho mostrados no URI de solicitação pelo seu, da seguinte maneira:

Componente Caminho	Descrição
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome do seu compartilhamento de arquivos.
`mydirectorypath`	Opcional. O caminho para o diretório de destino pai.
`myfile`	O nome do arquivo de destino.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Parâmetros de URI

Você pode especificar o seguinte parâmetro adicional no URI da solicitação.

Parâmetro	Descrição
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações do Azure Files.

Cabeçalhos de 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`	Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Obrigatório para todos os pedidos autorizados. Especifica a versão da operação a ser usada para essa solicitação. Para obter mais informações, consulte controle de versão para os serviços de Armazenamento do Azure.
`x-ms-file-rename-source:name`	Necessário. URI completo do arquivo a ser renomeado.
`x-ms-file-rename-replace-if-exists`	Opcional. Se o arquivo de destino já existir, substitua-o.
`x-ms-file-rename-ignore-readonly`	Opcional. Se o arquivo de destino existir com o atributo `readonly`, substitua o arquivo. Se for verdade, `x-ms-file-rename-replace-if-exists` também deve ser verdade.
`x-ms-content-Type`	Opcional. Define o tipo de conteúdo do arquivo. Se essa propriedade não for especificada na solicitação, a propriedade será preservada para o arquivo.
`x-ms-file-permission: { preserve ¦ <SDDL> ¦ <binary> }`	Opcional se `x-ms-file-permission-key` não for especificado. Essa permissão é o descritor de segurança para o arquivo especificado no Security Descriptor Definition Language (SDDL) ou (versão 2024-11-04 ou posterior) no formato de descritor de segurança binário codificado em base64. Você pode especificar qual formato usar com o cabeçalho `x-ms-file-permission-format`. Você pode usar esse cabeçalho se o tamanho das permissões for 8 kibibytes (KiB) ou menos. Caso contrário, você pode usar `x-ms-file-permission-key`. Se especificado, essa permissão deve ter um proprietário, grupo e lista de controle de acesso discricionário. Você pode passar um valor de `preserve` se quiser manter um valor existente inalterado. Observe que você pode especificar `x-ms-file-permission` ou `x-ms-file-permission-key`, não ambos.
`x-ms-file-permission-format: { sddl ¦ binary }`	Opcional. Versão 2024-11-04 ou posterior. Especifica se o valor passado em `x-ms-file-permission` está em SDDL ou em formato binário. Se `x-ms-file-permission-key` estiver definido como `preserve`, este cabeçalho não deve ser definido. Se `x-ms-file-permission-key` estiver definido como qualquer outro valor que não `preserve`, e se esse cabeçalho não estiver definido, o valor padrão de `sddl` será usado.
`x-ms-file-permission-key`	Opcional se `x-ms-file-permission` não for especificado. A chave da permissão a ser definida para o arquivo. Você pode criar isso usando a API `Create-Permission`. Observe que você pode especificar `x-ms-file-permission` ou `x-ms-file-permission-key`, não ambos.
`x-ms-file-attributes`	Opcional. Os atributos do sistema de arquivos a serem definidos no arquivo. Consulte a lista de atributos disponíveis. Você pode passar um valor de `preserve` se quiser manter um valor existente inalterado. Se você não especificar essa propriedade na solicitação, a propriedade será preservada para o arquivo.
`x-ms-file-creation-time`	Opcional. A propriedade de tempo de criação UTC para um arquivo. Você pode passar um valor de `preserve` se quiser manter um valor existente inalterado. Se você não especificar essa propriedade na solicitação, a propriedade será preservada para o arquivo.
`x-ms-file-last-write-time`	Opcional. A propriedade UTC last write para um arquivo. Você pode passar um valor de `preserve` se quiser manter um valor existente inalterado. Se você não especificar essa propriedade na solicitação, a propriedade será preservada para o arquivo.
`x-ms-source-lease-id:<ID>`	Necessário se o arquivo de origem tiver uma concessão ativa.
`x-ms-destination-lease-id:<ID>`	Necessário se o arquivo de destino tiver uma concessão ativa.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitor Azure Blob Storage.
`x-ms-meta-name:value`	Opcional. Define um par nome-valor para o arquivo. Cada chamada para esta operação substitui todos os metadados existentes anexados ao arquivo. Os nomes de metadados devem aderir às regras de nomenclatura para identificadores C#.
`x-ms-file-request-intent`	Obrigatório se `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Este cabeçalho especifica que os `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho `Authorization`. 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 na url da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos 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 na url de origem deve ser cortado ou não. Esse cabeçalho deve ser especificado somente se a fonte de cópia for um Arquivo do Azure. Este cabeçalho não é suportado para qualquer outro tipo de fonte de cópia. Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Corpo do pedido

Nenhuma.

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 200 (OK). 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 seguintes cabeçalhos. A resposta também pode incluir 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 da resposta	Descrição
`ETag`	Contém um valor que representa a versão do arquivo, entre aspas.
`Last-Modified`	Retorna a data e a hora em que o arquivo foi modificado pela última vez. Para obter mais informações, consulte Representação de valores de data-hora em cabeçalhos. Qualquer operação que modifique o diretório ou suas propriedades atualiza a hora da última modificação. As operações em arquivos não afetam a hora da última modificação do diretório.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar a solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
`x-ms-version`	Indica a versão dos Arquivos do Azure usada para executar a solicitação.
`Date` ou `x-ms-date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
`x-ms-request-server-encrypted: true/false`	O valor desse cabeçalho é definido como `true` se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado. Caso contrário, o valor será definido como `false`.
`x-ms-file-permission-key`	A chave da permissão do arquivo.
`x-ms-file-attributes`	Os atributos do sistema de arquivos no arquivo. Consulte a lista de atributos disponíveis.
`x-ms-file-creation-time`	O valor de data/hora UTC que representa a propriedade de tempo de criação para o arquivo.
`x-ms-file-last-write-time`	O valor de data/hora UTC que representa a última propriedade de tempo de gravação para o arquivo.
`x-ms-file-change-time`	O valor de data/hora UTC que representa a propriedade change time para o arquivo.
`x-ms-file-file-id`	O ID do arquivo do arquivo.
`x-ms-file-parent-id`	A ID do arquivo pai do arquivo.
`x-ms-client-request-id`	Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do cabeçalho `x-ms-client-request-id`, se ele estiver presente na solicitação. O valor é, no máximo, 1.024 caracteres ASCII visíveis. Se o cabeçalho `x-ms-client-request-id` não estiver presente na solicitação, ele não estará presente na resposta.

Corpo de resposta

Nenhuma.

Autorização

Somente o proprietário da conta pode chamar essa operação.

Atributos do sistema de arquivos

Atributo	Atributo de arquivo Win32	Definição
`ReadOnly`	FILE_ATTRIBUTE_READONLY	Um arquivo que é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo.
`Hidden`	FILE_ATTRIBUTE_HIDDEN	O ficheiro está oculto. Ele não está incluído em uma listagem de diretório comum.
`System`	FILE_ATTRIBUTE_SYSTEM	Um arquivo que o sistema operacional usa uma parte ou usa exclusivamente.
`None`	FILE_ATTRIBUTE_NORMAL	Um arquivo que não tem outros atributos definidos. Este atributo é válido apenas quando usado sozinho.
`Archive`	FILE_ATTRIBUTE_ARCHIVE	Um arquivo que é um arquivo morto. Os aplicativos normalmente usam esse atributo para marcar arquivos para backup ou remoção.
`Temporary`	FILE_ATTRIBUTE_TEMPORARY	Um arquivo que está sendo usado para armazenamento temporário.
`Offline`	FILE_ATTRIBUTE_OFFLINE	Os dados de um ficheiro não estão disponíveis imediatamente. Este atributo do sistema de arquivos é apresentado principalmente para fornecer compatibilidade com o Windows. Os Arquivos do Azure não oferecem suporte a opções de armazenamento offline.
`NotContentIndexed`	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED	O arquivo não deve ser indexado pelo serviço de indexação de conteúdo.
`NoScrubData`	FILE_ATTRIBUTE_NO_SCRUB_DATA	O fluxo de dados do usuário não deve ser lido pelo scanner de integridade de dados em segundo plano. Este atributo do sistema de arquivos é apresentado principalmente para fornecer compatibilidade com o Windows.

Comentários

O destino não pode ser um diretório existente.

Se você não especificar propriedades, o comportamento padrão de preserve ou now será definido.

Observação

As propriedades do arquivo anterior são discretas das propriedades do sistema de arquivos disponíveis para clientes SMB. Os clientes SMB não podem ler, gravar ou modificar esses valores de propriedade.

Rename File não é suportado em um instantâneo de compartilhamento, que é uma cópia somente leitura de um compartilhamento. Se você tentar executar essa operação em um instantâneo de compartilhamento, o serviço retornará o status de erro 400 (Valor do parâmetro de consulta inválido).

Se o arquivo tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida na solicitação para renomear o arquivo. Se o cliente não especificar uma ID de concessão ou especificar uma ID de concessão inválida, os Arquivos do Azure retornarão o código de status 412 (Falha na Pré-condição). Se o cliente especificar uma ID de concessão, mas o arquivo não tiver uma concessão ativa, os Arquivos do Azure também retornarão o código de status 412 (Falha na pré-condição).

Ver também

Operações em arquivos

Partilhar via