Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
A operação Put Range grava um intervalo de bytes em um arquivo. Esta operação é suportada na versão 2025-05-05 e posterior para Partilhas de Ficheiros com o protocolo NFS ativado.
Disponibilidade do protocolo
| Protocolo de compartilhamento de arquivos habilitado | Disponível |
|---|---|
| PME |
|
| NFS |
|
Solicitar
A solicitação Put Range é construída da seguinte forma. Recomendamos que você use HTTPS.
| Método | Solicitar URI | Versão HTTP |
|---|---|---|
| COLOCAR | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
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 pai. |
myfile |
O nome do arquivo. |
Para obter informações sobre restrições de nomenclatura de caminho, consulte Compartilhamentos de nome e referência, diretórios, arquivos e metadados.
Parâmetros de URI
Os seguintes parâmetros adicionais podem ser especificados 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 serviço de arquivo. |
Cabeçalhos de solicitação
Os cabeçalhos de solicitação obrigatórios e opcionais são descritos nas tabelas a seguir:
Cabeçalhos de solicitação comuns
| 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. Esta operação é suportada na versão 2025-05-05 e posterior para Partilhas de Ficheiros com o protocolo NFS ativado. Para obter mais informações, consulte controle de versão para os serviços de Armazenamento do Azure. |
Range ou x-ms-range |
É necessário Range ou x-ms-range.Especifica o intervalo de bytes a ser gravado. O início e o fim do intervalo devem ser especificados. Este cabeçalho é definido pela especificação do protocolo HTTP/1.1. Para uma operação de atualização, o intervalo pode ser de até 4 MiB de tamanho. Para uma operação clara, o intervalo pode ser até o valor do tamanho total do arquivo. O serviço de arquivo aceita apenas um único intervalo de bytes para os cabeçalhos Range e x-ms-range, e o intervalo de bytes deve ser especificado no seguinte formato: bytes=startByte-endByte.Se Range e x-ms-range forem especificados, o serviço usará o valor de x-ms-range. Para obter mais informações, consulte Especificar o cabeçalho do intervalo para operações de serviço de arquivo. |
Content-Length |
Necessário. Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. Quando o cabeçalho x-ms-write é definido como clear, o valor desse cabeçalho deve ser definido como 0. |
Content-MD5 |
Opcional. Um hash MD5 do conteúdo. Esse hash é usado para verificar a integridade dos dados durante o transporte. Quando o cabeçalho Content-MD5 é especificado, os Arquivos do Azure comparam o hash do conteúdo que chegou com o valor do cabeçalho que foi enviado. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação incorreta).O cabeçalho Content-MD5 não é permitido quando o cabeçalho x-ms-write está definido como clear. Se estiver incluído com a solicitação, o serviço de arquivo retornará o código de status 400 (solicitação incorreta). |
x-ms-write: { update ¦ clear } |
Necessário. Você deve especificar uma das seguintes opções:
|
x-ms-lease-id:<ID> |
Obrigatório se o arquivo tiver uma concessão ativa. Disponível para a versão 2019-02-02 e posterior. Esse cabeçalho será ignorado se o arquivo estiver localizado em um compartilhamento de arquivos com o protocolo NFS habilitado, que não oferece suporte a concessões de arquivos. |
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 Monitorar arquivos do Azure. |
x-ms-file-last-write-time: { now ¦ preserve } |
Opcional. Versão 2021-06-08 e posterior. Você pode especificar uma das seguintes opções:
|
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. Esse cabeçalho será ignorado se o destino estiver localizado em um compartilhamento de arquivos com o protocolo NFS habilitado, que oferece suporte a pontos à direita por padrão. Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados. |
Cabeçalhos de solicitação somente SMB
Nenhuma.
Cabeçalhos de solicitação somente NFS
Nenhuma.
Corpo do pedido
Os dados que representam o intervalo a ser carregado.
Exemplo de solicitação: Atualizar intervalo de bytes
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Solicitação de exemplo: Limpar intervalo de bytes
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
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 201 (Criado). Para obter mais 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 nas tabelas a seguir. 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çalhos de resposta comuns
| Cabeçalho da resposta | Descrição |
|---|---|
ETag |
O ETag contém um valor que representa a versão do arquivo. O valor está entre aspas. |
Last-Modified |
Retorna a data e a hora em que o diretório foi modificado pela última vez. O formato de data segue o RFC 1123. Para obter mais informações, consulte Representar valores de data/hora em cabeçalhos. Qualquer operação que modifique o compartilhamento ou suas propriedades ou metadados atualiza a hora da última modificação. As operações em arquivos não afetam a hora da última modificação do compartilhamento. |
Content-MD5 |
Esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor desse cabeçalho é calculado pelo serviço de arquivo. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos da solicitação. |
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 Solucionar problemas de operações de API. |
x-ms-version |
Indica a versão do serviço de arquivo que foi usada para executar a solicitação. |
Date |
Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada. |
x-ms-request-server-encrypted: { true ¦ false } |
Versão 2017-04-17 e posterior. 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-client-request-id |
Esse cabeçalho 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 e o valor não contiver mais de 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. |
x-ms-file-last-write-time |
Versão 2021-06-08 e posterior. A última hora de gravação do arquivo, no formato ISO 8601. Exemplo: 2017-05-10T17:52:33.9551861Z. |
Cabeçalhos de resposta somente SMB
Nenhuma.
Cabeçalhos de resposta somente NFS
Nenhuma.
Corpo de resposta
Nenhuma.
Resposta da amostra
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Autorização
Apenas o proprietário da conta pode chamar esta operação.
Comentários
A operação Put Range grava um intervalo de bytes em um arquivo. Esta operação só pode ser chamada num ficheiro existente. Ele não pode ser chamado para criar um novo arquivo. Chamar Put Range com um nome de arquivo que não existe atualmente retorna o código de status 404 (Não encontrado).
Para criar um novo arquivo, chame Criar arquivo. Um arquivo pode ter até 4 TiB de tamanho.
Uma operação Put Range é permitida 10 minutos por MiB para ser concluída. Se a operação estiver demorando mais de 10 minutos por MiB, em média, o tempo limite expira.
Se o arquivo tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida na solicitação para gravar um intervalo.
Operações de atualização do intervalo
Chamar Put Range com a opção Update executa uma gravação in-loco no arquivo especificado. Qualquer conteúdo no intervalo especificado é substituído pela atualização. Cada intervalo enviado com Put Range para uma operação de atualização pode ter até 4 MiB de tamanho. Se você tentar carregar um intervalo maior que 4 MiB, o serviço retornará o código de status 413 (Solicitar entidade muito grande).
Alcance de operações limpas
Chamar Put Range com a opção Clear libera o espaço no armazenamento, desde que o intervalo especificado esteja alinhado a 512 bytes. Os intervalos que foram limpos não são mais rastreados como parte do arquivo e não são retornados na resposta Intervalo de Lista de. Se o intervalo especificado não estiver alinhado a 512 bytes, a operação gravará zeros no início ou no final do intervalo que não estiver alinhado a 512 bytes e liberará o restante do intervalo dentro do qual estiver alinhado com 512 bytes.
Todos os intervalos que não foram limpos são retornados na Listar Intervalos resposta. Para obter um exemplo, consulte a seção "Amostra de intervalo claro não alinhado" a seguir.
Concessão de arquivo
Você pode chamar Lease File para obter um bloqueio de gravação exclusivo para o arquivo em relação a outras gravações por uma duração infinita.
intervalo de bytes do cliente SMB bloqueia
O protocolo SMB permite bloqueios de intervalo de bytes para gerenciar o acesso de leitura e gravação a regiões de um arquivo. Isso significa que Put Range em um arquivo localizado em um compartilhamento de arquivos com o protocolo SMB habilitado falhará se um cliente SMB tiver um bloqueio que se sobreponha ao intervalo especificado pela operação Put Range usando x-ms-range. Para obter mais informações, consulte Gerenciar bloqueios de arquivos.
intervalo de bytes do cliente NFS bloqueia
Os bloqueios de intervalo de bytes POSIX do protocolo NFS são de natureza consultiva, portanto, o Put Range em um arquivo localizado em um compartilhamento de arquivos com o protocolo NFS habilitado não falhará mesmo se houver um bloqueio de intervalo de bytes conflitante mantido por um cliente NFS.
de notificações de alteração do diretório do cliente SMB
O protocolo SMB suporta a função de API FindFirstChangeNotification que permite que os aplicativos detetem quando ocorrem alterações no sistema de arquivos. Ele pode detetar quando um arquivo ou diretório é adicionado, alterado ou excluído, e quando o tamanho, atributos ou descritores de segurança de um arquivo mudam. Os clientes SMB que usam essa API não receberão notificações quando uma alteração de arquivo ou diretório acontecer por meio da API REST dos Arquivos do Azure. No entanto, as alterações causadas por outros clientes SMB propagam notificações.
Amostra de intervalo claro não alinhado
Suponha que um arquivo é criado com Create File e um único intervalo é escrito com Put Range, da seguinte maneira:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Executar uma operação Intervalos de Lista de no arquivo retorna o seguinte corpo de resposta:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Agora, suponha que uma operação de intervalo de bytes de intervalo livre não alinhada seja executada:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Uma operação List Ranges subsequente no arquivo retorna o seguinte corpo de resposta:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Observe que zeros foram gravados no espaço não alinhado de 768-1024 e 2048-2304.
Put Range não é suportado em um instantâneo de compartilhamento, que é uma cópia somente leitura de um compartilhamento. Uma tentativa de executar essa operação em um instantâneo de compartilhamento falha com 400 (InvalidQueryParameterValue).