Freigeben über

Abfragen von Blobinhalten

  • Artikel

Der Query Blob Contents Vorgang wendet eine einfache strukturierte Abfragesprache (SQL)-Anweisung auf den Inhalt eines Blobs an und gibt nur die abgefragte Teilmenge der Daten zurück. Sie können auch aufrufenQuery Blob Contents, um den Inhalt einer Version oder Momentaufnahme abzufragen.

Anforderung

Sie können die Query Blob Contents Anforderung wie folgt erstellen. Wir empfehlen HTTPS. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos.

POST-Methodenanforderungs-URI HTTP-Version
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

URI-Parameter

Sie können im Anforderungs-URI die folgenden zusätzlichen Parameter angeben:

Parameter BESCHREIBUNG
snapshot Optional. Der parameter Momentaufnahme ist ein undurchsichtiger DateTime Wert. Wenn es vorhanden ist, gibt es die zu abfragende Blob-Momentaufnahme an. Weitere Informationen zum Arbeiten mit Blobmomentaufnahmen finden Sie unter Create einer Momentaufnahme eines Blobs.
versionid Optional, Version 2019-12-12 und höher. Der versionid Parameter ist ein undurchsichtiger DateTime Wert. Wenn es vorhanden ist, gibt es die Version des abzurufenden Blobs an.
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob Storage-Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben:

Anforderungsheader BESCHREIBUNG
Authorization Erforderlich. Gibt das Authentifizierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Date oder x-ms-date Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
x-ms-version Für alle authentifizierten Anforderungen erforderlich, für anonyme Anforderungen optional. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
Content-Type Erforderlich. Der Wert dieses Headers sollte sein application/xml; charset=UTF-8.
x-ms-lease-id:<ID> Optional. Bei Angabe dieses Headers wird der Vorgang nur ausgeführt, wenn die beiden folgenden Bedingungen erfüllt sind:

– Die Lease des Blobs ist derzeit aktiv.
– Die in der Anforderung angegebene Lease-ID entspricht der des Blobs.

Wenn der Header angegeben ist und beide Bedingungen nicht erfüllt sind, schlägt die Anforderung fehl, und der Query Blob Contents-Vorgang schlägt mit dem Statuscode 412 (Vorbedingung nicht erfüllt) fehl.
Origin Optional. Gibt die Ursprungsdomäne an, von der die Anforderung ausgegeben wird. Das Vorhandensein dieses Headers führt zu CORS-Headern (Cross-Origin Resource Sharing) für die Antwort.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der beim Konfigurieren der Protokollierung in den Protokollen aufgezeichnet wird. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt.

Dieser Vorgang unterstützt auch die Verwendung bedingter Header zum Abfragen des Blobinhalts nur, wenn eine angegebene Bedingung erfüllt ist. Weitere Informationen finden Sie unter Angeben von bedingten Headern für Blob Storage-Vorgänge.

Anforderungstext

Der Anforderungstext für diese Version von Query Blob Contents verwendet das folgende XML-Format:

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

In der folgenden Tabelle werden die Elemente des Anforderungstexts beschrieben:

