Conteúdo do Blob de Consultas

Artigo
02/12/2024

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

Solicitação

Você pode construir a solicitação da Query Blob Contents seguinte maneira. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento.

URI de solicitação 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

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:

Parâmetro	Descrição
`snapshot`	Opcional. O parâmetro instantâneo é um valor opaco`DateTime`. Quando ele está presente, ele especifica o instantâneo de blob a ser consultado. Para obter mais informações sobre como trabalhar com instantâneos de blob, 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 ele está presente, ele especifica a versão do blob a ser recuperada.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais:

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autenticação, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`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`	Obrigatório para todas as solicitações autenticadas, opcional para solicitações anônimas. 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.
`Content-Type`	Obrigatórios. O valor desse cabeçalho deve ser `application/xml; charset=UTF-8`.
`x-ms-lease-id:<ID>`	Opcional. Se esse cabeçalho for especificado, a operação será executada apenas se as seguintes condições forem atendidas: - A concessão do blob está ativa no momento. - A ID de concessão especificada na solicitação corresponde à do blob. Se esse cabeçalho for especificado e nenhuma dessas condições for atendida, a solicitação não será feita e ocorrerá uma falha na operação `Query Blob Contents` com o código de status 412 (Falha na Pré-condição).
`Origin`	Opcional. Especifica a origem da qual a solicitação será emitida. A presença desse cabeçalho resulta em cabeçalhos CORS (Compartilhamento de Recursos entre Origens) na resposta.
`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.

Essa operação também dá suporte ao uso de cabeçalhos condicionais para consultar o conteúdo do blob somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da solicitação

O corpo da solicitação para esta versão do Query Blob Contents usa 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 a seguir descreve os elementos do corpo da solicitação:

Nome do elemento	Descrição
`QueryRequest`	Obrigatórios. Agrupa o conjunto de configurações de solicitação de consulta.
`QueryType`	Obrigatórios. Indica o tipo da expressão de consulta fornecida. O único valor válido para a versão atual é `SQL`.
`Expression`	Obrigatórios. 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 de expressão, consulte Aceleração de consulta: referência de linguagem SQL.
`InputSerialization`	Opcional. Agrupa as configurações relativas à serialização de entrada do conteúdo do blob. Se não for especificado, a configuração de texto delimitado será usada.
`Format`	Obrigatório se `InputSerialization` for especificado. Agrupa as configurações em relação ao formato dos dados de blob.
`Type`	Obrigatório se `InputSerialization` for especificado. Indica o tipo de formato. Os valores válidos são `delimited`, `csv` e `json`.
`DelimitedTextConfiguration`	Opcional. Agrupa as configurações usadas para interpretar os dados de blob se o blob for formatado com texto delimitado.
`ColumnSeparator`	Opcional. Indica a cadeia de caracteres usada para separar colunas.
`FieldQuote`	Opcional. Indica a cadeia de caracteres usada para citar um campo específico.
`RecordSeparator`	Opcional. Indica a cadeia de caracteres usada para separar registros.
`EscapeChar`	Opcional. Indica a cadeia de caracteres usada como um caractere de escape.
`HasHeaders`	Opcional. Especifica um Boolean que representa se os dados têm cabeçalhos.
`JsonTextConfiguration`	Opcional. Agrupa as configurações usadas para interpretar os dados de blob se o blob for formatado em JSON.
`RecordSeparator`	Opcional. Indica a cadeia de caracteres usada para separar registros.
`OutputSerialization`	Opcional. Indica o formato de serialização do conteúdo filtrado do blob retornado na resposta. Se não for especificado, a configuração de texto delimitado será usada.
`Format`	Obrigatório se `OutputSerialization` for especificado. Agrupa as configurações em relação ao formato da resposta retornada.
`Type`	Obrigató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 configurações usadas para formatar a resposta se a resposta deve ser formatada com texto delimitado.
`ColumnSeparator`	Opcional. Indica a cadeia de caracteres usada para separar colunas.
`FieldQuote`	Opcional. Indica a cadeia de caracteres usada para citar um campo específico.
`RecordSeparator`	Opcional. Indica a cadeia de caracteres usada para separar registros.
`EscapeChar`	Opcional. Indica a cadeia de caracteres usada como um caractere de escape.
`HasHeaders`	Opcional. Especifica um Boolean que representa se os dados têm cabeçalhos.
`JsonTextConfiguration`	Opcional. Agrupa as configurações usadas para formatar a resposta se a resposta deve ser formatada em JSON.
`RecordSeparator`	Opcional. Indica a cadeia de caracteres usada para separar registros.
`ArrowConfiguration`	Opcional. Agrupa as configurações usadas para formatar a resposta se a resposta deve ser formatada por seta.
`Schema`	Obrigatório se `ArrowConfiguration` for especificado. Agrupa as configurações relativas ao esquema da resposta de seta retornada.
`Field`	Opcional. Configurações de grupos relacionadas a um campo específico.
`Type`	Obrigató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 status HTTP, um conjunto de cabeçalhos de resposta e o corpo de resposta. O corpo da resposta está no formato binário Avro. Como o comprimento do conteúdo da resposta é desconhecido, a resposta é transmitida com codificação em partes.

Código de status

Se a solicitação de consulta estiver bem formada e autorizada, a operação retornará status código 202 (Aceito). Quaisquer erros ou mensagens de progresso encontradas durante o streaming de resposta serão retornados como parte do corpo da resposta.

Para obter 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 HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Sintaxe	Descrição
`Last-Modified`	Indica a data/hora em que o blob foi modificado pela última vez. O formato da data segue RFC 1123. Qualquer operação que modificar o blob, incluindo uma atualização dos metadados ou das propriedades do blob, alterará a hora da última modificação do blob.
`Content-Type`	Especifica o formato em que os resultados são retornados. Atualmente, esse valor é `avro/binary`.
`ETag`	Contém um valor que você pode usar para executar operações condicionalmente. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs. Se a versão da solicitação for 2011-08-18 ou posterior, o `ETag` valor estará entre aspas.
`Content-Encoding`	Retorna o valor especificado para o cabeçalho da solicitação `Content-Encoding` .
`Content-Language`	Retorna o valor especificado para o cabeçalho da solicitação `Content-Language` .
`Cache-Control`	Retornado se esse cabeçalho tiver sido especificado anteriormente para o blob.
`Content-Disposition`	Retornado para solicitações na versão 2013-08-15 e mais recente. Esse cabeçalho retorna o valor que foi especificado para o cabeçalho `x-ms-blob-content-disposition`. O `Content-Disposition` campo de cabeçalho de resposta transmite informações adicionais sobre como processar o conteúdo da resposta. Você também pode usar o campo de cabeçalho de resposta para anexar metadados adicionais. Por exemplo, se o campo de cabeçalho de resposta estiver definido como `attachment`, o agente do usuário não deverá exibir a resposta. Em vez disso, ele deve mostrar uma caixa de diálogo Salvar como com um nome de arquivo diferente do nome do blob especificado.
`x-ms-blob-type: <BlockBlob>`	Retorna o tipo de blob.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita. Você pode usá-lo 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 de Armazenamento de Blobs do Azure usada para executar a solicitação. Incluído para solicitações feitas usando a versão 2009-09-19 e posterior. Esse cabeçalho também será retornado para solicitações anônimas sem uma versão especificada, se o contêiner tiver sido marcado para acesso público usando 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`	Retornado se a solicitação incluir um cabeçalho `Origin` e CORS estiver habilitado com uma regra de correspondência. Este cabeçalho retorna o valor do cabeçalho de solicitação de origem no caso de uma correspondência.
`Access-Control-Expose-Headers`	Retornado se a solicitação incluir um cabeçalho `Origin` e CORS estiver habilitado com uma regra de correspondência. Esse cabeçalho retorna a lista de cabeçalhos de resposta que serão expostos ao cliente ou emissor da solicitação.
`Vary`	Retornado com o valor do cabeçalho `Origin` quando as regras de CORS são especificadas. Para obter detalhes, confira Suporte do CORS para o Armazenamento do Azure.
`Access-Control-Allow-Credentials`	Retornado se a solicitação incluir um `Origin` cabeçalho e CORS estiver habilitado com uma regra correspondente que não permita todas as origens. Esse cabeçalho é definido como `true`.
`x-ms-blob-committed-block-count`	Indica o número de blocos confirmados presentes no blob. Esse cabeçalho é retornado somente para blobs de acréscimo.
`x-ms-server-encrypted: true/false`	Versão 2015-12-11 ou posterior. O valor desse cabeçalho será definido `true` como se os dados de blob e os metadados do aplicativo forem completamente criptografados por meio do algoritmo especificado. Quando o blob é descriptografado ou se apenas partes dos metadados de blob/aplicativo forem criptografadas, o valor será definido `false`como .

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. Ele usa 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 exemplo

      "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. Você pode autorizar a Query Blob Contents operação, conforme descrito abaixo.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Query Blob Contents operação e a função RBAC interna 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 interna com privilégios mínimos:Leitor de Dados do Blob de Armazenamento

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Uma SAS (assinatura de acesso compartilhado) fornece acesso delegado seguro aos recursos em uma conta de armazenamento. Com uma SAS, você tem controle granular sobre como um cliente pode acessar dados. Você pode especificar qual recurso o cliente pode acessar, quais permissões eles têm para esses recursos e por quanto tempo a SAS é válida.

