Contenuto del BLOB di query

  • Articolo

L'operazione Query Blob Contents applica una semplice istruzione Structured Query Language (SQL) sul contenuto di un BLOB e restituisce solo il subset sottoposto a query dei dati. È anche possibile chiamare Query Blob Contents per eseguire una query sul contenuto di una versione o di uno snapshot.

Richiesta

È possibile costruire la Query Blob Contents richiesta come indicato di seguito. È consigliabile usare HTTPS. Sostituire myaccount con il nome dell'account di archiviazione.

URI della richiesta del metodo POST Versione 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

Parametri URI

Nell'URI della richiesta puoi specificare i parametri seguenti:

Parametro Descrizione
snapshot Facoltativa. Il parametro snapshot è un valore opaco DateTime . Quando è presente, specifica lo snapshot del BLOB su cui eseguire la query. Per altre informazioni sull'uso degli snapshot BLOB, vedere Creare uno snapshot di un BLOB.
versionid Facoltativa, versione 2019-12-12 e successive. Il versionid parametro è un valore opaco DateTime . Quando è presente, specifica la versione del BLOB da recuperare.
timeout facoltativo. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostare i timeout per le operazioni di archiviazione BLOB.

Intestazioni della richiesta

La tabella seguente descrive le intestazioni di richiesta obbligatorie e facoltative:

Intestazione della richiesta Descrizione
Authorization Obbligatorio. Specifica lo schema di autenticazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date o x-ms-date Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
x-ms-version Obbligatoria per tutte le richieste autenticate, facoltativa per le richieste anonime. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
Content-Type Obbligatorio. Il valore di questa intestazione deve essere application/xml; charset=UTF-8.
x-ms-lease-id:<ID> facoltativo. Se questa intestazione viene specificata, l'operazione viene eseguita solo se vengono soddisfatte entrambe le condizioni seguenti:

- Il lease del BLOB è attualmente attivo.
- L'ID lease specificato nella richiesta corrisponde a quello del BLOB.

Se questa intestazione viene specificata e tutte e due le condizioni non vengono soddisfatte, la richiesta ha esito negativo e l'operazione Query Blob Contents restituisce il codice di stato 412 (Condizione preliminare non riuscita).
Origin facoltativo. Specifica l'origine da cui proviene la richiesta. La presenza di questa intestazione genera intestazioni CORS (Cross-Origin Resource Sharing) sulla risposta.
x-ms-client-request-id facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log al momento della configurazione della registrazione. È consigliabile usare questa intestazione per correlare le attività lato client alle richieste ricevute dal server.

Questa operazione supporta anche l'uso di intestazioni condizionali per eseguire query sul contenuto del BLOB solo se viene soddisfatta una condizione specificata. Per altre informazioni, vedere Specificare intestazioni condizionali per le operazioni di archiviazione BLOB.

Testo della richiesta

Il corpo della richiesta per questa versione di Query Blob Contents utilizza il formato XML seguente:

<?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>

Nella tabella seguente vengono descritti gli elementi del corpo della richiesta:

