Consultar el contenido del blob

Artículo
02/07/2024

La Query Blob Contents operación aplica una instrucción Lenguaje de consulta estructurado simple (SQL) en el contenido de un blob y devuelve solo el subconjunto consultado de los datos. También puede llamar Query Blob Contents a para consultar el contenido de una versión o instantánea.

Solicitud

Puede construir la solicitud de la Query Blob Contents siguiente manera. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento.

URI de solicitud de método POST	Versión de 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 del identificador URI

Puedes especificar los siguientes parámetros adicionales en el URI de la solicitud:

Parámetro	Descripción
`snapshot`	Opcional. El parámetro snapshot es un valor opaco `DateTime` . Cuando está presente, especifica la instantánea de blob que se va a consultar. Para más información sobre cómo trabajar con instantáneas de blob, consulte Creación de una instantánea de un blob.
`versionid`	Opcional, versión 2019-12-12 y posteriores. El `versionid` parámetro es un valor opaco `DateTime` . Cuando está presente, especifica la versión del blob que se va a recuperar.
`timeout`	Opcional. El parámetro `timeout` se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales:

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autenticación, el nombre de la cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`Date` o `x-ms-date`	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`x-ms-version`	Obligatorio para todas las solicitudes autenticadas, opcional para las solicitudes anónimas. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
`Content-Type`	Necesario. El valor de este encabezado debe ser `application/xml; charset=UTF-8`.
`x-ms-lease-id:<ID>`	Opcional. Si se especifica este encabezado, la operación se realizará solo si se cumplen las dos condiciones siguientes: - La concesión del blob está activa actualmente. : el identificador de concesión especificado en la solicitud coincide con el del blob. Si se especifica este encabezado y no se cumplen ambas condiciones, la solicitud producirá un error y la operación `Query Blob Contents` generará un error con el código de estado 412 (Error de condición previa).
`Origin`	Opcional. Especifica el origen del que se emitirá la solicitud. La presencia de este encabezado da como resultado encabezados de uso compartido de recursos entre orígenes (CORS) en la respuesta.
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor.

Esta operación también admite el uso de encabezados condicionales para consultar el contenido del blob solo si se cumple una condición especificada. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

Cuerpo de la solicitud

El cuerpo de la solicitud para esta versión de Query Blob Contents usa el siguiente 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>

La tabla siguiente describe los elementos del cuerpo de la solicitud:

