Dela via

Frågeblobinnehåll

  • Artikel

Åtgärden Query Blob Contents tillämpar en enkel Structured Query Language -instruktion (SQL) på en blobs innehåll och returnerar endast den efterfrågade delmängden av data. Du kan också anropa Query Blob Contents för att fråga innehållet i en version eller ögonblicksbild.

Förfrågan

Du kan skapa begäran på Query Blob Contents följande sätt. Vi rekommenderar HTTPS. Ersätt myaccount med namnet på ditt lagringskonto.

URI för POST-metodbegäran 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-parametrar

Du kan ange följande ytterligare parametrar på begärande-URI:n:

Parameter Beskrivning
snapshot Valfritt. Parametern snapshot är ett täckande DateTime värde. När den finns anger den blobögonblicksbilden som ska frågas. Mer information om hur du arbetar med blobögonblicksbilder finns i Skapa en ögonblicksbild av en blob.
versionid Valfritt, version 2019-12-12 och senare. Parametern versionid är ett täckande DateTime värde. När den finns anger den version av bloben som ska hämtas.
timeout Valfritt. Parametern timeout uttrycks i sekunder. Mer information finns i Ange tidsgränser för Blob Storage-åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden:

Begärandehuvud Beskrivning
Authorization Krävs. Anger autentiseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
Date eller x-ms-date Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
x-ms-version Krävs för alla autentiserade begäranden, valfritt för anonyma begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
Content-Type Krävs. Värdet för det här huvudet ska vara application/xml; charset=UTF-8.
x-ms-lease-id:<ID> Valfritt. Om det här huvudet anges utförs åtgärden endast om båda följande villkor uppfylls:

– Blobens lån är för närvarande aktivt.
– Låne-ID:t som anges i begäran matchar blobens.

Om det här huvudet anges och båda dessa villkor inte uppfylls misslyckas begäran och Query Blob Contents åtgärden misslyckas med statuskod 412 (Förhandsvillkoret misslyckades).
Origin Valfritt. Anger ursprunget som begäran utfärdas från. Förekomsten av det här huvudet resulterar i CORS-huvuden (Cross-Origin Resource Sharing) i svaret.
x-ms-client-request-id Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggning har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot.

Den här åtgärden stöder också användning av villkorsstyrda rubriker för att fråga blobinnehållet endast om ett angivet villkor uppfylls. Mer information finns i Ange villkorsstyrda rubriker för Blob Storage-åtgärder.

Begärandetext

Begärandetexten för den här versionen av Query Blob Contents använder följande 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>

I följande tabell beskrivs elementen i begärandetexten:

Elementnamn Beskrivning
QueryRequest Krävs. Grupper uppsättningen frågebegäransinställningar.
QueryType Krävs. Anger typen av det angivna frågeuttrycket. Det enda giltiga värdet för den aktuella versionen är SQL.
Expression Krävs. Anger frågeuttrycket i SQL. Den maximala storleken för frågeuttrycket är 256 KiB. Mer information om uttryckssyntaxen finns i Frågeacceleration: SQL-språkreferens.
InputSerialization Valfritt. Grupper inställningarna för indataserialisering av blobinnehållet. Om den inte anges används den avgränsade textkonfigurationen.
Format Krävs om InputSerialization anges. Grupper inställningarna för formatet för blobdata.
Type Krävs om InputSerialization anges. Anger formattypen. Giltiga värden är delimited, csvoch json.
DelimitedTextConfiguration Valfritt. Grupper de inställningar som används för att tolka blobdata om bloben är formaterad med avgränsad text.
ColumnSeparator Valfritt. Anger strängen som används för att avgränsa kolumner.
FieldQuote Valfritt. Anger strängen som används för att citera ett visst fält.
RecordSeparator Valfritt. Anger strängen som används för att avgränsa poster.
EscapeChar Valfritt. Anger strängen som används som escape-tecken.
HasHeaders Valfritt. Anger ett booleskt värde som representerar om data har rubriker.
JsonTextConfiguration Valfritt. Grupper de inställningar som används för att tolka blobdata om bloben är JSON-formaterad.
RecordSeparator Valfritt. Anger strängen som används för att avgränsa poster.
OutputSerialization Valfritt. Anger serialiseringsformatet för det filtrerade innehållet i bloben som returneras i svaret. Om den inte anges används den avgränsade textkonfigurationen.
Format Krävs om OutputSerialization anges. Grupper inställningarna för formatet för det returnerade svaret.
Type Krävs om OutputSerialization anges. Anger formattypen. Giltiga värden är delimited, csv, json och arrow.
DelimitedTextConfiguration Valfritt. Grupper de inställningar som används för att formatera svaret om svaret ska formateras med avgränsad text.
ColumnSeparator Valfritt. Anger strängen som används för att avgränsa kolumner.
FieldQuote Valfritt. Anger strängen som används för att citera ett visst fält.
RecordSeparator Valfritt. Anger strängen som används för att avgränsa poster.
EscapeChar Valfritt. Anger strängen som används som escape-tecken.
HasHeaders Valfritt. Anger ett booleskt värde som representerar om data har rubriker.
JsonTextConfiguration Valfritt. Grupper de inställningar som används för att formatera svaret om svaret ska vara JSON-formaterat.
RecordSeparator Valfritt. Anger strängen som används för att avgränsa poster.
ArrowConfiguration Valfritt. Grupper de inställningar som används för att formatera svaret om svaret ska vara pilformaterat.
Schema Krävs om ArrowConfiguration anges. Grupper inställningarna för schemat för det returnerade pilsvaret.
Field Valfritt. Grupper inställningar för ett visst fält.
Type Krävs om Field anges. Anger fälttypen. Giltiga värden är Int, Float, Decimal och Bool.
Precision Valfritt. Anger precisionen för fältet.
Scale Valfritt. Anger skalan för fältet.

