Conteúdo do Blob de Consultas

Artigo
02/03/2024

A Query Blob Contents operação aplica uma instrução de linguagem SQL (Structured Query Language) simples (SQL) no conteúdo de um blob e devolve apenas o subconjunto consultado dos dados. Também pode chamar Query Blob Contents para consultar os conteúdos de uma versão ou instantâneo.

Pedir

Pode construir o pedido da Query Blob Contents seguinte forma. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento.

URI do pedido do método POST	Versão HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&versionid=<DateTime>`	HTTP/1.0 HTTP/1.1

Parâmetros do URI

Pode especificar os seguintes parâmetros adicionais no URI do pedido:

Parâmetro	Description
`snapshot`	Opcional. O parâmetro de instantâneo é um valor opaco `DateTime` . Quando estiver presente, especifica o instantâneo de blob a consultar. Para obter mais informações sobre como trabalhar com instantâneos de blobs, consulte Criar um instantâneo de um blob.
`versionid`	Opcional, versão 2019-12-12 e posterior. O `versionid` parâmetro é um valor opaco `DateTime` . Quando estiver presente, especifica a versão do blob a obter.
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais:

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autenticaçã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 autenticados, opcional para pedidos anónimos. 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.
`Content-Type`	Obrigatório. O valor deste cabeçalho deve ser `application/xml; charset=UTF-8`.
`x-ms-lease-id:<ID>`	Opcional. Se este cabeçalho for especificado, a operação só será efetuada se ambas as condições seguintes forem cumpridas: - A concessão do blob está atualmente ativa. - O ID de concessão especificado no pedido corresponde ao do blob. Se este cabeçalho for especificado e ambas as condições não forem cumpridas, o pedido falhará e a operação falhará com o `Query Blob Contents` código de estado 412 (Falha na Pré-condição).
`Origin`	Opcional. Especifica a origem a partir da qual o pedido é emitido. A presença deste cabeçalho resulta em cabeçalhos de Partilha de Recursos Transversais à Origem (CORS) na resposta.
`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.

Esta operação também suporta a utilização de cabeçalhos condicionais para consultar os conteúdos do blob apenas se uma condição especificada for cumprida. Para obter mais informações, veja Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo do pedido

O corpo do pedido para esta versão do Query Blob Contents utiliza o seguinte formato XML:

<?xml version="1.0" encoding="utf-8"?>  
<QueryRequest>
  <QueryType>String</QueryType>
  <Expression>String</Expression>
  <InputSerialization>
    <Format>
      <Type>String</Type>
          <DelimitedTextConfiguration>
            <ColumnSeparator>String</ColumnSeparator>
            <FieldQuote>String</FieldQuote>
            <RecordSeparator>String</RecordSeparator>
            <EscapeChar>String</EscapeChar>
            <HasHeaders>Boolean</HasHeaders>
          </DelimitedTextConfiguration>
          <JsonTextConfiguration>
            <RecordSeparator>String</RecordSeparator>
          </JsonTextConfiguration>
    </Format>
  </InputSerialization>
  <OutputSerialization>
    <Format>
      <Type>String</Type>
      <DelimitedTextConfiguration>
        <ColumnSeparator>String</ColumnSeparator >
        <FieldQuote>String</FieldQuote >
        <RecordSeparator>String</RecordSeparator>
        <EscapeChar>String</EscapeChar>
        <HasHeaders>Boolean</HasHeaders>
      </DelimitedTextConfiguration>
      <JsonTextConfiguration>
        <RecordSeparator>String</RecordSeparator>
      </JsonTextConfiguration>
      <ArrowConfiguration>
        <Schema>
            <Field>
                <Type>String</Type>
                <Name>String</Name>
            </Field>
            <Field>
                <Type>String</Type>
            </Field>
                .
                .
                .
            <Field>
                <Type>String</Type>
                <Precision>Integer</Precision>
                <Scale>Integer</Scale>
            </Field>
        </Schema>
      </ArrowConfiguration>
    </Format>
  </OutputSerialization>