Nombre del elemento	Descripción
`QueryRequest`	Necesario. Agrupa el conjunto de configuraciones de solicitud de consulta.
`QueryType`	Necesario. Indica el tipo de la expresión de consulta proporcionada. El único valor válido para la versión actual es `SQL`.
`Expression`	Necesario. Indica la expresión de consulta en SQL. El tamaño máximo de la expresión de consulta es 256 KiB. Para obtener más información sobre la sintaxis de la expresión, vea Aceleración de consultas: referencia del lenguaje SQL.
`InputSerialization`	Opcional. Agrupa la configuración con respecto a la serialización de entrada del contenido del blob. Si no se especifica, se usa la configuración de texto delimitada.
`Format`	Requerido si se especifica `InputSerialization`. Agrupa la configuración con respecto al formato de los datos de blob.
`Type`	Requerido si se especifica `InputSerialization`. Indica el tipo de formato. Valores válidos son `delimited`, `csv` y `json`.
`DelimitedTextConfiguration`	Opcional. Agrupa la configuración que se usa para interpretar los datos del blob si el blob tiene formato con texto delimitado.
`ColumnSeparator`	Opcional. Indica la cadena que se usa para separar columnas.
`FieldQuote`	Opcional. Indica la cadena que se usa para comillas de un campo específico.
`RecordSeparator`	Opcional. Indica la cadena que se usa para separar los registros.
`EscapeChar`	Opcional. Indica la cadena que se usa como carácter de escape.
`HasHeaders`	Opcional. Especifica un valor booleano que representa si los datos tienen encabezados.
`JsonTextConfiguration`	Opcional. Agrupa la configuración que se usa para interpretar los datos del blob si el blob tiene formato JSON.
`RecordSeparator`	Opcional. Indica la cadena que se usa para separar los registros.
`OutputSerialization`	Opcional. Indica el formato de serialización del contenido filtrado del blob devuelto en la respuesta. Si no se especifica, se usa la configuración de texto delimitada.
`Format`	Requerido si se especifica `OutputSerialization`. Agrupa la configuración con respecto al formato de la respuesta devuelta.
`Type`	Requerido si se especifica `OutputSerialization`. Indica el tipo de formato. Los valores válidos son `delimited`, `csv`, `json` y `arrow`.
`DelimitedTextConfiguration`	Opcional. Agrupa la configuración que se usa para dar formato a la respuesta si la respuesta debe tener formato con texto delimitado.
`ColumnSeparator`	Opcional. Indica la cadena que se usa para separar columnas.
`FieldQuote`	Opcional. Indica la cadena que se usa para citar un campo específico.
`RecordSeparator`	Opcional. Indica la cadena que se usa para separar los registros.
`EscapeChar`	Opcional. Indica la cadena que se usa como carácter de escape.
`HasHeaders`	Opcional. Especifica un valor booleano que representa si los datos tienen encabezados.
`JsonTextConfiguration`	Opcional. Agrupa la configuración que se usa para dar formato a la respuesta si la respuesta debe tener formato JSON.
`RecordSeparator`	Opcional. Indica la cadena que se usa para separar los registros.
`ArrowConfiguration`	Opcional. Agrupa la configuración que se usa para dar formato a la respuesta si la respuesta debe tener el formato De flecha.
`Schema`	Requerido si se especifica `ArrowConfiguration`. Agrupa la configuración con respecto al esquema de la respuesta de flecha devuelta.
`Field`	Opcional. Agrupa la configuración con respecto a un campo específico.
`Type`	Requerido si se especifica `Field`. Indica el tipo de campo. Los valores válidos son `Int`, `Float`, `Decimal` y `Bool`.
`Precision`	Opcional. Indica la precisión del campo.
`Scale`	Opcional. Indica la escala del campo.

Response

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y el cuerpo de respuesta. El cuerpo de la respuesta está en formato binario avro. Dado que la longitud del contenido de la respuesta es desconocida, la respuesta se transmite con codificación fragmentada.

status code

Si la solicitud de consulta tiene un formato correcto y está autorizado, la operación devuelve el código de estado 202 (aceptado). Los errores o mensajes de progreso encontrados durante el streaming de respuesta se devolverán como parte del cuerpo de la respuesta.