Elementname BESCHREIBUNG
QueryRequest Erforderlich. Gruppen den Satz der Abfrageanforderungseinstellungen.
QueryType Erforderlich. Gibt den Typ des bereitgestellten Abfrageausdrucks an. Der einzige gültige Wert für die aktuelle Version ist SQL.
Expression Erforderlich. Gibt den Abfrageausdruck in SQL an. Die maximale Größe des Abfrageausdrucks beträgt 256 KiB. Weitere Informationen zur Ausdruckssyntax finden Sie unter Abfragebeschleunigung: SQL-Sprachreferenz.
InputSerialization Optional. Gruppen die Einstellungen für die Eingabeserialisierung des Blobinhalts. Wenn sie nicht angegeben ist, wird die Textkonfiguration mit Trennzeichen verwendet.
Format Erforderlich, wenn InputSerialization angegeben wird. Gruppen die Einstellungen für das Format der Blobdaten.
Type Erforderlich, wenn InputSerialization angegeben wird. Gibt den Formattyp an. Gültige Werte sind delimited, csv und json.
DelimitedTextConfiguration Optional. Gruppen die Einstellungen, die zum Interpretieren der Blobdaten verwendet werden, wenn das Blob mit durch Trennzeichen formatiert ist.
ColumnSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Spalten verwendet wird.
FieldQuote Optional. Gibt die Zeichenfolge an, die zum Anführungszeichen eines bestimmten Felds verwendet wird.
RecordSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Datensätzen verwendet wird.
EscapeChar Optional. Gibt die Zeichenfolge an, die als Escapezeichen verwendet wird.
HasHeaders Optional. Gibt einen booleschen Wert an, der angibt, ob die Daten über Header verfügen.
JsonTextConfiguration Optional. Gruppen die Einstellungen, die zum Interpretieren der Blobdaten verwendet werden, wenn das Blob JSON-formatiert ist.
RecordSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Datensätzen verwendet wird.
OutputSerialization Optional. Gibt das Serialisierungsformat des gefilterten Inhalts des Blobs an, der in der Antwort zurückgegeben wird. Wenn sie nicht angegeben ist, wird die Textkonfiguration mit Trennzeichen verwendet.
Format Erforderlich, wenn OutputSerialization angegeben wird. Gruppen die Einstellungen für das Format der zurückgegebenen Antwort.
Type Erforderlich, wenn OutputSerialization angegeben wird. Gibt den Formattyp an. Gültige Werte sind delimited, csv, json und arrow.
DelimitedTextConfiguration Optional. Gruppen die Einstellungen, die zum Formatieren der Antwort verwendet werden, wenn die Antwort mit durch Trennzeichen getrennten Text formatiert werden soll.
ColumnSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Spalten verwendet wird.
FieldQuote Optional. Gibt die Zeichenfolge an, die zum Anführungszeichen eines bestimmten Felds verwendet wird.
RecordSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Datensätzen verwendet wird.
EscapeChar Optional. Gibt die Zeichenfolge an, die als Escapezeichen verwendet wird.
HasHeaders Optional. Gibt einen Booleschen Wert an, der angibt, ob die Daten Header aufweisen.
JsonTextConfiguration Optional. Gruppen die Einstellungen, die zum Formatieren der Antwort verwendet werden, wenn die Antwort im JSON-Format formatiert werden soll.
RecordSeparator Optional. Gibt die Zeichenfolge an, die zum Trennen von Datensätzen verwendet wird.
ArrowConfiguration Optional. Gruppen die Einstellungen, die zum Formatieren der Antwort verwendet werden, wenn die Antwort pfeilformatiert sein soll.
Schema Erforderlich, wenn ArrowConfiguration angegeben wird. Gruppen die Einstellungen für das Schema der zurückgegebenen Pfeilantwort.
Field Optional. Gruppen Einstellungen für ein bestimmtes Feld.
Type Erforderlich, wenn Field angegeben wird. Gibt den Feldtyp an. Gültige Werte sind Int, Float, Decimal und Bool.
Precision Optional. Gibt die Genauigkeit des Felds an.
Scale Optional. Gibt die Skalierung des Felds an.

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und den Antworttext. Der Antworttext ist im Avro-Binärformat. Da die Länge des Antwortinhalts unbekannt ist, wird die Antwort mit blockierter Codierung gestreamt.

Statuscode

Wenn die Abfrageanforderung wohlgeformt und autorisiert ist, gibt der Vorgang status Code 202 (Akzeptiert) zurück. Alle Während des Antwortstreamings aufgetretenen Fehler oder Statusmeldungen werden als Teil des Antworttexts zurückgegeben.

Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann auch zusätzliche HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Syntax BESCHREIBUNG
Last-Modified Gibt das Datum/die Uhrzeit der letzten Änderung des Blobs an. Das Datumsformat entspricht RFC 1123.