</QueryRequest>

A tabela seguinte descreve os elementos do corpo do pedido:

Nome do elemento	Description
`QueryRequest`	Obrigatório. Agrupa o conjunto de definições de pedido de consulta.
`QueryType`	Obrigatório. Indica o tipo da expressão de consulta fornecida. O único valor válido para a versão atual é `SQL`.
`Expression`	Obrigatório. Indica a expressão de consulta no SQL. O tamanho máximo da expressão de consulta é 256 KiB. Para obter mais informações sobre a sintaxe da expressão, veja Aceleração de consultas: referência de linguagem SQL.
`InputSerialization`	Opcional. Agrupa as definições relativas à serialização de entrada dos conteúdos do blob. Se não for especificado, é utilizada a configuração de texto delimitado.
`Format`	Necessário se `InputSerialization` for especificado. Agrupa as definições relativas ao formato dos dados de blobs.
`Type`	Necessário se `InputSerialization` for especificado. Indica o tipo de formato. Os valores válidos são `delimited`, `csv`e `json`.
`DelimitedTextConfiguration`	Opcional. Agrupa as definições que são utilizadas para interpretar os dados de blobs se o blob estiver formatado com texto delimitado.
`ColumnSeparator`	Opcional. Indica a cadeia utilizada para separar colunas.
`FieldQuote`	Opcional. Indica a cadeia utilizada para citar um campo específico.
`RecordSeparator`	Opcional. Indica a cadeia utilizada para separar registos.
`EscapeChar`	Opcional. Indica a cadeia que é utilizada como um caráter de escape.
`HasHeaders`	Opcional. Especifica um Booleano que representa se os dados têm cabeçalhos.
`JsonTextConfiguration`	Opcional. Agrupa as definições que são utilizadas para interpretar os dados de blobs se o blob estiver formatado em JSON.
`RecordSeparator`	Opcional. Indica a cadeia utilizada para separar registos.
`OutputSerialization`	Opcional. Indica o formato de serialização dos conteúdos filtrados do blob devolvido na resposta. Se não for especificado, é utilizada a configuração de texto delimitado.
`Format`	Necessário se `OutputSerialization` for especificado. Agrupa as definições relativas ao formato da resposta devolvida.
`Type`	Necessário se `OutputSerialization` for especificado. Indica o tipo de formato. Os valores válidos são `delimited`, `csv`, `json` e `arrow`.
`DelimitedTextConfiguration`	Opcional. Agrupa as definições utilizadas para formatar a resposta se a resposta tiver de ser formatada com texto delimitado.
`ColumnSeparator`	Opcional. Indica a cadeia utilizada para separar colunas.
`FieldQuote`	Opcional. Indica a cadeia que é utilizada para citar um campo específico.
`RecordSeparator`	Opcional. Indica a cadeia utilizada para separar registos.
`EscapeChar`	Opcional. Indica a cadeia que é utilizada como um caráter de escape.
`HasHeaders`	Opcional. Especifica um Valor Booleano que representa se os dados têm cabeçalhos.
`JsonTextConfiguration`	Opcional. Agrupa as definições que são utilizadas para formatar a resposta se a resposta tiver a formatação JSON.
`RecordSeparator`	Opcional. Indica a cadeia utilizada para separar registos.
`ArrowConfiguration`	Opcional. Agrupa as definições que são utilizadas para formatar a resposta se a resposta tiver formatação de seta.
`Schema`	Necessário se `ArrowConfiguration` for especificado. Agrupa as definições relativas ao esquema da resposta de Seta devolvida.
`Field`	Opcional. Definições de grupos relativas a um campo específico.
`Type`	Necessário se `Field` for especificado. Indica o tipo de campo. Os valores válidos são `Int`, `Float`, `Decimal` e `Bool`.
`Precision`	Opcional. Indica a precisão do campo.
`Scale`	Opcional. Indica a escala do campo.

Resposta