Para obtener información sobre los códigos de estado, vea Códigos de estado y de error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir encabezados HTTP estándar adicionales. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Sintaxis	Descripción
`Last-Modified`	Indica la fecha y hora en que se modificó por última vez el blob. El formato de la fecha sigue las convenciones de RFC 1123. Cualquier operación que modifique el blob, incluida una actualización de los metadatos o las propiedades del blob, cambia la hora de la última modificación del blob.
`Content-Type`	Especifica el formato en el que se devuelven los resultados. Actualmente, este valor es `avro/binary`.
`ETag`	Contiene un valor que puede usar para realizar operaciones condicionalmente. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage. Si la versión de la solicitud es 2011-08-18 o posterior, el `ETag` valor está entre comillas.
`Content-Encoding`	Devuelve el valor especificado para el encabezado de `Content-Encoding` solicitud.
`Content-Language`	Devuelve el valor especificado para el encabezado de `Content-Language` solicitud.
`Cache-Control`	Se devuelve si este encabezado se especificó anteriormente para el blob.
`Content-Disposition`	Se devuelve para las solicitudes realizadas en la versión 2013-08-15 y posteriores. Este encabezado devuelve el valor especificado para el encabezado `x-ms-blob-content-disposition`. El `Content-Disposition` campo de encabezado de respuesta transmite información adicional sobre cómo procesar la carga de respuesta. También puede usar el campo de encabezado de respuesta para adjuntar metadatos adicionales. Por ejemplo, si el campo de encabezado de respuesta está establecido `attachment`en , el agente de usuario no debe mostrar la respuesta. En su lugar, debe mostrar un cuadro de diálogo Guardar como con un nombre de archivo distinto del nombre de blob especificado.
`x-ms-blob-type: <BlockBlob>`	Devuelve el tipo del blob.
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó. Puede usarlo para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión de Azure Blob Storage que se usa para ejecutar la solicitud. Se incluye para las solicitudes realizadas con la versión 2009-09-19 y posteriores. Este encabezado también se devuelve para las solicitudes anónimas sin una versión especificada, si el contenedor se marcó para el acceso público mediante la versión 2009-09-19 de Blob Storage.
`Date`	Valor de fecha y hora UTC que indica la hora a la que el servicio envió la respuesta.
`Access-Control-Allow-Origin`	Se devuelve si la solicitud incluye un encabezado `Origin` y se ha habilitado CORS con una regla de coincidencia. Este encabezado devuelve el valor del encabezado Origin de la solicitud en caso de que haya una coincidencia.
`Access-Control-Expose-Headers`	Se devuelve si la solicitud incluye un encabezado `Origin` y se ha habilitado CORS con una regla de coincidencia. Este encabezado devuelve la lista de encabezados de respuesta que se expondrán al cliente o emisor de la solicitud.
`Vary`	Se devuelve con el valor del encabezado `Origin` cuando se especifican reglas de CORS. Para más información, consulte Compatibilidad de CORS con Azure Storage.
`Access-Control-Allow-Credentials`	Se devuelve si la solicitud incluye un `Origin` encabezado y CORS está habilitado con una regla coincidente que no permite todos los orígenes. Este encabezado se establece en `true`.
`x-ms-blob-committed-block-count`	Indica el número de bloques confirmados presentes en el blob. Este encabezado solo se devuelve para blobs en anexos.
`x-ms-server-encrypted: true/false`	Versión 2015-12-11 o posterior. El valor de este encabezado se establece `true` en si los datos de blob y los metadatos de la aplicación se cifran completamente a través del algoritmo especificado. Cuando el blob está sin cifrar, o si solo se cifran partes de los metadatos de blob o aplicación, el valor se establece `false`en .

Response body

El cuerpo de la respuesta contiene el contenido filtrado del blob enviado como una serie de mensajes en formato binario avro. Usa el esquema siguiente:

{
    "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"
      }
    ]
  }
]

Respuesta de muestra

      "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":{...}

Authorization

Se requiere autorización al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Query Blob Contents operación como se describe a continuación.

Azure Storage admite el uso de Microsoft Entra ID para autorizar solicitudes a datos de blobs. Con Microsoft Entra ID, puede usar el control de acceso basado en rol de Azure (RBAC de Azure) para conceder permisos a una entidad de seguridad. La entidad de seguridad puede ser un usuario, un grupo, una entidad de servicio de aplicación o una identidad administrada de Azure. La entidad de seguridad se autentica mediante Microsoft Entra ID para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para más información sobre la autorización mediante Microsoft Entra ID, consulte Autorización del acceso a blobs mediante Microsoft Entra ID.

Permisos

A continuación se enumeran las acciones de RBAC necesarias para un usuario, grupo o entidad de servicio de Microsoft Entra para llamar a la Query Blob Contents operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rol integrado con privilegios mínimos:Lector de datos de Storage Blob

Para más información sobre la asignación de roles mediante RBAC de Azure, consulte Asignación de un rol de Azure para el acceso a datos de blobs.

Una firma de acceso compartido (SAS) proporciona acceso delegado seguro a los recursos de una cuenta de almacenamiento. Con una SAS, tiene un control granular sobre cómo un cliente puede acceder a los datos. Puede especificar a qué recurso puede tener acceso el cliente, a qué permisos tienen esos recursos y cuánto tiempo es válido la SAS.