Svarsåtgärder

Svaret innehåller en HTTP-statuskod, en uppsättning svarshuvuden och svarstexten. Svarstexten är i binärt Avro-format. Eftersom svarsinnehållets längd är okänd strömmas svaret med segmenterad kodning.

Statuskod

Om frågebegäran är väl utformad och auktoriserad returnerar åtgärden statuskoden 202 (godkänd). Eventuella fel eller förloppsmeddelanden som påträffas under svarsströmningen returneras som en del av svarstexten.

Information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller följande rubriker. Svaret kan också innehålla ytterligare HTTP-standardhuvuden. Alla standardhuvuden överensstämmer med http/1.1-protokollspecifikationen.

Syntax Description
Last-Modified Anger datum/tid då bloben senast ändrades. Datumformatet följer RFC 1123.

Alla åtgärder som ändrar bloben, inklusive en uppdatering av blobens metadata eller egenskaper, ändrar blobens senast ändrade tid.
Content-Type Anger i vilket format resultaten returneras. För närvarande är avro/binarydet här värdet .
ETag Innehåller ett värde som du kan använda för att utföra åtgärder villkorligt. Mer information finns i Ange villkorsstyrda rubriker för Blob Storage-åtgärder. Om begärandeversionen är 2011-08-18 eller senare ETag är värdet inom citattecken.
Content-Encoding Returnerar värdet som angavs för begärandehuvudet Content-Encoding .
Content-Language Returnerar värdet som angavs för begärandehuvudet Content-Language .
Cache-Control Returnerades om det här huvudet tidigare angavs för bloben.
Content-Disposition Returneras för begäranden mot version 2013-08-15 och senare. Den här rubriken returnerar det värde som angavs för x-ms-blob-content-disposition rubriken.

Fältet Content-Disposition för svarshuvud förmedlar ytterligare information om hur du bearbetar svarsnyttolasten. Du kan också använda fältet för svarshuvud för att bifoga ytterligare metadata. Om till exempel fältet för svarshuvud är inställt attachmentpå ska användaragenten inte visa svaret. I stället bör dialogrutan Spara som visas med ett annat filnamn än det angivna blobnamnet.
x-ms-blob-type: <BlockBlob> Returnerar blobens typ.
x-ms-request-id Identifierar begäran som gjordes unikt. Du kan använda den för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
x-ms-version Anger vilken version av Azure Blob Storage som används för att köra begäran. Ingår för begäranden som görs med version 2009-09-19 och senare.