Durch jeden Vorgang, der das BLOB ändert, einschließlich eines Updates der Metadaten oder Eigenschaften des BLOB, wird die Uhrzeit der letzten Änderung aktualisiert.
Content-Type Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist avro/binarydieser Wert .
ETag Enthält einen Wert, den Sie zum bedingten Ausführen von Vorgängen verwenden können. Weitere Informationen finden Sie unter Angeben von bedingten Headern für Blob Storage-Vorgänge. Wenn die Anforderungsversion 2011-08-18 oder höher ist, befindet sich der Wert in Anführungszeichen ETag .
Content-Encoding Gibt den Wert zurück, der für den Anforderungsheader Content-Encoding angegeben wurde.
Content-Language Gibt den Wert zurück, der für den Anforderungsheader Content-Language angegeben wurde.
Cache-Control Wird zurückgegeben, wenn dieser Header zuvor für das Blob angegeben wurde.
Content-Disposition Wird für Anforderungen an die Version 2013-08-15 und höher zurückgegeben. Dieser Header gibt den Wert zurück, der für den x-ms-blob-content-disposition-Header angegeben wurde.

Das Content-Disposition Antwortheaderfeld enthält zusätzliche Informationen zur Verarbeitung der Antwortnutzlast. Sie können auch das Antwortheaderfeld verwenden, um zusätzliche Metadaten anzufügen. Wenn das Antwortheaderfeld beispielsweise auf attachmentfestgelegt ist, sollte der Benutzer-Agent die Antwort nicht anzeigen. Stattdessen sollte ein Dialogfeld Speichern unter mit einem anderen Dateinamen als dem angegebenen Blobnamen angezeigt werden.
x-ms-blob-type: <BlockBlob> Gibt den Typ des BLOB zurück.
x-ms-request-id Identifiziert die durchgeführte Anforderung eindeutig. Sie können ihn verwenden, um probleme mit der Anforderung zu beheben. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Gibt die Version von Azure Blob Storage an, die zum Ausführen der Anforderung verwendet wird. Enthalten für Anforderungen mit Version 2009-09-19 und höher.

Dieser Header wird auch für anonyme Anforderungen ohne angegebene Version zurückgegeben, wenn der Container mit der Blob Storage-Version 2009-09-19 für öffentlichen Zugriff markiert wurde.
Date Ein UTC-Datums-/Uhrzeitwert, der den Zeitpunkt angibt, zu dem der Dienst die Antwort gesendet hat.
Access-Control-Allow-Origin Wird zurückgegeben, wenn die Anforderung einen Origin-Header enthält und CORS mit einer Abgleichsregel aktiviert ist. Dieser Header gibt den Wert des Origin-Anforderungsheaders im Falle einer Übereinstimmung zurück.
Access-Control-Expose-Headers Wird zurückgegeben, wenn die Anforderung einen Origin-Header enthält und CORS mit einer Abgleichsregel aktiviert ist. Dieser Header gibt die Liste der Antwortheader zurück, die für den Client oder Aussteller der Anforderung verfügbar gemacht werden.
Vary Wird mit dem Wert des Origin-Headers zurückgegeben, wenn CORS-Regeln angegeben werden. Weitere Informationen finden Sie unter CORS-Unterstützung für Azure Storage.
Access-Control-Allow-Credentials Wird zurückgegeben, wenn die Anforderung einen Origin Header enthält und CORS mit einer Abgleichsregel aktiviert ist, die nicht alle Ursprünge zulässt. Dieser Header ist auf truefestgelegt.
x-ms-blob-committed-block-count Gibt die Anzahl der committeten Blöcke an, die im Blob vorhanden sind. Dieser Header wird nur für Anfügeblobs zurückgegeben.
x-ms-server-encrypted: true/false Version 2015-12-11 oder höher. Der Wert dieses Headers wird auf true festgelegt, wenn die Blobdaten und Anwendungsmetadaten vollständig durch den angegebenen Algorithmus verschlüsselt werden. Wenn das Blob unverschlüsselt ist oder nur Teile der Blob-/Anwendungsmetadaten verschlüsselt sind, wird der Wert auf falsefestgelegt.

Antworttext

Der Antworttext enthält den gefilterten Inhalt des Blobs, das als Eine Reihe von Nachrichten im Avro-Binärformat gesendet wird. Es verwendet das folgende Schema:

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

Beispiel für eine Antwort

      "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

Beim Aufrufen eines Datenzugriffsvorgangs in Azure Storage ist eine Autorisierung erforderlich. Sie können den Query Blob Contents Vorgang wie unten beschrieben autorisieren.

Wichtig