La Query Blob Contents operación admite tres tipos de firmas de acceso compartido: SAS de delegación de usuarios, SAS de servicio y SAS de cuenta.

Como procedimiento recomendado de seguridad, se recomienda usar Microsoft Entra credenciales en lugar de la clave de la cuenta de almacenamiento, lo que se puede poner en peligro más fácilmente. Si el diseño de la aplicación requiere firmas de acceso compartido, use Microsoft Entra credenciales para crear una SAS de delegación de usuarios, siempre que sea posible.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá un token de SAS de servicio o un token de SAS de cuenta en una solicitud a Blob Storage. Para más información, consulte Descripción de cómo no permitir la clave compartida afecta a los tokens de SAS.

SAS de delegación de usuarios

Una SAS de delegación de usuarios se protege con credenciales de Microsoft Entra y también con los permisos especificados para la SAS.

Llamar a la Query Blob Contents operación mediante un token de SAS delegado en un contenedor o recurso de blob requiere el permiso De lectura (r) como parte del token de SAS de delegación de usuarios.

Para más información sobre la SAS de delegación de usuarios, consulte Creación de una SAS de delegación de usuarios.

SAS de servicio

Una SAS de servicio está protegida con la clave de cuenta de almacenamiento. Una SAS de servicio delega el acceso a un recurso en un único servicio de Azure Storage, como Blob Storage.

Llamar a la Query Blob Contents operación mediante un token de SAS delegado en un contenedor o recurso de blob requiere el permiso De lectura (r) como parte del token de SAS de servicio.

Para más información sobre la SAS de servicio, consulte Creación de una SAS de servicio.

SAS de cuenta

Una SAS de cuenta está protegida con la clave de cuenta de almacenamiento. SAS de cuenta delega el acceso a los recursos en uno o varios de los servicios de almacenamiento. Todas las operaciones disponibles con una SAS de servicio o delegación de usuarios están también disponibles con una SAS de cuenta.

En la tabla siguiente se indica el tipo de recurso firmado y los permisos firmados que se deben especificar al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
Consultar el contenido del blob	Blob (b)	Objeto (o)	Lectura (r)

Para más información sobre la SAS de la cuenta, consulte Creación de una SAS de cuenta.

Comentarios

La Query Blob Contents operación solo se admite en un BlockBlob tipo.
No se admite la consulta del contenido de un blob cifrado con claves proporcionadas por el cliente en esta versión de la API.
Esta operación no se admite en blobs de cuentas que tienen habilitado el cifrado de infraestructura .
El encabezado x-ms-version es necesario para recuperar un blob que pertenece a un contenedor privado. Si el blob pertenece a un contenedor que está disponible para el acceso público completo o parcial, cualquier cliente puede leerlo sin especificar una versión. La versión del servicio no es necesaria para recuperar un blob que pertenece a un contenedor público. Para obtener más información, consulte Restringir acceso a contenedores y blobs.
Puede usar la Query Blob Contents operación para consultar solo los objetos que tienen formato JSON o delimitado/CSV.

Facturación

Las solicitudes de precios se pueden originar en clientes que usan las API de Blob Storage, ya sea directamente a través de la API rest de Blob Storage o de una biblioteca cliente de Azure Storage. Estas solicitudes acumulan cargos por transacción. El tipo de transacción afecta a cómo se cobra la cuenta. Por ejemplo, las transacciones de lectura se acumulan en una categoría de facturación diferente que las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de Query Blob Contents las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
Consultar el contenido del blob	Blobs en bloques Premium De uso general, estándar, v2	Operaciones de lectura¹

¹Además de un cargo de lectura, la cuenta incurre en cargos por aceleración de consultas: aceleración de datos y aceleración de consultas: categorías de transacciones devueltas por datos . Los precios de estas categorías aparecen en la página de precios de Azure Data Lake Storage.

Consulte también

Autorización de solicitudes a códigos de error y estado de Azure Storage: Códigos de error de Blob Storage Establecer tiempos de espera para las operaciones de Blob Storage Aceleración de consultas: Referencia del lenguaje SQL