Colocar Intervalo
A operação Put Range grava um intervalo de bytes em um arquivo. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado.
Disponibilidade do protocolo
| Protocolo de compartilhamento de arquivos habilitado | Disponível |
|---|---|
| SMB |
|
| NFS |
|
Pedir
A solicitação Put Range é construída da seguinte maneira. Recomendamos que você use HTTPS.
| Método | URI de solicitação | Versão HTTP |
|---|---|---|
| PÔR | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Substitua os componentes de caminho mostrados no URI da solicitação por seus próprios, da seguinte maneira:
| Componente path | Descrição |
|---|---|
myaccount |
O nome da sua conta de armazenamento. |
myshare |
O nome do 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 parâmetros adicionais a seguir 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 seguintes tabelas:
Cabeçalhos de solicitação comuns
| Cabeçalho de 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 UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte 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 essa solicitação. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado. 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 serem gravados. O início e o final do intervalo devem ser especificados. Esse cabeçalho é definido pela especificação de protocolo HTTP/1.1 . Para uma operação de atualização, o intervalo pode ter 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 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 de 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 de 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 é definido como clear. Se ele estiver incluído na solicitação, o serviço 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> |
Necessá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 dá suporte a concessões de arquivo. |
x-ms-client-request-id |
Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres kib (1 kibibyte) 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 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 |
Necessário se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse 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 booliano 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, o que dá suporte ao ponto à direita por padrão. Para obter mais informações, consulte Nomenclatura e referência a compartilhamentos, diretórios, arquivos e metadados. |
Cabeçalhos de solicitação somente SMB
Nenhum.
Cabeçalhos de solicitação somente NFS
Nenhum.
Corpo da solicitação
Os dados que representam o intervalo a ser carregado.
Solicitação de exemplo: atualizar o 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 o 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 Status e códigos de erro.
Cabeçalhos de resposta
A resposta dessa 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 de protocolo HTTP/1.1 .
Cabeçalhos de resposta comuns
| Cabeçalho de resposta | Descrição |
|---|---|
ETag |
A 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 Arquivo. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos de solicitação. |
x-ms-request-id |
Identifica exclusivamente a solicitação que foi feita e pode ser usada 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 do serviço 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 será 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
Nenhum.
Cabeçalhos de resposta somente NFS
Nenhum.
Corpo da resposta
Nenhum.
Resposta de exemplo
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
Somente o proprietário da conta pode chamar essa operação.
Observações
A operação Put Range grava um intervalo de bytes em um arquivo. Essa operação pode ser chamada somente em um arquivo 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 criarde arquivo. Um arquivo pode ter até 4 TiB de tamanho.
Uma operação de Put Range tem permissão de 10 minutos por MiB para ser concluída. Se a operação estiver demorando mais de 10 minutos por MiB em média, ela atingirá o tempo limite.
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 de intervalo de
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 com a 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 (Entidade de Solicitação Muito Grande).
Operações de limpeza de intervalo
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 Listas. 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 está alinhado a 512 bytes e libera o restante do intervalo dentro que está alinhado em 512 bytes.
Todos os intervalos que não foram limpos são retornados na resposta Intervalos de Listas. Para obter um exemplo, consulte a seção "Amostra de intervalo desmarcado sem sinal" a seguir.
de concessão de arquivo
Você pode chamar de Arquivo de Concessão para obter um bloqueio de gravação exclusivo para o arquivo em relação a outras gravações por uma duração infinita.
bloqueios de intervalo de bytes do cliente SMB
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 de Put Range usando x-ms-range. Para obter mais informações, consulte Gerenciar bloqueios de arquivo.
bloqueios de intervalo de bytes do cliente NFS
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.
notificações de alteração do diretório do cliente SMB
O protocolo SMB dá suporte à função FindFirstChangeNotification API que permite que os aplicativos detectem quando ocorrem alterações no sistema de arquivos. Ele pode detectar quando um arquivo ou diretório é adicionado, alterado ou excluído e quando o tamanho, os atributos ou os descritores de segurança de um arquivo são alterados. Os clientes SMB que usam essa API não receberão notificações quando uma alteração de arquivo ou diretório ocorrer por meio da API REST dos Arquivos do Azure. No entanto, alterações causadas por outros clientes SMB propagam notificações.
amostra de de intervalo desalinhado sem sinal
Suponha que um arquivo seja criado com Criar de Arquivo e um único intervalo seja 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
A execução de uma operação de Intervalos de Lista no arquivo retorna o seguinte corpo da 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 claro não assinado 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 de intervalos de lista subsequente no arquivo retorna o seguinte corpo da 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 sem sinal de 768-1024 e 2048-2304.
Put Range não tem suporte 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).
Consulte também
operações de em arquivos