A resposta inclui um código de estado HTTP, um conjunto de cabeçalhos de resposta e o corpo da resposta. O corpo da resposta está no formato binário Avro. Uma vez que o comprimento do conteúdo de resposta é desconhecido, a resposta é transmitida em fluxo com codificação segmentada.

Código de estado

Se o pedido de consulta estiver bem formado e autorizado, a operação devolve o código de estado 202 (Aceite). Quaisquer erros ou mensagens de progresso encontradas durante a transmissão em fluxo de resposta serão devolvidos como parte do corpo da resposta.

Para obter 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.

Syntax	Descrição
`Last-Modified`	Indica a data/hora em que o blob foi modificado pela última vez. O formato de data segue RFC 1123. Qualquer operação que modifique o blob, incluindo uma atualização dos metadados ou propriedades do blob, altera a hora da última modificação do blob.
`Content-Type`	Especifica o formato no qual os resultados são devolvidos. Atualmente, este valor é `avro/binary`.
`ETag`	Contém um valor que pode utilizar para realizar operações condicionalmente. Para obter mais informações, veja Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs. Se a versão do pedido for 2011-08-18 ou posterior, o `ETag` valor estará entre aspas.
`Content-Encoding`	Devolve o valor especificado para o cabeçalho do `Content-Encoding` pedido.
`Content-Language`	Devolve o valor especificado para o cabeçalho do `Content-Language` pedido.
`Cache-Control`	Devolvido se este cabeçalho tiver sido especificado anteriormente para o blob.
`Content-Disposition`	Devolvido para pedidos na versão 2013-08-15 e posterior. Este cabeçalho devolve o valor especificado para o `x-ms-blob-content-disposition` cabeçalho. O `Content-Disposition` campo de cabeçalho de resposta transmite informações adicionais sobre como processar o payload de resposta. Também pode utilizar o campo de cabeçalho de resposta para anexar metadados adicionais. Por exemplo, se o campo do cabeçalho de resposta estiver definido como `attachment`, o agente de utilizador não deverá apresentar a resposta. Em vez disso, deve mostrar uma caixa de diálogo Guardar Como com um nome de ficheiro diferente do nome do blob especificado.
`x-ms-blob-type: <BlockBlob>`	Devolve o tipo do blob.
`x-ms-request-id`	Identifica exclusivamente o pedido que foi feito. 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 do Armazenamento de Blobs do Azure que é utilizada para executar o pedido. Incluído para pedidos feitos com a versão 2009-09-19 e posterior. Este cabeçalho também é devolvido para pedidos anónimos sem uma versão especificada, se o contentor tiver sido marcado para acesso público com a versão 2009-09-19 do Armazenamento de Blobs.
`Date`	Um valor de data/hora UTC que indica a hora em que o serviço enviou a resposta.
`Access-Control-Allow-Origin`	Devolvido se o pedido incluir um `Origin` cabeçalho e CORS estiver ativado com uma regra correspondente. Este cabeçalho devolve o valor do cabeçalho do pedido de origem em caso de correspondência.
`Access-Control-Expose-Headers`	Devolvido se o pedido incluir um `Origin` cabeçalho e CORS estiver ativado com uma regra correspondente. Este cabeçalho devolve a lista de cabeçalhos de resposta que serão expostos ao cliente ou emissor do pedido.
`Vary`	Devolvido com o valor do `Origin` cabeçalho quando as regras CORS são especificadas. Para obter detalhes, veja Suporte CORS para o Armazenamento do Azure.
`Access-Control-Allow-Credentials`	Devolvido se o pedido incluir um `Origin` cabeçalho e CORS estiver ativado com uma regra correspondente que não permita todas as origens. Este cabeçalho está definido como `true`.
`x-ms-blob-committed-block-count`	Indica o número de blocos consolidados presentes no blob. Este cabeçalho é devolvido apenas para blobs de acréscimo.
`x-ms-server-encrypted: true/false`	Versão 2015-12-11 ou posterior. O valor deste cabeçalho está definido como `true` se os dados de blobs e os metadados da aplicação estiverem completamente encriptados através do algoritmo especificado. Quando o blob não estiver encriptado ou se apenas partes dos metadados de blob/aplicação forem encriptadas, o valor é definido como `false`.

