Dotaz na obsah objektu blob

  • Článek

Operace Query Blob Contents použije jednoduchý příkaz jazyk SQL (Structured Query Language) (SQL) na obsah objektu blob a vrátí pouze dotazovanou podmnožinu dat. Můžete také volat Query Blob Contents dotaz na obsah verze nebo snímku.

Žádost

Požadavek můžete sestavit Query Blob Contents následujícím způsobem. Doporučujeme HTTPS. Nahraďte myaccount názvem vašeho účtu úložiště.

Identifikátor URI požadavku metody POST Verze PROTOKOLU 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

Parametry identifikátoru URI

V identifikátoru URI požadavku můžete zadat následující další parametry:

Parametr Popis
snapshot Nepovinný parametr. Parametr snapshot je neprůselná DateTime hodnota. Když je k dispozici, určuje snímek objektu blob, který se má dotazovat. Další informace o práci se snímky objektů blob najdete v tématu Vytvoření snímku objektu blob.
versionid Volitelné, verze 2019-12-12 a novější. Parametr versionid je neprůžná DateTime hodnota. Když je k dispozici, určuje verzi objektu blob, který se má načíst.
timeout Nepovinný parametr. Parametr se timeout vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace služby Blob Storage.

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků:

Hlavička požadavku Popis
Authorization Povinná hodnota. Určuje schéma ověřování, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
Date nebo x-ms-date Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
x-ms-version Povinné pro všechny ověřené požadavky, volitelné pro anonymní požadavky. Určuje verzi operace, která se má pro tento požadavek použít. Další informace najdete v tématu Správa verzí pro služby Azure Storage.
Content-Type Povinná hodnota. Hodnota této hlavičky by měla být application/xml; charset=UTF-8.
x-ms-lease-id:<ID> Nepovinný parametr. Pokud je zadána tato hlavička, bude operace provedena pouze v případě, že jsou splněny obě následující podmínky:

– Zapůjčení objektu blob je aktuálně aktivní.
– ID zapůjčení zadané v požadavku odpovídá ID objektu blob.

