Partilhar via


Conteúdo do Blob de Consulta

A Query Blob Contents operação aplica uma instrução linguagem SQL (Structured Query Language) (SQL) simples nos conteúdos de um blob e devolve apenas o subconjunto consultado dos dados. Também pode ligar Query Blob Contents para consultar o conteúdo 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 de 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 URI

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

Parâmetro Description
snapshot Opcional. O parâmetro instantâneo é um valor opaco DateTime . Quando está presente, especifica o instantâneo de blobs a consultar. Para obter mais informações sobre como trabalhar com instantâneos de blobs, veja Create um instantâneo de um blob.
versionid Opcional, versão 2019-12-12 e posterior. O versionid parâmetro é um valor opaco DateTime . Quando está 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 CORS (Cross-Origin Resource Sharing) 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 o conteúdo do blob apenas se for cumprida uma condição especificada. 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. Grupos o conjunto de definições do 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. Grupos as definições relativas à serialização de entrada do conteúdo do blob. Se não for especificado, é utilizada a configuração de texto delimitado.
Format Necessário se InputSerialization for especificado. Grupos 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, csve json.
DelimitedTextConfiguration Opcional. Grupos as definições que são utilizadas para interpretar os dados de blob se o blob estiver formatado 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. Grupos as definições que são utilizadas para interpretar os dados de blob 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. Grupos 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. Grupos 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. Grupos as definições utilizadas para formatar a resposta se a resposta tiver formatação JSON.
RecordSeparator Opcional. Indica a cadeia utilizada para separar registos.
ArrowConfiguration Opcional. Grupos as definições utilizadas para formatar a resposta se a resposta tiver formatação de seta.
Schema Necessário se ArrowConfiguration for especificado. Grupos as definições relativas ao esquema da resposta de Seta devolvida.
Field Opcional. Grupos definições 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.

Importante

A Microsoft recomenda a utilização de Microsoft Entra ID com identidades geridas para autorizar pedidos para o Armazenamento do Azure. Microsoft Entra ID fornece segurança e facilidade de utilização superiores em comparação com a autorização de Chave Partilhada.

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 Microsoft Entra, grupo, identidade gerida ou principal de serviço chame a Query Blob Contents operação e a função RBAC do Azure com menos privilégios que inclua esta ação:

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.

Observações

  • A Query Blob Contents operação é suportada apenas 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 que tenham a 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 Consultas Blob de blocos Premium
Standard para fins gerais v2
Operaçõesde leitura 1

1Além de um custo de leitura, a conta incorre em custos para as categorias Aceleração de Consulta – Análise de Dados eAceleraçã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 Azuree códigos de erro Códigos de erro do Armazenamento de BlobsDefinir tempos limite para operações do Armazenamento de BlobsAceleração de consultas: referência de linguagem SQL