Microsoft empfiehlt die Verwendung von Microsoft Entra ID mit verwalteten Identitäten, um Anforderungen an Azure Storage zu autorisieren. Microsoft Entra ID bietet im Vergleich zur Autorisierung mit gemeinsam genutzten Schlüsseln eine höhere Sicherheit und Benutzerfreundlichkeit.

Azure Storage unterstützt die Verwendung von Microsoft Entra ID zum Autorisieren von Anforderungen für Blobdaten. Mit Microsoft Entra ID können Sie die rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) verwenden, um einem Sicherheitsprinzipal Berechtigungen zu erteilen. Der Sicherheitsprinzipal kann ein Benutzer, eine Gruppe, ein Anwendungsdienstprinzipal oder eine verwaltete Azure-Identität sein. Der Sicherheitsprinzipal wird von Microsoft Entra ID authentifiziert, um ein OAuth 2.0-Token zurückzugeben. Das Token kann anschließend zum Autorisieren einer Anforderung an den Blob-Dienst verwendet werden.

Weitere Informationen zur Autorisierung mit Microsoft Entra ID finden Sie unter Autorisieren des Zugriffs auf Blobs mithilfe von Microsoft Entra ID.

Berechtigungen

Nachfolgend sind die RBAC-Aktion aufgeführt, die für einen Microsoft Entra Benutzer, eine Gruppe, eine verwaltete Identität oder einen Dienstprinzipal erforderlich ist, um den Query Blob Contents Vorgang aufzurufen, und die integrierte Azure RBAC-Rolle mit den geringsten Berechtigungen, die diese Aktion enthält:

Weitere Informationen zum Zuweisen von Rollen mithilfe von Azure RBAC finden Sie unter Zuweisen einer Azure-Rolle für den Zugriff auf Blobdaten.

Hinweise

  • Der Query Blob Contents Vorgang wird nur für einen BlockBlob Typ unterstützt.
  • Das Abfragen des Inhalts eines Blobs, das mit vom Kunden bereitgestellten Schlüsseln verschlüsselt ist, wird in dieser Version der API nicht unterstützt.
  • Dieser Vorgang wird für Blobs in Konten, für die die Infrastrukturverschlüsselung aktiviert ist, nicht unterstützt.
  • Der x-ms-version-Header ist erforderlich, um ein BLOB abzurufen, das zu einem privaten Container gehört. Wenn das Blob zu einem Container gehört, der für den vollständigen oder teilweisen öffentlichen Zugriff verfügbar ist, kann jeder Client es lesen, ohne eine Version anzugeben. Die Dienstversion ist nicht erforderlich, um ein Blob abzurufen, das zu einem öffentlichen Container gehört. Weitere Informationen finden Sie unter Beschränken des Zugriffs auf Container und Blobs.
  • Sie können den Query Blob Contents Vorgang verwenden, um nur Objekte abzufragen, die durch Trennzeichen/CSV- oder JSON-Format getrennt sind.

Abrechnung

Preisanforderungen können von Clients stammen, die Blob Storage-APIs verwenden, entweder direkt über die Blob Storage-REST-API oder aus einer Azure Storage-Clientbibliothek. Für diese Anforderungen fallen Gebühren pro Transaktion an. Die Art der Transaktion wirkt sich auf die Abrechnung des Kontos aus. Beispielsweise werden Lesetransaktionen einer anderen Abrechnungskategorie zugeordnet als Schreibtransaktionen. Die folgende Tabelle zeigt die Abrechnungskategorie für Query Blob Contents Anforderungen basierend auf dem Speicherkontotyp:

Vorgang Speicherkontotyp Abrechnungskategorie
Abfragen von Blobinhalten Premium, Blockblob
Standard „Allgemein v2“		 Lesevorgänge1

1Zusätzlich zu einer Lesegebühr fallen für das Konto Gebühren für die Transaktionskategorien Abfragebeschleunigung – Gescannte Daten und Abfragebeschleunigung – Zurückgegebene Daten an. Die Preise für diese Kategorien werden auf der Seite Azure Data Lake Storage Preise angezeigt.

Weitere Informationen

Autorisieren von Anforderungen an Azure StorageStatus und FehlercodesBlob Storage-FehlercodesFestlegen von Timeouts für Blob Storage-VorgängeAbfragebeschleunigung: SQL-Sprachreferenz