Nome dell'elemento Descrizione
QueryRequest Obbligatorio. Raggruppa il set di impostazioni della richiesta di query.
QueryType Obbligatorio. Indica il tipo dell'espressione di query specificata. L'unico valore valido per la versione corrente è SQL.
Expression Obbligatorio. Indica l'espressione di query in SQL. La dimensione massima dell'espressione di query è 256 KiB. Per altre informazioni sulla sintassi delle espressioni, vedere Accelerazione query: Informazioni di riferimento sul linguaggio SQL.
InputSerialization facoltativo. Raggruppa le impostazioni relative alla serializzazione di input del contenuto del BLOB. Se non è specificato, viene utilizzata la configurazione del testo delimitata.
Format Obbligatorio se si specifica InputSerialization. Raggruppa le impostazioni relative al formato dei dati BLOB.
Type Obbligatorio se si specifica InputSerialization. Indica il tipo di formato. I valori validi sono delimited, csv e json.
DelimitedTextConfiguration facoltativo. Raggruppa le impostazioni usate per interpretare i dati del BLOB se il BLOB è formattato con testo delimitato.
ColumnSeparator facoltativo. Indica la stringa utilizzata per separare le colonne.
FieldQuote facoltativo. Indica la stringa utilizzata per citare un campo specifico.
RecordSeparator facoltativo. Indica la stringa utilizzata per separare i record.
EscapeChar facoltativo. Indica la stringa utilizzata come carattere di escape.
HasHeaders facoltativo. Specifica un valore booleano che indica se i dati hanno intestazioni.
JsonTextConfiguration facoltativo. Raggruppa le impostazioni usate per interpretare i dati del BLOB se il BLOB è formattato in formato JSON.
RecordSeparator facoltativo. Indica la stringa utilizzata per separare i record.
OutputSerialization facoltativo. Indica il formato di serializzazione del contenuto filtrato del BLOB restituito nella risposta. Se non è specificato, viene utilizzata la configurazione del testo delimitata.
Format Obbligatorio se si specifica OutputSerialization. Raggruppa le impostazioni relative al formato della risposta restituita.
Type Obbligatorio se si specifica OutputSerialization. Indica il tipo di formato. I valori validi sono delimited, csv, json e arrow.
DelimitedTextConfiguration facoltativo. Raggruppa le impostazioni usate per formattare la risposta se la risposta deve essere formattata con testo delimitato.
ColumnSeparator facoltativo. Indica la stringa usata per separare le colonne.
FieldQuote facoltativo. Indica la stringa usata per indicare un campo specifico.
RecordSeparator facoltativo. Indica la stringa usata per separare i record.
EscapeChar facoltativo. Indica la stringa usata come carattere di escape.
HasHeaders facoltativo. Specifica un valore booleano che rappresenta se i dati hanno intestazioni.
JsonTextConfiguration facoltativo. Raggruppa le impostazioni usate per la formattazione della risposta se la risposta deve essere formattata IN FORMATO JSON.
RecordSeparator facoltativo. Indica la stringa usata per separare i record.
ArrowConfiguration facoltativo. Raggruppa le impostazioni usate per la formattazione della risposta se la risposta deve essere formattata con freccia.
Schema Obbligatorio se si specifica ArrowConfiguration. Raggruppa le impostazioni relative allo schema della risposta freccia restituita.
Field facoltativo. Impostazioni dei gruppi relativi a un campo specifico.
Type Obbligatorio se si specifica Field. Indica il tipo di campo. I valori validi sono Int, Float, Decimal e Bool.
Precision facoltativo. Indica la precisione del campo.
Scale facoltativo. Indica la scala del campo.

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni della risposta e il corpo della risposta. Il corpo della risposta è in formato binario Avro. Poiché la lunghezza del contenuto della risposta è sconosciuta, la risposta viene trasmesso con codifica con blocchi.

Codice stato

Se la richiesta di query è ben formata e autorizzata, l'operazione restituisce il codice di stato 202 (accettato). Eventuali errori o messaggi di stato rilevati durante il flusso di risposta verranno restituiti come parte del corpo della risposta.

Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta potrebbe includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Sintassi Descrizione
Last-Modified Indica la data/ora dell'ultima modifica del BLOB. Il formato data è conforme a RFC 1123.

Le operazioni che comportano la modifica del Blob, incluso un aggiornamento dei metadati o delle proprietà del Blob, comportano la modifica dell'ora dell'ultima modifica del Blob.
Content-Type Specifica il formato in cui vengono restituiti i risultati. Attualmente, questo valore è avro/binary.
ETag Contiene un valore che è possibile usare per eseguire operazioni in modo condizionale. Per altre informazioni, vedere Specificare intestazioni condizionali per le operazioni di archiviazione BLOB. Se la versione della richiesta è 2011-08-18 o successiva, il ETag valore è tra virgolette.
Content-Encoding Restituisce il valore specificato per l'intestazione della Content-Encoding richiesta.
Content-Language Restituisce il valore specificato per l'intestazione della Content-Language richiesta.
Cache-Control Restituito se questa intestazione è stata specificata in precedenza per il BLOB.
Content-Disposition Restituita per le richieste effettuate nella versione 2013-08-15 e successive. Questa intestazione restituisce il valore che era stato specificato per l'intestazione x-ms-blob-content-disposition.

Il Content-Disposition campo intestazione della risposta fornisce informazioni aggiuntive su come elaborare il payload della risposta. È anche possibile usare il campo intestazione di risposta per collegare metadati aggiuntivi. Ad esempio, se il campo dell'intestazione di risposta è impostato su attachment, l'agente utente non deve visualizzare la risposta. Dovrebbe invece essere visualizzata una finestra di dialogo Salva con nome di file diverso dal nome del BLOB specificato.
x-ms-blob-type: <BlockBlob> Restituisce il tipo di Blob.
x-ms-request-id Identifica in modo univoco la richiesta effettuata. È possibile usarlo per risolvere la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
x-ms-version Indica la versione di Archiviazione BLOB di Azure usata per eseguire la richiesta. Incluso per le richieste effettuate con la versione 2009-09-19 e versioni successive.

