Compartilhar via


Colocar o intervalo da URL

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 Sim
NFS Não

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 para o 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 Microsoft Entra.
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 inválida).
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 fonte 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, Microsoft Entra autorização tem suporte 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).