Colocar Intervalo a Partir do URL

Artigo
05/15/2024

A Put Range From URL operação cria um novo intervalo a ser consolidado como parte de um ficheiro onde os conteúdos são lidos a partir de um URL. Esta API está disponível a partir da versão 2019-02-02.

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado	Disponível
SMB
NFS

Pedir

O Put Range From URL pedido pode ser construído da seguinte forma. Recomendamos que utilize HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

Método	URI do pedido	Versão HTTP
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

Parâmetros URI

Parâmetro	Description
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações de Ficheiros do Azure.

Cabeçalhos do pedido

Os cabeçalhos de pedido obrigatórios e opcionais estão descritos na seguinte tabela:

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Veja Autorizar pedidos para o Armazenamento do Azure para obter mais informações.
`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. Para `Put Range From URL`o , a versão tem de ser 2019-02-02 ou posterior.
`x-ms-copy-source:name`	Obrigatório. Especifica o URL do ficheiro de origem. O valor pode ser um URL de até 2 KiB de comprimento que especifica um ficheiro. O valor deve ser codificado por URL, uma vez que apareceria num URI de pedido. O ficheiro de origem tem de ser público ou tem de ser autorizado através de uma assinatura de acesso partilhado. Se o ficheiro de origem for público, não é necessária autorização para executar a operação. Eis alguns exemplos de URLs de objetos de origem: `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`x-ms-copy-source-authorization: <scheme> <signature>`	Opcional. Especifica o esquema de autorização e a assinatura da origem de cópia. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. Apenas o portador do esquema é suportado para Microsoft Entra. Este cabeçalho é suportado na versão 2020-10-02 e posterior.
`x-ms-write: { update }`	Obrigatório. Tem de especificar apenas `update`. O pedido falha se for chamado com `clear`. O `update` valor escreve os bytes especificados pelo corpo do pedido nos intervalos especificados.
`Range` ou `x-ms-range`	Obrigatório. `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. Ficheiros do Azure aceita apenas um único intervalo de bytes 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 ambos e `Rangex-ms-range` forem especificados, o serviço utiliza o valor de `x-ms-range`. Para obter mais informações, consulte Especificar o cabeçalho do intervalo para operações de Ficheiros do Azure.
`x-ms-source-range`	Obrigatório. Especifica o intervalo de bytes a ler a partir da origem. O início e o fim do intervalo têm de ser especificados. Ficheiros do Azure aceita apenas um único intervalo de bytes para os `Range` cabeçalhos e `x-ms-range` e o intervalo de bytes tem de ser especificado no seguinte formato: `bytes=startByte-endByte`. O intervalo de origem pode ter até 4 MiB de tamanho. Se o tamanho do intervalo de origem exceder os 4 MiB, Ficheiros do Azure devolve o código de estado 413 (Entidade do Pedido Demasiado Grande). Se o tamanho do intervalo de origem não corresponder ao tamanho do intervalo (intervalo de destino), o serviço devolve o código de estado 400 (Pedido Incorreto).
`Content-Length`	Obrigatório. Especifica o número de bytes que estão a ser transmitidos no corpo do pedido. O valor deste cabeçalho tem de ser definido como `0`. Quando o comprimento não `0`for , a operação falha com o código de estado 400 (Pedido Incorreto).
`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-source-content-crc64`	Opcional. Um Hash CRC64 do intervalo especificado a partir do URI. Este Hash é utilizado para verificar a integridade da gama durante o transporte dos dados do URI. Quando este cabeçalho é especificado, o Azure Files compara o Hash do conteúdo que chegou da fonte de cópia com este valor do cabeçalho. Nota: este hash CRC64 não está armazenado com o ficheiro. Se os dois hashes não corresponderem, a operação falha com o código de erro 400 (Pedido Incorreto).
`x-ms-source-if-match-crc64`	Opcional. Um valor de soma de verificação CRC64. Especifique este cabeçalho para efetuar a operação apenas se a soma de verificação do intervalo especificado for lida a partir de correspondências de origem a partir da soma de verificação fornecida. Se a condição especificada não for cumprida, Ficheiros do Azure devolve o código de estado 412 (Falha na Pré-condição).
`x-ms-source-if-none-match-crc64`	Opcional. Um valor de soma de verificação CRC64. Especifique este cabeçalho para executar a operação apenas se a soma de verificação do intervalo especificado lido a partir da origem for diferente da soma de verificação fornecida. Se a condição especificada não for cumprida, Ficheiros do Azure devolve o código de estado 412 (Falha na Pré-condição).
`x-ms-lease-id:<ID>`	Necessário se o ficheiro tiver uma concessão ativa. Para efetuar esta operação num ficheiro com uma concessão ativa, especifique o ID de concessão válido para este cabeçalho.
`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 de análise quando o registo de Análise de Armazenamento do Azure está ativado. Recomendamos vivamente que utilize este cabeçalho quando estiver a correlacionar atividades do lado do cliente com pedidos recebidos pelo servidor. Para obter mais informações, veja Monitorizar o Armazenamento de Blobs.
`x-ms-file-last-write-time: { now ¦ preserve }`	Opcional. Versão 2021-06-08 e posterior. Pode especificar uma das seguintes opções: `now`: valor predefinido. Atualizações o último carimbo de data/hora de escrita à hora do pedido. `preserve`: mantém o carimbo de data/hora da última escrita existente inalterado.
`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 estiverem incluídos 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 Nomenclatura e referência de partilhas, diretórios, ficheiros 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 no URL de origem deve ser cortado ou não. Este cabeçalho só deve ser especificado se a origem de cópia for um Ficheiro do Azure. Este cabeçalho não é suportado para qualquer outro tipo de origem de cópia. Para obter mais informações, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.

Corpo do pedido

Sem corpo do pedido.

Pedido de exemplo

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

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`	Contém um valor que pode utilizar para realizar operações condicionalmente. O valor está entre aspas.
`Last-Modified`	A data e hora em que o ficheiro foi modificado pela última vez. O formato de data segue RFC 1123. Para obter mais informações, veja Representação de Valores de Data/Hora em cabeçalhos. Qualquer operação de escrita no ficheiro, incluindo atualizações aos metadados ou propriedades do ficheiro, altera a hora da última modificação do ficheiro.
`x-ms-request-id`	Identifica exclusivamente o pedido que foi feito e pode utilizá-lo para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
`x-ms-version`	Indica a versão da API FileREST 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-content-crc64`	Devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado por Ficheiros do Azure. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos do pedido.
`x-ms-client-request-id`	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 estará 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 (por exemplo, `2017-05-10T17:52:33.9551861Z`).

Resposta de amostra

Response Status:  
HTTP/1.1 201 Created  

Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

Autorização

Esta operação pode ser chamada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso partilhado com permissões para escrever neste ficheiro ou na partilha de ficheiros do Azure.

Observações

A Put Range From URL operação escreve um intervalo de dados num ficheiro. Se a API for chamada num ficheiro inexistente no destino, a API devolve o código de estado HTTP 404 (Não Encontrado).

Na versão 2020-10-02 e posterior, Microsoft Entra autorização é suportada para a origem da operação de cópia.

Para criar um novo ficheiro, chame Create File.

Put Range From URL operation returns success 201 (Created) only if the specified range is written to the file.

Operação de leitura de ficheiros
Put Range From URL utiliza Get File para ler dados e metadados, atributos e ACLs da origem.

Operação de atualização de ficheiros
Chamar Put Range From URL com a opção "atualizar" efetua uma escrita no local no ficheiro especificado. Qualquer conteúdo no ficheiro especificado é substituído pela atualização.  

O tamanho do Put Range From URL intervalo na operação para uma operação de atualização pode ter até 4 MiB de tamanho. Se tentar carregar um intervalo superior a 4 MiB, Ficheiros do Azure devolve o código de estado 413 (RequestEntityTooLarge).

Partilhar via