Questa intestazione viene restituita anche per le richieste anonime senza una versione specificata, se il contenitore è stato contrassegnato per l'accesso pubblico usando la versione 2009-09-19 dell'archiviazione BLOB.
Date Valore di data/ora UTC che indica l'ora in cui il servizio ha inviato la risposta.
Access-Control-Allow-Origin Restituito se la richiesta include un'intestazione Origin e la condivisione CORS è abilitata con una regola di corrispondenza. Questa intestazione restituisce il valore dell'intestazione della richiesta di origine nel caso di una corrispondenza.
Access-Control-Expose-Headers Restituito se la richiesta include un'intestazione Origin e la condivisione CORS è abilitata con una regola di corrispondenza. Questa intestazione restituisce l'elenco di intestazioni di risposta che verranno esposte al client o all'autorità di certificazione della richiesta.
Vary Restituito con il valore dell'intestazione Origin quando sono specificate le regole CORS. Per informazioni dettagliate, vedere Supporto CORS per Archiviazione di Azure.
Access-Control-Allow-Credentials Restituito se la richiesta include un'intestazione e CORS è abilitata con una Origin regola corrispondente che non consente tutte le origini. Questa intestazione è impostata su true.
x-ms-blob-committed-block-count Indica il numero di blocchi di commit presenti nel BLOB. Questa intestazione viene restituita solo per i BLOB di accodamento.
x-ms-server-encrypted: true/false Versione 2015-12-11 o successiva. Il valore di questa intestazione è impostato su true se i dati BLOB e i metadati dell'applicazione vengono completamente crittografati tramite l'algoritmo specificato. Quando il BLOB non è crittografato o se vengono crittografate solo parti dei metadati BLOB/applicazione, il valore è impostato su false.

Corpo della risposta

Il corpo della risposta contiene il contenuto filtrato del BLOB inviato come serie di messaggi in formato binario Avro. Usa lo schema seguente:

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

Risposta di esempio

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

Autorizzazione

L'autorizzazione è necessaria quando si chiama qualsiasi operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione Query Blob Contents come descritto di seguito.

Archiviazione di Azure supporta l'uso di Microsoft Entra ID per autorizzare le richieste ai dati BLOB. Con Microsoft Entra ID è possibile usare il controllo degli accessi in base al ruolo di Azure per concedere le autorizzazioni a un'entità di sicurezza. L'entità di sicurezza può essere un utente, un gruppo, un'entità servizio applicazione o un'identità gestita di Azure. L'entità di sicurezza viene autenticata da Microsoft Entra ID per restituire un token OAuth 2.0. Il token può quindi essere usato per autorizzare una richiesta relativa al servizio BLOB.

Per altre informazioni sull'autorizzazione usando Microsoft Entra ID, vedere Autorizzare l'accesso ai BLOB usando Microsoft Entra ID.

Autorizzazioni

Di seguito è riportata l'azione controllo degli accessi in base al ruolo necessaria per un utente, un gruppo o un'entità servizio di Microsoft Entra per chiamare l'operazione Query Blob Contents e il ruolo controllo degli accessi in base al ruolo di Azure con privilegi minimi che include questa azione:

Per altre informazioni sull'assegnazione dei ruoli tramite il controllo degli accessi in base al ruolo di Azure, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Commenti

  • L'operazione Query Blob Contents è supportata solo in un BlockBlob tipo.
  • L'esecuzione di query sul contenuto di un BLOB crittografato con chiavi fornite dal cliente non è supportata in questa versione dell'API.
  • Questa operazione non è supportata nei BLOB negli account in cui è abilitata la crittografia dell'infrastruttura .
  • L'intestazione x-ms-version è necessaria per recuperare un Blob che appartiene a un contenitore privato. Se il BLOB appartiene a un contenitore disponibile per l'accesso pubblico completo o parziale, qualsiasi client può leggerlo senza specificare una versione. La versione del servizio non è necessaria per il recupero di un BLOB appartenente a un contenitore pubblico. Per altre informazioni, vedere Limitare l'accesso a contenitori e Blob.
  • È possibile usare l'operazione Query Blob Contents per eseguire query solo sugli oggetti con formato DELIMITATO/CSV o JSON.

Fatturazione

Le richieste di determinazione dei prezzi possono provenire dai client che usano le API di archiviazione BLOB, direttamente tramite l'API REST di Archiviazione BLOB o da una libreria client di Archiviazione di Azure. Queste richieste accumulano addebiti per transazione. Il tipo di transazione influisce sul modo in cui viene addebitato l'account. Ad esempio, le transazioni di lettura si accumulano in una categoria di fatturazione diversa rispetto alle transazioni di scrittura. La tabella seguente illustra la categoria di fatturazione per Query Blob Contents le richieste in base al tipo di account di archiviazione:

Operazione Tipo di account di archiviazione Categoria di fatturazione
Contenuto del BLOB di query BLOB in blocchi Premium
Utilizzo generico v2 Standard		 Operazionidi lettura 1

1Oltre a un addebito di lettura, l'account comporta addebiti per l'accelerazione delle query - Analisi dei dati e accelerazione query - Categorie di transazioni restituite dai dati . I prezzi per queste categorie vengono visualizzati nella pagina Azure Data Lake Storage prezzi.

Vedi anche

Autorizzare le richieste allo stato dell'archiviazione di Azuree ai codici di erroredell'archiviazione BLOB Codici di erroreImpostare i timeout per le operazioni di archiviazione BLOBAccelerazione query: Riferimento al linguaggio SQL