Pokud je tato hlavička zadána a nejsou splněny obě tyto podmínky, požadavek selže a Query Blob Contents operace selže se stavovým kódem 412 (Předběžná podmínka selhala).
Origin Nepovinný parametr. Určuje původ, ze kterého je žádost vystavena. Přítomnost této hlavičky má za následek hlavičky SDÍLENÍ prostředků mezi zdroji (CORS) v odpovědi.
x-ms-client-request-id Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu znaků 1 kibibajt (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá.

Tato operace také podporuje použití podmíněných hlaviček k dotazování na obsah objektů blob pouze v případě, že je splněna zadaná podmínka. Další informace najdete v tématu Určení podmíněných hlaviček pro operace služby Blob Storage.

Text požadavku

Text požadavku pro tuto verzi Query Blob Contents používá následující formát 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>

Následující tabulka popisuje prvky textu požadavku:

Název elementu Popis
QueryRequest Povinná hodnota. Seskupí sadu nastavení požadavků dotazu.
QueryType Povinná hodnota. Označuje typ zadaného výrazu dotazu. Jediná platná hodnota pro aktuální verzi je SQL.
Expression Povinná hodnota. Označuje výraz dotazu v SQL. Maximální velikost výrazu dotazu je 256 KiB. Další informace o syntaxi výrazů najdete v tématu Zrychlení dotazů: Referenční informace k jazyku SQL.
InputSerialization Nepovinný parametr. Seskupí nastavení týkající se vstupní serializace obsahu objektu blob. Pokud není zadaný, použije se konfigurace textu s oddělovači.
Format Povinné, pokud InputSerialization je zadána hodnota . Seskupí nastavení týkající se formátu dat objektů blob.
Type Povinné, pokud InputSerialization je zadána hodnota . Označuje typ formátu. Platné hodnoty jsou delimited, csva json.
DelimitedTextConfiguration Nepovinný parametr. Seskupí nastavení, která se použijí k interpretaci dat objektů blob, pokud je objekt blob formátovaný textem s oddělovači.
ColumnSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení sloupců.
FieldQuote Nepovinný parametr. Označuje řetězec, který se používá k uvozovce konkrétního pole.
RecordSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení záznamů.
EscapeChar Nepovinný parametr. Označuje řetězec, který se používá jako řídicí znak.
HasHeaders Nepovinný parametr. Určuje logickou hodnotu, která představuje, jestli data obsahují hlavičky.
JsonTextConfiguration Nepovinný parametr. Seskupí nastavení, která se používají k interpretaci dat objektů blob, pokud je objekt blob ve formátu JSON.
RecordSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení záznamů.
OutputSerialization Nepovinný parametr. Označuje formát serializace filtrovaného obsahu objektu blob vráceného v odpovědi. Pokud není zadaný, použije se konfigurace textu s oddělovači.
Format Povinné, pokud OutputSerialization je zadána hodnota . Seskupí nastavení týkající se formátu vrácené odpovědi.
Type Povinné, pokud OutputSerialization je zadána hodnota . Označuje typ formátu. Platné hodnoty jsou delimited, csv, json nebo arrow.
DelimitedTextConfiguration Nepovinný parametr. Seskupí nastavení, která se použijí k formátování odpovědi, pokud má být odpověď formátována textem s oddělovači.
ColumnSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení sloupců.
FieldQuote Nepovinný parametr. Označuje řetězec, který se používá k uvozovce konkrétního pole.
RecordSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení záznamů.
EscapeChar Nepovinný parametr. Označuje řetězec, který se používá jako řídicí znak.
HasHeaders Nepovinný parametr. Určuje logickou hodnotu, která představuje, jestli data obsahují hlavičky.
JsonTextConfiguration Nepovinný parametr. Pokud má být odpověď ve formátu JSON, seskupí nastavení, která se použijí k formátování odpovědi.
RecordSeparator Nepovinný parametr. Označuje řetězec, který se používá k oddělení záznamů.
ArrowConfiguration Nepovinný parametr. Pokud má být odpověď naformátovaná šipkou, seskupí nastavení, která se použijí k formátování odpovědi.
Schema Povinné, pokud ArrowConfiguration je zadána hodnota . Seskupí nastavení týkající se schématu vrácené odpovědi šipky.
Field Nepovinný parametr. Nastavení skupin týkajících se konkrétního pole
Type Povinné, pokud Field je zadána hodnota . Označuje typ pole. Platné hodnoty jsou Int, Float, Decimal nebo Bool.
Precision Nepovinný parametr. Označuje přesnost pole.
Scale Nepovinný parametr. Označuje měřítko pole.

Odpověď

Odpověď obsahuje stavový kód HTTP, sadu hlaviček odpovědi a tělo odpovědi. Text odpovědi je v binárním formátu Avro. Vzhledem k tomu, že délka obsahu odpovědi je neznámá, odpověď se streamuje s blokovým kódováním.

Stavový kód

Pokud je požadavek dotazu ve správném formátu a autorizován, operace vrátí stavový kód 202 (přijato). Všechny chyby nebo zprávy o průběhu, ke kterým došlo během streamování odpovědí, se vrátí jako součást textu odpovědi.

Informace o stavových kódech najdete v tématu Stavové kódy a kódy chyb.

Hlavičky odpovědi

Odpověď na tuto operaci obsahuje následující hlavičky. Odpověď může také obsahovat další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.

Syntax Description
Last-Modified Označuje datum a čas poslední změny objektu blob. Formát data odpovídá dokumentu RFC 1123.

Každá operace, která změní objekt blob, včetně aktualizace metadat nebo vlastností objektu blob, změní čas poslední změny objektu blob.
Content-Type Určuje formát, ve kterém jsou výsledky vráceny. V současné době je avro/binarytato hodnota .
ETag Obsahuje hodnotu, kterou můžete použít k podmíněnému provádění operací. Další informace najdete v tématu Určení podmíněných hlaviček pro operace služby Blob Storage. Pokud je verze požadavku 2011-08-18 nebo novější, ETag hodnota je v uvozovkách.
Content-Encoding Vrátí hodnotu, která byla zadána pro hlavičku Content-Encoding požadavku.
Content-Language Vrátí hodnotu, která byla zadána pro hlavičku Content-Language požadavku.
Cache-Control Vrátí se, pokud byla pro objekt blob dříve zadána tato hlavička.
Content-Disposition Vráceno pro požadavky na verzi 2013-08-15 a novější. Tato hlavička vrátí hodnotu, která byla zadána pro hlavičku x-ms-blob-content-disposition .

Pole Content-Disposition hlavičky odpovědi sděluje další informace o tom, jak zpracovat datovou část odpovědi. K připojení dalších metadat můžete také použít pole hlavičky odpovědi. Pokud je například pole hlavičky odpovědi nastavené na attachmenthodnotu , uživatelský agent by neměl odpověď zobrazovat. Místo toho by se mělo zobrazit dialogové okno Uložit jako s jiným názvem souboru, než je zadaný název objektu blob.
x-ms-blob-type: <BlockBlob> Vrátí typ objektu blob.
x-ms-request-id Jednoznačně identifikuje požadavek, který byl proveden. Můžete ho použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API.
x-ms-version Označuje verzi Azure Blob Storage, která se používá ke spuštění požadavku. Zahrnuté pro požadavky vytvořené pomocí verze 2009-09-19 a novější.

Tato hlavička se vrátí také pro anonymní požadavky bez zadané verze, pokud byl kontejner označen pro veřejný přístup pomocí verze 2009-09-19 služby Blob Storage.
Date Hodnota data a času UTC, která určuje čas, kdy služba odeslala odpověď.
Access-Control-Allow-Origin Vrátí se, pokud požadavek obsahuje hlavičku Origin a CORS je povolený s odpovídajícím pravidlem. Tato hlavička vrátí hodnotu hlavičky požadavku původu v případě shody.
Access-Control-Expose-Headers Vrátí se, pokud požadavek obsahuje hlavičku Origin a CORS je povolený s odpovídajícím pravidlem. Tato hlavička vrátí seznam hlaviček odpovědi, které budou zpřístupněny klientovi nebo vystaviteli požadavku.
Vary Vrátí se s hodnotou hlavičky Origin při zadání pravidel CORS. Podrobnosti najdete v tématu Podpora CORS pro Azure Storage.
Access-Control-Allow-Credentials Vrátí se, pokud požadavek obsahuje hlavičku Origin a CORS je povolené s odpovídajícím pravidlem, které nepovoluje všechny zdroje. Tato hlavička je nastavená na true.
x-ms-blob-committed-block-count Určuje počet potvrzených bloků v objektu blob. Tato hlavička se vrátí jenom pro doplňovací objekty blob.
x-ms-server-encrypted: true/false Verze 2015-12-11 nebo novější. Hodnota této hlavičky se nastaví na , true pokud jsou data objektů blob a metadata aplikace zcela zašifrovaná prostřednictvím zadaného algoritmu. Pokud je objekt blob nešifrovaný nebo pokud jsou zašifrované jenom části metadat objektu blob nebo aplikace, nastaví se hodnota na false.

Text odpovědi

Tělo odpovědi obsahuje filtrovaný obsah objektu blob odeslaného jako řada zpráv v binárním formátu Avro. Používá následující schéma:

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

Ukázková odpověď

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

Autorizace

Autorizace se vyžaduje při volání jakékoli operace přístupu k datům ve službě Azure Storage. Operaci můžete autorizovat Query Blob Contents , jak je popsáno níže.

Azure Storage podporuje autorizaci požadavků na data objektů blob pomocí Microsoft Entra ID. S Microsoft Entra ID můžete pomocí řízení přístupu na základě role v Azure (Azure RBAC) udělit oprávnění k objektu zabezpečení. Objektem zabezpečení může být uživatel, skupina, instanční objekt aplikace nebo spravovaná identita Azure. Objekt zabezpečení ověří Microsoft Entra ID, aby vrátil token OAuth 2.0. Token se pak dá použít k autorizaci požadavku na službu Blob Service.

Další informace o autorizaci pomocí Microsoft Entra ID najdete v tématu Autorizace přístupu k objektům blob pomocí Microsoft Entra ID.

Oprávnění

Níže jsou uvedené akce RBAC nezbytné k volání Query Blob Contents operace Microsoft Entra uživatele, skupiny nebo instančního objektu a předdefinované role Azure RBAC s nejnižšími oprávněními, která tuto akci zahrnuje:

Další informace o přiřazování rolí pomocí Azure RBAC najdete v tématu Přiřazení role Azure pro přístup k datům objektů blob.

Poznámky

  • Operace Query Blob Contents je podporována pouze u typu BlockBlob .
  • Tato verze rozhraní API nepodporuje dotazování na obsah objektu blob, který je šifrovaný pomocí klíčů poskytnutých zákazníkem.
  • Tato operace se nepodporuje u objektů blob v účtech s povoleným šifrováním infrastruktury .
  • Hlavička x-ms-version se vyžaduje k načtení objektu blob, který patří do privátního kontejneru. Pokud objekt blob patří do kontejneru, který je k dispozici pro úplný nebo částečný veřejný přístup, může ho každý klient číst bez zadání verze. Verze služby se nevyžaduje pro načtení objektu blob, který patří do veřejného kontejneru. Další informace najdete v tématu Omezení přístupu ke kontejnerům a objektům blob.
  • Operaci můžete použít Query Blob Contents k dotazování pouze na objekty, které mají formát s oddělovači/CSV nebo JSON.

Fakturace

Požadavky na ceny můžou pocházet od klientů, kteří používají rozhraní API služby Blob Storage, a to buď přímo prostřednictvím rozhraní REST API služby Blob Storage, nebo z klientské knihovny služby Azure Storage. Za tyto žádosti se účtují poplatky za každou transakci. Typ transakce ovlivňuje způsob účtování za účet. Například transakce čtení se načítají do jiné kategorie fakturace než transakce zápisu. Následující tabulka uvádí kategorii fakturace pro Query Blob Contents žádosti založené na typu účtu úložiště:

Operace Typ účtu úložiště Kategorie fakturace
Dotaz na obsah objektu blob Objekt blob bloku úrovně Premium
Standard pro obecné účely v2		 Operace čtení1

1.Kromě poplatku za čtení se na účtu účtují poplatky za kategorie Akcelerace dotazů – Kontrolovaná data a Akcelerace dotazů – Vrácená data . Ceny pro tyto kategorie se zobrazí na stránce s cenami Azure Data Lake Storage.

Viz také

Autorizace požadavků na stav služby Azure Storagea kódy chybBlob Storage – Kódy chybNastavení časových limitů pro operace služby Blob Storage– Akcelerace dotazů: Referenční informace k jazyku SQL