Lekérdezési blob tartalma

A Query Blob Contents művelet egy egyszerű Structured Query Language (SQL) utasítást alkalmaz egy blob tartalmára, és csak az adatok lekérdezett részhalmazát adja vissza. A hívással Query Blob Contents lekérdezheti egy verzió vagy pillanatkép tartalmát is.

Kérés

A kérést az Query Blob Contents alábbiak szerint hozhatja létre. A HTTPS használatát javasoljuk. Cserélje le a myaccount kifejezést a tárfiók nevére.

POST metódus kérésének URI-ja HTTP-verzió
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-paraméterek

A kérelem URI-ján a következő további paramétereket adhatja meg:

Paraméter Leírás
snapshot Választható. A pillanatkép paraméter egy átlátszatlan DateTime érték. Ha jelen van, meghatározza a lekérdezendő blobpillanatképet. A blobpillanatképek használatával kapcsolatos további információkért lásd: Blob pillanatképének létrehozása.
versionid Nem kötelező, 2019-12-12-es és újabb verzió. A versionid paraméter egy átlátszatlan DateTime érték. Ha jelen van, meghatározza a lekérni kívánt blob verzióját.
timeout Választható. A timeout paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása Blob Storage-műveletekhez.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti:

Kérelem fejléce Leírás
Authorization Kötelező. Megadja a hitelesítési sémát, a fióknevet és az aláírást. További információ: Kérelmek engedélyezése az Azure Storage-ba.
Date vagy x-ms-date Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérelmek engedélyezése az Azure Storage-ba.
x-ms-version Az összes hitelesített kéréshez kötelező, a névtelen kérésekhez nem kötelező. A kérelemhez használandó művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
Content-Type Kötelező. A fejléc értékének a következőnek kell lennie application/xml; charset=UTF-8: .
x-ms-lease-id:<ID> Választható. Ha ez a fejléc van megadva, a művelet csak akkor lesz végrehajtva, ha az alábbi feltételek mindegyike teljesül:

– A blob bérlete jelenleg aktív.
– A kérelemben megadott bérletazonosító megegyezik a blob bérletazonosítójával.