Det här huvudet returneras också för anonyma begäranden utan en angiven version, om containern har markerats för offentlig åtkomst med hjälp av 2009-09-19-versionen av Blob Storage.
Date Ett datum-/tidsvärde för UTC som anger den tid då tjänsten skickade svaret.
Access-Control-Allow-Origin Returneras om begäran innehåller ett Origin huvud och CORS är aktiverat med en matchande regel. Den här rubriken returnerar värdet för ursprungsbegärandehuvudet vid en matchning.
Access-Control-Expose-Headers Returneras om begäran innehåller ett Origin huvud och CORS är aktiverat med en matchande regel. Det här huvudet returnerar listan med svarshuvuden som ska exponeras för klienten eller utfärdaren av begäran.
Vary Returneras med värdet för Origin rubriken när CORS-regler anges. Mer information finns i CORS-stöd för Azure Storage.
Access-Control-Allow-Credentials Returneras om begäran innehåller ett Origin huvud och CORS är aktiverat med en matchande regel som inte tillåter alla ursprung. Det här huvudet är inställt på true.
x-ms-blob-committed-block-count Anger antalet bekräftade block som finns i bloben. Det här huvudet returneras endast för tilläggsblobar.
x-ms-server-encrypted: true/false Version 2015-12-11 eller senare. Värdet för den här rubriken anges till true om blobdata och programmetadata är helt krypterade via den angivna algoritmen. När bloben är okrypterad, eller om endast delar av blob-/programmetadata krypteras, anges värdet till false.

Själva svaret

Svarstexten innehåller det filtrerade innehållet i bloben som skickas som en serie meddelanden i binärt Avro-format. Den använder följande 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"
      }
    ]
  }
]

Exempelsvar

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

Auktorisering

Auktorisering krävs när du anropar en dataåtkomståtgärd i Azure Storage. Du kan auktorisera åtgärden enligt beskrivningen Query Blob Contents nedan.

Viktigt

Microsoft rekommenderar att du använder Microsoft Entra ID med hanterade identiteter för att auktorisera begäranden till Azure Storage. Microsoft Entra ID ger överlägsen säkerhet och användarvänlighet jämfört med auktorisering med delad nyckel.

Azure Storage stöder användning av Microsoft Entra ID för att auktorisera begäranden till blobdata. Med Microsoft Entra ID kan du använda rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att bevilja behörigheter till ett säkerhetsobjekt. Säkerhetsobjektet kan vara en användare, grupp, programtjänstens huvudnamn eller en hanterad Azure-identitet. Säkerhetsobjektet autentiseras av Microsoft Entra ID för att returnera en OAuth 2.0-token. Token kan sedan användas för att auktorisera en begäran mot Blob-tjänsten.

Mer information om auktorisering med Microsoft Entra ID finns i Auktorisera åtkomst till blobar med hjälp av Microsoft Entra ID.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Microsoft Entra användare, grupp, hanterad identitet eller tjänstens huvudnamn ska anropa Query Blob Contents åtgärden och den minst privilegierade inbyggda Azure RBAC-rollen som innehåller den här åtgärden:

Mer information om hur du tilldelar roller med hjälp av Azure RBAC finns i Tilldela en Azure-roll för åtkomst till blobdata.

Kommentarer

  • Åtgärden Query Blob Contents stöds endast för en BlockBlob typ.
  • Det går inte att köra frågor mot innehållet i en blob som är krypterad med nycklar som tillhandahålls av kunden i den här versionen av API:et.
  • Den här åtgärden stöds inte på blobar i konton som har infrastrukturkryptering aktiverat.
  • Huvudet x-ms-version krävs för att hämta en blob som tillhör en privat container. Om bloben tillhör en container som är tillgänglig för fullständig eller partiell offentlig åtkomst kan alla klienter läsa den utan att ange en version. Tjänstversionen krävs inte för att hämta en blob som tillhör en offentlig container. Mer information finns i Begränsa åtkomsten till containrar och blobar.
  • Du kan använda åtgärden Query Blob Contents för att fråga endast objekt som har avgränsat/CSV- eller JSON-format.

Fakturering

Prisbegäranden kan komma från klienter som använder Blob Storage-API:er, antingen direkt via REST-API:et för Blob Storage eller från ett Azure Storage-klientbibliotek. Dessa begäranden ackumulerar avgifter per transaktion. Typen av transaktion påverkar hur kontot debiteras. Lästransaktioner ackumuleras till exempel till en annan faktureringskategori än skrivtransaktioner. I följande tabell visas faktureringskategorin för Query Blob Contents begäranden baserat på lagringskontotypen:

Åtgärd Typ av lagringskonto Faktureringskategori
Frågeblobinnehåll Premium-blockblob
Standard generell användning v2		 Läsåtgärder1

1Förutom en läskostnad debiteras kontot för frågeacceleration – genomsökt data och frågeacceleration – Data returnerade transaktionskategorier . Priser för dessa kategorier visas på sidan Azure Data Lake Storage prissättning.

Se även

Auktorisera begäranden till AzureStorage-status och felkoderBlob Storage-felkoderAnge tidsgränser för Blob Storage-åtgärderFrågeacceleration: SQL-språkreferens