Colocar Intervalo
A Put Range operação escreve um intervalo de bytes num ficheiro.
Disponibilidade do protocolo
| Protocolo de partilha de ficheiros ativado | Disponível |
|---|---|
| SMB |
|
| NFS |
|
Pedir
O Put Range pedido pode ser construído da seguinte forma. Recomendamos que utilize HTTPS.
| Método | URI do pedido | Versão HTTP |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
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 informações sobre restrições de nomenclatura de caminhos, veja Partilhas de nomes e referências, diretórios, ficheiros e metadados.
Parâmetros do URI
Os seguintes parâmetros adicionais podem ser especificados no URI do pedido.
| Parâmetro | Description |
|---|---|
timeout |
Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações do Serviço de ficheiros. |
Cabeçalhos do pedido
Os cabeçalhos de pedido obrigatórios e opcionais estão descritos na tabela seguinte:
| 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. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure. |
Range ou x-ms-range |
x-ms-range Ou Range é necessário.Especifica o intervalo de bytes a escrever. O início e o fim do intervalo têm de ser especificados. Este cabeçalho é definido pela especificação do 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 estar até ao valor do tamanho total do ficheiro. O serviço Ficheiro aceita apenas um intervalo de bytes único para os Range cabeçalhos e x-ms-range e o intervalo de bytes tem de ser especificado no seguinte formato: bytes=startByte-endByte.Se e Rangex-ms-range forem especificados, o serviço utiliza o valor de x-ms-range. Para obter mais informações, veja Especificar o cabeçalho de intervalo para operações do Serviço de ficheiros. |
Content-Length |
Obrigatório. Especifica o número de bytes que estão a ser transmitidos no corpo do pedido. Quando o x-ms-write cabeçalho está definido como clear, o valor deste cabeçalho tem de ser definido como 0. |
Content-MD5 |
Opcional. Um Hash MD5 do conteúdo. Este Hash é utilizado para verificar a integridade dos dados durante o transporte. Quando o Content-MD5 cabeçalho é especificado, Ficheiros do Azure compara 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 falha com o código de erro 400 (Pedido Incorreto).O Content-MD5 cabeçalho não é permitido quando o x-ms-write cabeçalho está definido como clear. Se estiver incluído no pedido, o serviço Ficheiro devolve o código de estado 400 (Pedido Incorreto). |
x-ms-write: { update ¦ clear } |
Obrigatório. Tem de especificar uma das seguintes opções:
|
x-ms-lease-id: <ID> |
Necessário se o ficheiro 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 carateres de 1 kibibyte (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 Ficheiros do Azure. |
x-ms-file-last-write-time: { now ¦ preserve } |
Opcional. Versão 2021-06-08 e posterior. Pode especificar uma das seguintes opções:
|
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). |
Corpo do pedido
Os dados que representam o intervalo a carregar.
Pedido 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
Pedido 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 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 201 (Criado).
Para obter mais 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 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 de resposta | Descrição |
|---|---|
ETag |
A ETag contém um valor que representa a versão do ficheiro. O valor está entre aspas. |
Last-Modified |
Devolve a data e hora em que o diretório foi modificado pela última vez. O formato de data segue RFC 1123. Para obter mais informações, veja Representar valores de data/hora em cabeçalhos. Qualquer operação que modifique a partilha ou as respetivas propriedades ou metadados atualiza a hora da última modificação. As operações em ficheiros não afetam a hora da última modificação da partilha. |
Content-MD5 |
Este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo serviço Ficheiro. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido. |
x-ms-request-id |
Identifica exclusivamente o pedido que foi feito e pode ser utilizado 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 Serviço de ficheiros que foi utilizada para executar o pedido. |
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 deste cabeçalho é definido como true se os conteúdos do pedido forem encriptados com êxito através do algoritmo especificado. Caso contrário, o valor está definido como false. |
x-ms-client-request-id |
Este cabeçalho 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 não contiver mais de 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, não está presente na resposta. |
x-ms-file-last-write-time |
Versão 2021-06-08 e posterior. A última hora de escrita do ficheiro, no formato ISO 8601. Exemplo: 2017-05-10T17:52:33.9551861Z. |
Corpo da resposta
Nenhum.
Resposta de 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.
Observações
A Put Range operação escreve um intervalo de bytes num ficheiro. Esta operação só pode ser chamada num ficheiro existente. Não pode ser chamado para criar um novo ficheiro. Chamar Put Range com um nome de ficheiro que não existe atualmente devolve o código de estado 404 (Não Encontrado).
Para criar um novo ficheiro, chame Criar Ficheiro. Um ficheiro pode ter até 4 TiB de tamanho.
É Put Range permitida uma operação de 10 minutos por MiB. Se a operação estiver a demorar mais de 10 minutos por MiB em média, excede o limite de tempo.
Se o ficheiro tiver uma concessão ativa, o cliente tem de especificar um ID de concessão válido no pedido para escrever um intervalo.
Operações de atualização do intervalo
Chamar Put Range com a opção Update efetua uma escrita no local no ficheiro especificado. Qualquer conteúdo no intervalo especificado é substituído pela atualização. Cada intervalo submetido para Put Range uma operação de atualização pode ter até 4 MiB de tamanho. Se tentar carregar um intervalo superior a 4 MiB, o serviço devolve o código de estado 413 (Entidade de Pedido Demasiado Grande).
Operações de limpar intervalo
Chamar Put Range com a opção Clear liberta o espaço no armazenamento, desde que o intervalo especificado esteja alinhado com 512 bytes. Os intervalos que foram limpos já não são monitorizados como parte do ficheiro e não são devolvidos na resposta Do Intervalo de Listas . Se o intervalo especificado não estiver alinhado com 512 bytes, a operação escreve zeros no início ou no fim do intervalo que não está alinhado com 512 bytes e liberta o resto do intervalo dentro do que está alinhado com 512 bytes.
Quaisquer intervalos que não tenham sido limpos são devolvidos na resposta Intervalos de Lista . Por exemplo, veja a secção "Intervalo claro desalinhado de exemplo" que se segue.
Concessão de ficheiros
Pode chamar o Ficheiro de Concessão para obter um bloqueio de escrita exclusivo no ficheiro em relação a outras escritas durante uma duração infinita.
Bloqueios do intervalo de bytes do cliente SMB
O protocolo SMB permite bloqueios de intervalo de bytes para gerir o acesso de leitura e escrita a regiões de um ficheiro. Isto significa que Put Range falha se um cliente SMB tiver um bloqueio que se sobrepõe ao intervalo especificado pela Put Range operação com x-ms-range. Para obter mais informações, veja Gerir bloqueios de ficheiros.
Notificações de alteração do diretório de cliente SMB
O protocolo SMB suporta a função da API FindFirstChangeNotification que permite que as aplicações detetem quando ocorrem alterações no sistema de ficheiros. Pode detetar quando um ficheiro ou diretório é adicionado, alterado ou eliminado e quando o tamanho, atributos ou descritores de segurança de um ficheiro são alterados. Os clientes SMB que utilizam esta API não receberão notificações quando ocorrer uma alteração de ficheiro ou diretório através da API REST Ficheiros do Azure. No entanto, as alterações causadas por outros clientes SMB propagam notificações.
Exemplo de intervalo limpo desalinhado
Suponha que um ficheiro é criado com Criar Ficheiro e um único intervalo é escrito com Put Range, da seguinte forma:
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 De Intervalos de Lista no ficheiro devolve 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 é efetuada uma operação de intervalo de bytes claros desalinhada:
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 ficheiro devolve 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>
Tenha em atenção que foram escritos zeros no espaço desalinhado de 768-1024 e 2048-2304.
Put Range não é suportado num instantâneo de partilha, que é uma cópia só de leitura de uma partilha. Uma tentativa de executar esta operação num instantâneo de partilha falha com 400 (InvalidQueryParameterValue).