Ha ez a fejléc meg van adva, és mindkét feltétel nem teljesül, a kérés sikertelen lesz, és a művelet a Query Blob Contents 412-s állapotkóddal meghiúsul (az előfeltétel sikertelen).
Origin Választható. Meghatározza, hogy a kérelem melyik forrásból legyen kibocsátva. Ennek a fejlécnek a jelenléte az eltérő eredetű erőforrás-megosztási (CORS) fejléceket eredményez a válaszban.
x-ms-client-request-id Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kibibyte (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel.

Ez a művelet feltételes fejlécek használatát is támogatja a blob tartalmának lekérdezéséhez, ha egy adott feltétel teljesül. További információ: Feltételes fejlécek megadása Blob Storage-műveletekhez.

A kérés törzse

A kérelem törzse ehhez a Query Blob Contents verzióhoz a következő XML-formátumot használja:

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

Az alábbi táblázat a kérelem törzsének elemeit ismerteti:

Elem neve Leírás
QueryRequest Kötelező. A lekérdezési kérelem beállításainak csoportosítása.
QueryType Kötelező. A megadott lekérdezési kifejezés típusát jelzi. Az aktuális verzió egyetlen érvényes értéke a következő SQL: .
Expression Kötelező. A lekérdezési kifejezést jelzi az SQL-ben. A lekérdezési kifejezés maximális mérete 256 KiB. A kifejezésszintaxissal kapcsolatos további információkért lásd : Lekérdezésgyorsítás: SQL nyelvi referencia.
InputSerialization Választható. Csoportosítja a blob tartalmának bemeneti szerializálására vonatkozó beállításokat. Ha nincs megadva, a rendszer a tagolt szövegkonfigurációt használja.
Format InputSerialization Ha meg van adva, kötelező megadni. A blobadatok formátumára vonatkozó beállítások csoportosítása.
Type InputSerialization Ha meg van adva, kötelező megadni. A formátum típusát jelzi. Az érvényes értékek a következők: delimited, csvés json.
DelimitedTextConfiguration Választható. Csoportosítja a blobadatok értelmezéséhez használt beállításokat, ha a blob tagolt szöveggel van formázva.
ColumnSeparator Választható. Az oszlopok elválasztásához használt sztringet jelöli.
FieldQuote Választható. Egy adott mező idézéséhez használt sztringet jelöli.
RecordSeparator Választható. A rekordok elválasztásához használt sztringet jelöli.
EscapeChar Választható. A feloldó karakterként használt sztringet jelöli.
HasHeaders Választható. Egy logikai értéket ad meg, amely azt jelzi, hogy az adatok tartalmaznak-e fejléceket.
JsonTextConfiguration Választható. Csoportosítja a blobadatok értelmezéséhez használt beállításokat, ha a blob JSON formátumú.
RecordSeparator Választható. A rekordok elválasztásához használt sztringet jelöli.
OutputSerialization Választható. A válaszban visszaadott blob szűrt tartalmának szerializálási formátumát jelzi. Ha nincs megadva, a rendszer a tagolt szövegkonfigurációt használja.
Format OutputSerialization Ha meg van adva, kötelező megadni. Csoportosítja a visszaadott válasz formátumára vonatkozó beállításokat.
Type OutputSerialization Ha meg van adva, kötelező megadni. A formátum típusát jelzi. Az érvényes értékek a következők: delimited, csv, json és arrow.
DelimitedTextConfiguration Választható. Csoportosítja a válasz formázásához használt beállításokat, ha a választ tagolt szöveggel kell formázni.
ColumnSeparator Választható. Az oszlopok elválasztásához használt sztringet jelöli.
FieldQuote Választható. Egy adott mező idézéséhez használt sztringet jelöli.
RecordSeparator Választható. A rekordok elválasztásához használt sztringet jelöli.
EscapeChar Választható. A feloldó karakterként használt sztringet jelöli.
HasHeaders Választható. Egy logikai értéket ad meg, amely azt jelzi, hogy az adatok tartalmaznak-e fejléceket.
JsonTextConfiguration Választható. Csoportosítja a válasz formázásához használt beállításokat, ha a válasznak JSON formátumúnak kell lennie.
RecordSeparator Választható. A rekordok elválasztásához használt sztringet jelöli.
ArrowConfiguration Választható. Csoportosítja a válasz formázásához használt beállításokat, ha a válasznak nyílformátumúnak kell lennie.
Schema ArrowConfiguration Ha meg van adva, kötelező megadni. A visszaadott nyílválasz sémájára vonatkozó beállítások csoportosítása.
Field Választható. Adott mezőre vonatkozó beállítások csoportosítása.
Type Field Ha meg van adva, kötelező megadni. A mező típusát jelzi. Az érvényes értékek a következők: Int, Float, Decimal és Bool.
Precision Választható. A mező pontosságát jelzi.
Scale Választható. A mező skáláját jelzi.

Reagálás

A válasz tartalmazza a HTTP-állapotkódot, a válaszfejlécek készletét és a válasz törzsét. A válasz törzse Avro bináris formátumban van. Mivel a válasz tartalmának hossza ismeretlen, a rendszer adattömbön átkódolt kódolással streameli a választ.

Állapotkód

Ha a lekérdezési kérelem megfelelően formázott és engedélyezett, a művelet a 202-s állapotkódot adja vissza (elfogadva). A válaszstreamelés során észlelt hibák vagy állapotüzenetek a válasz törzsének részeként lesznek visszaadva.

Az állapotkódokkal kapcsolatos információkért lásd: Állapot- és hibakódok.

Válaszfejlécek

A műveletre adott válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Syntax Description
Last-Modified A blob utolsó módosításának dátumát/időpontját jelzi. A dátumformátum az RFC 1123-at követi.

Minden olyan művelet, amely módosítja a blobot, beleértve a blob metaadatainak vagy tulajdonságainak frissítését, megváltoztatja a blob utolsó módosítási időpontját.
Content-Type Megadja az eredmények visszaadott formátumát. Ez az érték jelenleg a .avro/binary
ETag Olyan értéket tartalmaz, amellyel feltételesen hajthat végre műveleteket. További információ: Feltételes fejlécek megadása Blob Storage-műveletekhez. Ha a kérelem verziója 2011-08-18 vagy újabb, az ETag érték idézőjelek között van.
Content-Encoding A kérelemfejléchez Content-Encoding megadott értéket adja vissza.
Content-Language A kérelemfejléchez Content-Language megadott értéket adja vissza.
Cache-Control Akkor adja vissza, ha ez a fejléc korábban meg lett adva a blobhoz.
Content-Disposition A 2013-08-15-ös és újabb verzióval kapcsolatos kérések visszaadva. Ez a fejléc a fejléchez x-ms-blob-content-disposition megadott értéket adja vissza.

A Content-Disposition válaszfejléc mező további információkat tartalmaz a válasz hasznos adatainak feldolgozásáról. A válaszfejlécmezővel további metaadatokat is csatolhat. Ha például a válasz fejlécmezője értékre attachmentvan állítva, a felhasználói ügynök nem jelenítheti meg a választ. Ehelyett egy Mentés másként párbeszédpanelnek kell megjelennie a megadott blobnéven kívül más fájlnévvel.
x-ms-blob-type: <BlockBlob> A blob típusát adja vissza.
x-ms-request-id Egyedileg azonosítja a végrehajtott kérést. Segítségével elháríthatja a kérést. További információ: API-műveletek hibaelhárítása.
x-ms-version A kérés végrehajtásához használt Azure Blob Storage verzióját jelzi. A 2009-09-19-es és újabb verzióval küldött kérésekhez tartozik.

Ez a fejléc a megadott verzió nélküli névtelen kérések esetén is megjelenik, ha a tároló nyilvános hozzáférésre lett megjelölve a Blob Storage 2009-09-19-es verziójával.
Date UTC dátum/idő érték, amely azt az időpontot jelzi, amikor a szolgáltatás elküldte a választ.
Access-Control-Allow-Origin Akkor adja vissza, ha a kérelem tartalmaz fejlécet Origin , és a CORS engedélyezve van egy megfelelő szabmánnyal. Ez a fejléc a forráskérés fejlécének értékét adja vissza egyezés esetén.
Access-Control-Expose-Headers Akkor adja vissza, ha a kérelem tartalmaz fejlécet Origin , és a CORS engedélyezve van egy megfelelő szabmánnyal. Ez a fejléc azoknak a válaszfejléceknek a listáját adja vissza, amelyek a kérés ügyfélének vagy kiállítójának lesznek elérhetővé téve.
Vary A cors-szabályok megadásakor a Origin fejléc értékével adja vissza. Részletekért lásd: CORS-támogatás az Azure Storage-hoz.
Access-Control-Allow-Credentials Akkor adja vissza, ha a kérelem tartalmaz egy fejlécet Origin , és a CORS engedélyezve van egy olyan egyező szabánnyal, amely nem engedélyezi az összes forrást. Ez a fejléc a következőre van állítva: true.
x-ms-blob-committed-block-count A blobban található véglegesített blokkok számát jelzi. Ez a fejléc csak hozzáfűző blobokhoz lesz visszaadva.
x-ms-server-encrypted: true/false 2015-12-11-es vagy újabb verzió. Ennek a fejlécnek az értéke akkor van beállítva true , ha a blobadatok és az alkalmazás metaadatai teljes mértékben titkosítva vannak a megadott algoritmussal. Ha a blob titkosítatlan, vagy ha csak a blob/alkalmazás metaadatainak csak részei vannak titkosítva, az érték értékre falsevan állítva.

Választörzs

A válasz törzse a blob szűrt tartalmát tartalmazza, amely Avro bináris formátumban küldött üzenetek sorozataként van elküldve. A következő sémát használja:

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

Mintaválasz

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

Engedélyezés

Az azure storage-beli adathozzáférési műveletek meghívásakor engedélyezés szükséges. A műveletet az Query Blob Contents alábbiak szerint engedélyezheti.

Az Azure Storage támogatja a Microsoft Entra ID használatát a blobadatokra irányuló kérések engedélyezéséhez. A Microsoft Entra ID azure-beli szerepköralapú hozzáférés-vezérléssel (Azure RBAC) adhat engedélyeket egy rendszerbiztonsági tagnak. A rendszerbiztonsági tag lehet felhasználó, csoport, alkalmazás-szolgáltatásnév vagy Azure-beli felügyelt identitás. A rendszerbiztonsági tag hitelesítését a Microsoft Entra ID végzi egy OAuth 2.0-jogkivonat visszaadásához. A jogkivonat ezután a Blob szolgáltatásra irányuló kérések engedélyezésére használható.

További információ a Microsoft Entra ID használatával történő engedélyezésről: Blobokhoz való hozzáférés engedélyezése Microsoft Entra ID használatával.

Engedélyek

Az alábbiakban azokat az RBAC-műveletet soroljuk fel, amelyek szükségesek ahhoz, hogy egy Microsoft Entra felhasználó, csoport vagy szolgáltatásnév meghívja a Query Blob Contents műveletet, valamint a legkevésbé kiemelt beépített Azure RBAC-szerepkört, amely tartalmazza ezt a műveletet:

A szerepkörök Azure RBAC-vel való hozzárendeléséről további információt az Azure-szerepkör hozzárendelése a blobadatokhoz való hozzáféréshez című témakörben talál.

Megjegyzések

  • A Query Blob Contents művelet csak típus BlockBlob esetén támogatott.
  • Az API jelen verziójában nem támogatott az ügyfél által megadott kulcsokkal titkosított blob tartalmának lekérdezése.
  • Ez a művelet nem támogatott olyan blobokon, amelyeken engedélyezve van az infrastruktúra-titkosítás .
  • A x-ms-version fejléc egy privát tárolóhoz tartozó blob lekéréséhez szükséges. Ha a blob egy olyan tárolóhoz tartozik, amely teljes vagy részleges nyilvános hozzáféréshez érhető el, bármely ügyfél elolvashatja a verzió megadása nélkül. A szolgáltatás verziója nem szükséges egy nyilvános tárolóhoz tartozó blob lekéréséhez. További információkért lásd: Restrict access to containers and blobs (A tárolókhoz és blobokhoz való hozzáférés korlátozása).
  • A Query Blob Contents művelettel csak a tagolt/CSV- vagy JSON-formátumú objektumokat kérdezheti le.

Számlázás

A díjszabási kérések a Blob Storage API-kat használó ügyfelektől, közvetlenül a Blob Storage REST API-ból vagy egy Azure Storage-ügyfélkódtárból származhatnak. Ezek a kérések tranzakciónkénti díjakat halmoznak fel. A tranzakció típusa befolyásolja a fiók terhelését. Az olvasási tranzakciók például más számlázási kategóriába tartoznak, mint az írási tranzakciók. Az alábbi táblázat a tárfiók típusa alapján a kérelmek számlázási kategóriáját Query Blob Contents mutatja be:

Művelet Tárfiók típusa Számlázási kategória
Blobtartalom lekérdezése Prémium szintű blokkblob
Standard általános célú v2
Olvasási műveletek1

1Az olvasási díj mellett a fiók díjat is felszámít a Lekérdezésgyorsítás – Beolvasott adatok és lekérdezésgyorsítás – Visszaadott adatok tranzakciókategóriáiért. Ezeknek a kategóriáknak a díjszabása a Azure Data Lake Storage díjszabási oldalon jelenik meg.

Lásd még

Kérések engedélyezése az Azure Storage állapotáhozés hibakódjaihozBlob Storage-hibakódokIdőtúllépések beállítása Blob Storage-műveletekhezLekérdezésgyorsítás: SQL nyelvi referencia