Intervalo PUT
A Put Range operação grava um intervalo de bytes em um arquivo.
Disponibilidade do protocolo
| Protocolo de compartilhamento de arquivos habilitado | Disponível |
|---|---|
| SMB |
|
| NFS |
|
Solicitação
A solicitação Put Range pode ser criada da seguinte maneira. Recomendamos que você use HTTPS.
| Método | URI da solicitação | Versão HTTP |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
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 informações sobre restrições de nomenclatura de caminho, consulte Compartilhamentos de nome e referência, diretórios, arquivos e metadados.
Parâmetros do URI
Os seguintes parâmetros adicionais podem ser especificados no URI de 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 da solicitação
Os cabeçalhos de solicitação obrigatórios e opcionais são descritos na tabela a seguir:
| 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. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure. |
Range ou x-ms-range |
Range or x-ms-range is required.Especifica o intervalo de bytes a serem gravados. É necessário especificar o início e o fim do intervalo. 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 de limpeza, o intervalo pode ter até o valor do tamanho total do arquivo. O serviço Arquivo aceita apenas um intervalo de bytes para os Range cabeçalhos 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 |
Obrigatórios. Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. Quando o x-ms-write cabeçalho é definido como clear, o valor desse cabeçalho deve ser definido 0como . |
Content-MD5 |
Opcional. Um hash MD5 do conteúdo. O hash é usado para verificar a integridade dos dados durante o transporte. Quando o Content-MD5 cabeçalho é especificado, Arquivos do Azure compara 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 inválida).O Content-MD5 cabeçalho não é permitido quando o x-ms-write cabeçalho é definido clearcomo . Se ele estiver incluído na solicitação, o serviço Arquivo retornará status código 400 (Solicitação Incorreta). |
x-ms-write: { update ¦ clear } |
Obrigatórios. 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. |
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 |
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 forem 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 de 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. |
Corpo da solicitação
Os dados que representam o intervalo a ser carregado.
Solicitação de exemplo: 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 a seguir. A resposta também pode incluir 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 |
A ETag contém um valor que representa a versão do arquivo. O valor é colocado entre aspas. |
Last-Modified |
Retorna a data e a hora em que o diretório foi modificado pela última vez. O formato da data segue RFC 1123. Para obter mais informações, consulte Representar valores de data/hora em cabeçalhos. Qualquer operação que modifique o compartilhamento, 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 true como 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 será igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho 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. |
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.
Comentários
A Put Range operação 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 status código 404 (Não Encontrado).
Para criar um novo arquivo, chame Criar Arquivo. Um arquivo pode ter até 4 TiB de tamanho.
Uma Put Range operação 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
Chamar Put Range com a opção Update executa uma gravação no local no arquivo especificado. Todo o 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á status código 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 de armazenamento, desde que o intervalo especificado seja de 512 bytes alinhado. 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 do alinhado de 512 bytes.
Todos os intervalos que não foram limpos são retornados na resposta Intervalos de Lista . Para obter um exemplo, consulte a seção "Amostra de intervalo desmarcado sem sinal" a seguir.
Concessão de arquivo
Você pode chamar o 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 que os bloqueios de intervalo de bytes gerenciem o acesso de leitura e gravação a regiões de um arquivo. Isso significa que Put Range falhará se um cliente SMB tiver um bloqueio que se sobreponha ao intervalo especificado pela Put Range operação usando x-ms-range. Para obter mais informações, consulte Gerenciar bloqueios de arquivo.
Notificações de alteração do diretório do cliente SMB
O protocolo SMB dá suporte à função de API FindFirstChangeNotification 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 ocorrer uma alteração de arquivo ou diretório por meio da API REST Arquivos do Azure. No entanto, as alterações causadas por outros clientes SMB propagam notificações.
Amostra de intervalo desmarcado sem sinal
Suponha que um arquivo seja criado com Criar Arquivo e um único intervalo seja gravado 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 não alinhado 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 subsequente de Intervalos de Lista 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 para o espaço não alinhado de 768-1024 e 2048-2304.
Put Rangenão há suporte em uma instantâneo de compartilhamento, que é uma cópia somente leitura de um compartilhamento. Uma tentativa de executar essa operação em um compartilhamento instantâneo falha com 400 (InvalidQueryParameterValue).