A Query Blob Contents operação dá suporte a três tipos de assinaturas de acesso compartilhado: SAS de delegação de usuário, SAS de serviço e SAS de conta.

Como prática recomendada de segurança, recomendamos que você use Microsoft Entra credenciais em vez da chave da conta de armazenamento, que pode ser comprometida com mais facilidade. Se o design do aplicativo exigir assinaturas de acesso compartilhado, use Microsoft Entra credenciais para criar uma SAS de delegação de usuário, quando possível.

Quando o acesso à Chave Compartilhada não for permitido para a conta de armazenamento, um token SAS de serviço ou um token SAS de conta não será permitido em uma solicitação para o Armazenamento de Blobs. Para saber mais, confira Entender como a não permissão de Chave Compartilhada afeta tokens SAS.

SAS de delegação do usuário

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

Chamar a Query Blob Contents operação usando um token SAS delegado a um recurso de contêiner ou blob requer a permissão Leitura (r) como parte do token SAS de delegação do usuário.

Para saber mais sobre a SAS de delegação de usuário, consulte Criar uma SAS de delegação de usuário.

SAS de serviço

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

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

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

SAS de Conta

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

A tabela a seguir indica o tipo de recurso assinado e as permissões assinadas a serem especificadas ao delegar o acesso:

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

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

