Colocar intervalo da URL

Artigo
03/29/2023

A Put Range From URL operação cria um novo intervalo a ser confirmado como parte de um arquivo em que o conteúdo é lido de uma URL. Essa API está disponível a partir da versão 2019-02-02.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Solicitação

A solicitação Put Range From URL pode ser criada da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

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

Parâmetros do URI

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 Arquivos do Azure.

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. Confira Autorizar solicitações ao Armazenamento do Azure para obter mais informações.
`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. Para `Put Range From URL`, a versão deve ser 2019-02-02 ou posterior.
`x-ms-copy-source:name`	Obrigatórios. Especifica a URL do arquivo de origem. O valor pode ser uma URL de até 2 KiB de comprimento que especifica um arquivo. O valor deve ser codificado em URL tal como apareceria em um pedido URI. O arquivo de origem deve ser público ou deve ser autorizado por meio de uma assinatura de acesso compartilhado. Se o arquivo de origem for público, nenhuma autorização será necessária para executar a operação. Aqui estão alguns exemplos de URLs de objeto 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 para a origem da cópia. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure. Somente o portador do esquema tem suporte para o Azure Active Directory. Esse cabeçalho tem suporte na versão 2020-10-02 e posterior.
`x-ms-write: { update }`	Obrigatórios. Você deve especificar apenas `update`. A solicitação falhará se for chamada com `clear`. O `update` valor grava os bytes especificados pelo corpo da solicitação nos intervalos especificados.
`Range` ou `x-ms-range`	Obrigatórios. `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. Arquivos do Azure 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 Arquivos do Azure.
`x-ms-source-range`	Obrigatórios. Especifica o intervalo de bytes a serem lidos da origem. É necessário especificar o início e o fim do intervalo. Arquivos do Azure 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`. O intervalo de origem pode ter até 4 MiB de tamanho. Se o tamanho do intervalo de origem exceder 4 MiB, Arquivos do Azure retornará status código 413 (Entidade de Solicitação Muito Grande). Se o tamanho do intervalo de origem não corresponder ao tamanho do intervalo (intervalo de destino), o serviço retornará status código 400 (Solicitação Incorreta).
`Content-Length`	Obrigatórios. Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. O valor deste cabeçalho deve ser definido como `0`. Quando o comprimento não `0`é , a operação falha com o código status 400 (Solicitação Incorreta).
`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-source-content-crc64`	Opcional. Um hash CRC64 do intervalo especificado do URI. Esse hash é usado para verificar a integridade do intervalo durante o transporte dos dados do URI. Quando esse cabeçalho é especificado, Arquivos do Azure compara o hash do conteúdo que chegou da fonte de cópia com esse valor de cabeçalho. Observação: esse hash CRC64 não é armazenado com o arquivo . Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).
`x-ms-source-if-match-crc64`	Opcional. Um valor de soma de verificação CRC64. Especifique esse cabeçalho para executar a operação somente se a soma de verificação do intervalo determinado lido da origem corresponder à soma de verificação fornecida. Se a condição especificada não for atendida, Arquivos do Azure retornará status código 412 (Falha na pré-condição).
`x-ms-source-if-none-match-crc64`	Opcional. Um valor de soma de verificação CRC64. Especifique esse cabeçalho para executar a operação somente se a soma de verificação do intervalo determinado lido da origem for diferente da soma de verificação fornecida. Se a condição especificada não for atendida, Arquivos do Azure retornará status código 412 (Falha na pré-condição).
`x-ms-lease-id:<ID>`	Obrigatório se o arquivo tiver uma concessão ativa. Para executar essa operação em um arquivo com uma concessão ativa, especifique a ID de concessão válida para esse cabeçalho.
`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 de análise quando o log de Análise de Armazenamento do Azure está habilitado. É altamente recomendável que você use esse cabeçalho ao correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar o Armazenamento de Blobs.
`x-ms-file-last-write-time: { now ¦ preserve }`	Opcional. Versão 2021-06-08 e posterior. Você pode especificar uma das seguintes opções: `now`: valor padrão. Atualizações o carimbo de data/hora da última gravação na hora da solicitação. `preserve`: mantém o carimbo de data/hora da última gravação existente inalterado.
`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.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Opcional. Versão 2022-11-02 e posterior. O valor booliano especifica se um ponto à direita presente na URL de origem deve ser cortado ou não. Esse cabeçalho só deverá ser especificado se a origem da cópia for um Arquivo do Azure. Não há suporte para esse cabeçalho para nenhum outro tipo de origem de cópia. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Corpo da solicitação

Nenhum corpo da solicitação.

Solicitação 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 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`	Contém um valor que você pode usar para executar operações condicionalmente. O valor é colocado entre aspas.
`Last-Modified`	A data e a hora em que o arquivo foi modificado pela última vez. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores de data/hora em cabeçalhos. Qualquer operação de gravação no arquivo, incluindo atualizações nos metadados ou propriedades do arquivo, altera a hora da última modificação do arquivo.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita e você pode usá-la 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 da API FileREST 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-content-crc64`	Retornado para que o cliente possa marcar quanto à integridade do conteúdo da mensagem. O valor desse cabeçalho é calculado por Arquivos do Azure. Não é necessariamente o mesmo que o valor especificado nos cabeçalhos de solicitação.
`x-ms-client-request-id`	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 (por exemplo, `2017-05-10T17:52:33.9551861Z`).

Resposta de exemplo

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

Essa operação pode ser chamada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso compartilhado com permissões para gravar nesse arquivo ou no compartilhamento de arquivos do Azure.

Comentários

A Put Range From URL operação grava um intervalo de dados em um arquivo. Se a API for chamada em um arquivo inexistente no destino, a API retornará HTTP status código 404 (Não Encontrado).

Na versão 2020-10-02 e posterior, há suporte para a autorização do Azure Active Directory para a origem da operação de cópia.

Para criar um novo arquivo, chame Create File.

Put Range From URL A operação retornará êxito 201 (Criado) somente se o intervalo especificado for gravado no arquivo.

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

Operação de atualização de arquivo
Chamar Put Range From URL com a opção "atualizar" executa uma gravação in-loco no arquivo especificado. Qualquer conteúdo no arquivo especificado é substituído pela atualização.  

O tamanho do intervalo na Put Range From URL operação para uma operação de atualização pode ter até 4 MiB de tamanho. Se você tentar carregar um intervalo maior que 4 MiB, Arquivos do Azure retornará status código 413 (RequestEntityTooLarge).