Corpo da resposta

O corpo da resposta contém o conteúdo filtrado do blob enviado como uma série de mensagens no formato binário Avro. Utiliza o seguinte esquema:

{
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.resultData",
    "doc": "Holds result data in the format specified for this query (CSV, JSON, etc.).",
    "fields": [
      {
        "name": "data",
        "type": "bytes"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.error",
    "doc": "An error that occurred while processing the query.",
    "fields": [
      {
        "name": "fatal",
        "type": "boolean",
        "doc": "If true, this error prevents further query processing.  More result data may be returned, but there is no guarantee that all of the original data will be processed.  If false, this error does not prevent further query processing."
      },
      {
        "name": "name",
        "type": "string",
        "doc": "The name of the error"
      },
      {
        "name": "description",
        "type": "string",
        "doc": "A description of the error"
      },
      {
        "name": "position",
        "type": "long",
        "doc": "The blob offset at which the error occurred"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.progress",
    "doc": "Information about the progress of the query",
    "fields": [
      {
        "name": "bytesScanned",
        "type": "long",
        "doc": "The number of bytes that have been scanned"
      },
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.end",
    "doc": "Sent as the final message of the response, indicating that all results have been sent.",
    "fields": [
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  }
]

Resposta de amostra

      "StatusCode": 200,
      "ResponseHeaders": {
        "Content-Type": "avro/binary",
        "Date": "Fri, 24 Apr 2020 20:25:42 GMT",
        "ETag": "\u00220x8D7E88DA9C0A75B\u0022",
        "Last-Modified": "Fri, 24 Apr 2020 20:25:43 GMT",
        "Transfer-Encoding": "chunked",
        "x-ms-blob-type": "BlockBlob",
        "x-ms-client-request-id": "f6d1983c-55e5-9f95-6d3d-80d74862d99e",
        "x-ms-creation-time": "Fri, 24 Apr 2020 20:25:43 GMT",
        "x-ms-lease-state": "available",
        "x-ms-lease-status": "unlocked",
        "x-ms-request-id": "46c09ab1-b01e-0001-1076-1acef2000000",
        "x-ms-version": "2019-12-12"
	},
	"ResponseBody":{...}

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Pode autorizar a Query Blob Contents operação conforme descrito abaixo.

O Armazenamento do Azure suporta a utilização de Microsoft Entra ID para autorizar pedidos para dados de blobs. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções do Azure (RBAC do Azure) para conceder permissões a um principal de segurança. O principal de segurança pode ser um utilizador, grupo, principal de serviço de aplicação ou identidade gerida do Azure. O principal de segurança é autenticado por Microsoft Entra ID para devolver um token OAuth 2.0. Em seguida, o token pode ser utilizado para autorizar um pedido contra o serviço Blob.

Para saber mais sobre a autorização através de Microsoft Entra ID, veja Autorizar o acesso a blobs com Microsoft Entra ID.

Permissões

Abaixo estão listadas as ações RBAC necessárias para que um utilizador, grupo ou principal de serviço Microsoft Entra chame a Query Blob Contents operação e a função RBAC do Azure com menos privilégios que inclua esta ação:

Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Função incorporada com menos privilégios:Leitor deDados de Blobs de Armazenamento

Para saber mais sobre como atribuir funções com o RBAC do Azure, veja Atribuir uma função do Azure para acesso a dados de blobs.

Uma assinatura de acesso partilhado (SAS) fornece acesso delegado seguro aos recursos numa conta de armazenamento. Com uma SAS, tem controlo granular sobre como um cliente pode aceder aos dados. Pode especificar o recurso a que o cliente pode aceder, que permissões têm para esses recursos e quanto tempo a SAS é válida.

A Query Blob Contents operação suporta três tipos de assinaturas de acesso partilhado: SAS de delegação de utilizador,SAS de serviço e SAS de conta.

Como melhor prática de segurança, recomendamos que utilize Microsoft Entra credenciais em vez da chave da conta de armazenamento, que podem ser mais facilmente comprometidas. Se a estrutura da aplicação exigir assinaturas de acesso partilhado, utilize Microsoft Entra credenciais para criar uma SAS de delegação de utilizador, sempre que possível.

Quando o acesso à Chave Partilhada não for permitido para a conta de armazenamento, não será permitido um token de SAS de serviço ou um token de SAS de conta num pedido para o Armazenamento de Blobs. Para saber mais, veja Compreender como a desativação da Chave Partilhada afeta os tokens de SAS.

SAS de delegação de utilizadores

Uma SAS de delegação de utilizador é protegida com credenciais de Microsoft Entra e também pelas permissões especificadas para a SAS.

Chamar a Query Blob Contents operação com um token de SAS delegado a um contentor ou recurso de blob requer a permissão De Leitura (r) como parte do token SAS de delegação de utilizador.

Para saber mais sobre a SAS de delegação de utilizador, veja Criar uma SAS de delegação de utilizador.

SAS de Serviço

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Um serviço SAS delega o acesso a um recurso num único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Chamar a Query Blob Contents operação com um token de SAS delegado a um contentor ou recurso de blob requer a permissão de Leitura (r) como parte do token saS do serviço.

Para saber mais sobre a SAS do serviço, veja Criar uma SAS de serviço.

SAS de Conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma conta SAS delega o acesso aos recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis através de um serviço ou saS de delegação de utilizador também estão disponíveis através de uma SAS de conta.

A tabela seguinte indica o tipo de recurso assinado e as permissões assinadas para especificar ao delegar o acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Conteúdo do Blob de Consulta	Blob (b)	Objeto (o)	Ler (r)

Para saber mais sobre a SAS da conta, consulte Criar uma SAS de conta.

A Query Blob Contents operação suporta autorização de Chave Partilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, uma vez que é menos segura.

A Microsoft recomenda a desativação da autorização da Chave Partilhada para a conta de armazenamento sempre que possível. Para obter mais informações, veja Impedir autorização com Chave Partilhada.

Observações

A Query Blob Contents operação só é suportada num BlockBlob tipo.
A consulta do conteúdo de um blob encriptado com chaves fornecidas pelo cliente não é suportada nesta versão da API.
Esta operação não é suportada em blobs em contas com encriptação de infraestrutura ativada.
O x-ms-version cabeçalho é necessário para obter um blob que pertence a um contentor privado. Se o blob pertencer a um contentor disponível para acesso público total ou parcial, qualquer cliente pode lê-lo sem especificar uma versão. A versão do serviço não é necessária para obter um blob que pertence a um contentor público. Para obter mais informações, consulte Restringir o acesso a contentores e blobs.
Pode utilizar a Query Blob Contents operação para consultar apenas objetos que tenham o formato delimitado/CSV ou JSON.

Faturação

Os pedidos de preços podem ter origem em clientes que utilizam APIs de Armazenamento de Blobs, diretamente através da API REST do Armazenamento de Blobs ou a partir de uma biblioteca de cliente do Armazenamento do Azure. Estes pedidos acumulam custos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura acumulam-se numa categoria de faturação diferente das transações de escrita. A tabela seguinte mostra a categoria de faturação dos Query Blob Contents pedidos com base no tipo de conta de armazenamento:

Operação	Tipo de conta de armazenamento	Categoria de faturação
Conteúdo do Blob de Consulta	Blob de bloco premium Standard para fins gerais v2	Operações de^{leitura 1}

¹Além de um custo de leitura, a conta incorre em custos para as categorias aceleração de consultas – Análise de Dados e Aceleração de Consultas – Dados Devolvidos . Os preços destas categorias são apresentados na página de preços do Azure Data Lake Storage.

Ver também

Autorizar pedidos para o Estado do Armazenamento do Azure e códigos de erro Códigos de erro do Armazenamento de Blobs Definir tempos limite para operações de Armazenamento de Blobs Aceleração de consultas: referência de linguagem SQL