A Query Blob Contents operação dá suporte à autorização de Chave Compartilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, pois é menos segura.

A Microsoft recomenda não permitir a autorização de Chave Compartilhada para a conta de armazenamento quando possível. Para obter mais informações, consulte Impedir autorização com chave compartilhada.

Comentários

A Query Blob Contents operação tem suporte apenas em um BlockBlob tipo.
Não há suporte para consultar o conteúdo de um blob criptografado com chaves fornecidas pelo cliente nesta versão da API.
Não há suporte para essa operação em blobs em contas que tenham a criptografia de infraestrutura habilitada.
O cabeçalho x-ms-version é necessário para recuperar um blob que pertence a um contêiner privado. Se o blob pertencer a um contêiner disponível para acesso público completo ou parcial, qualquer cliente poderá lê-lo sem especificar uma versão. A versão do serviço não é necessária para recuperar um blob que pertence a um contêiner público. Para saber mais, confira Restringir o acesso a contêineres e blobs.
Você pode usar a Query Blob Contents operação para consultar apenas objetos que têm formato delimitado/CSV ou JSON.

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para Query Blob Contents solicitações com base no tipo de conta de armazenamento:

Operação	Tipo de conta de armazenamento	Categoria de cobrança
Conteúdo do Blob de Consultas	Blob de blocos Premium Uso geral v2 Standard	Operações^{de leitura 1}

¹Além de uma cobrança de leitura, a conta incorre em encargos para as categorias Aceleração de Consulta – Dados Verificados e Aceleração de Consulta – Dados Retornados . Os preços dessas categorias são exibidos na página de preços Azure Data Lake Storage.

Confira também

Autorizar solicitações para o Status 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 consulta: referência de linguagem SQL