Delen via


Query's uitvoeren op blobinhoud

De Query Blob Contents bewerking past een eenvoudige sql-instructie (Structured Query Language) toe op de inhoud van een blob en retourneert alleen de opgevraagde subset van de gegevens. U kunt ook aanroepen Query Blob Contents om een query uit te voeren op de inhoud van een versie of momentopname.

Aanvraag

U kunt de Query Blob Contents aanvraag als volgt samenstellen. We raden HTTPS aan. Vervang myaccount door de naam van uw opslagaccount.

AANVRAAG-URI voor POST-methode HTTP-versie
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-parameters

U kunt de volgende aanvullende parameters opgeven voor de aanvraag-URI:

Parameter Beschrijving
snapshot Optioneel. De parameter momentopname is een ondoorzichtige DateTime waarde. Wanneer deze aanwezig is, wordt de momentopname van de blob opgegeven waarop een query moet worden uitgevoerd. Zie een momentopname van een blob Creatie voor meer informatie over het werken met blobmomentopnamen.
versionid Optioneel, versie 2019-12-12 en hoger. De versionid parameter is een ondoorzichtige DateTime waarde. Wanneer deze aanwezig is, wordt de versie van de blob opgegeven die moet worden opgehaald.
timeout Optioneel. De timeout parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven:

Aanvraagheader Beschrijving
Authorization Vereist. Hiermee geeft u het verificatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
Date of x-ms-date Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
x-ms-version Vereist voor alle geverifieerde aanvragen, optioneel voor anonieme aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
Content-Type Vereist. De waarde van deze header moet zijn application/xml; charset=UTF-8.
x-ms-lease-id:<ID> Optioneel. Als deze header is opgegeven, wordt de bewerking alleen uitgevoerd als aan beide van de volgende voorwaarden wordt voldaan:

- De lease van de blob is momenteel actief.
- De lease-id die in de aanvraag is opgegeven, komt overeen met die van de blob.

Als deze header is opgegeven en niet aan beide voorwaarden wordt voldaan, mislukt de aanvraag en mislukt de Query Blob Contents bewerking met statuscode 412 (Voorwaarde mislukt).
Origin Optioneel. Hiermee geeft u de oorsprong van waaruit de aanvraag wordt uitgegeven. De aanwezigheid van deze header resulteert in CORS-headers (Cross-Origin Resource Sharing) in het antwoord.
x-ms-client-request-id Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt.

Deze bewerking ondersteunt ook het gebruik van voorwaardelijke headers om alleen een query uit te voeren op de inhoud van de blob als aan een opgegeven voorwaarde wordt voldaan. Zie Voorwaardelijke headers opgeven voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagbody

De aanvraagbody voor deze versie van Query Blob Contents gebruikt de volgende XML-indeling:

<?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 de volgende tabel worden de elementen van de aanvraagbody beschreven:

Elementnaam Beschrijving
QueryRequest Vereist. Groepen de set instellingen voor queryaanvragen.
QueryType Vereist. Geeft het type van de opgegeven query-expressie aan. De enige geldige waarde voor de huidige versie is SQL.
Expression Vereist. Geeft de queryexpressie in SQL aan. De maximale grootte van de query-expressie is 256 KiB. Zie Queryversnelling: SQL-taalreferentie voor meer informatie over de syntaxis van de expressie.
InputSerialization Optioneel. Groepen de instellingen met betrekking tot de invoerserialisatie van de blobinhoud. Als dit niet is opgegeven, wordt de configuratie van de tekst met scheidingstekens gebruikt.
Format Vereist als InputSerialization is opgegeven. Groepen de instellingen met betrekking tot de indeling van de blobgegevens.
Type Vereist als InputSerialization is opgegeven. Geeft het notatietype aan. Geldige waarden zijn delimited, csven json.
DelimitedTextConfiguration Optioneel. Groepen de instellingen die worden gebruikt voor het interpreteren van de blobgegevens als de blob is opgemaakt met tekst met scheidingstekens.
ColumnSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om kolommen te scheiden.
FieldQuote Optioneel. Geeft de tekenreeks aan die wordt gebruikt om een specifiek veld aan te geven.
RecordSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om records van elkaar te scheiden.
EscapeChar Optioneel. Geeft de tekenreeks aan die wordt gebruikt als een escape-teken.
HasHeaders Optioneel. Hiermee geeft u een Booleaanse waarde op die aangeeft of de gegevens headers hebben.
JsonTextConfiguration Optioneel. Groepen de instellingen die worden gebruikt voor het interpreteren van de blobgegevens als de blob JSON-indeling heeft.
RecordSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om records van elkaar te scheiden.
OutputSerialization Optioneel. Geeft de serialisatie-indeling aan van de gefilterde inhoud van de blob die in het antwoord wordt geretourneerd. Als dit niet is opgegeven, wordt de configuratie van de tekst met scheidingstekens gebruikt.
Format Vereist als OutputSerialization is opgegeven. Groepen de instellingen met betrekking tot de indeling van het geretourneerde antwoord.
Type Vereist als OutputSerialization is opgegeven. Geeft het notatietype aan. Geldige waarden zijn delimited, csv, json en arrow.
DelimitedTextConfiguration Optioneel. Groepen de instellingen die worden gebruikt voor het opmaken van het antwoord als het antwoord moet worden opgemaakt met tekst met scheidingstekens.
ColumnSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om kolommen van elkaar te scheiden.
FieldQuote Optioneel. Geeft de tekenreeks aan die wordt gebruikt om een specifiek veld aan te geven.
RecordSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om records van elkaar te scheiden.
EscapeChar Optioneel. Geeft de tekenreeks aan die wordt gebruikt als escape-teken.
HasHeaders Optioneel. Hiermee geeft u een Booleaanse waarde op die aangeeft of de gegevens headers hebben.
JsonTextConfiguration Optioneel. Groepen de instellingen die worden gebruikt voor het opmaken van het antwoord als het antwoord JSON-indeling moet hebben.
RecordSeparator Optioneel. Geeft de tekenreeks aan die wordt gebruikt om records van elkaar te scheiden.
ArrowConfiguration Optioneel. Groepen de instellingen die worden gebruikt voor het opmaken van het antwoord als het antwoord moet zijn opgemaakt met de pijl.
Schema Vereist als ArrowConfiguration is opgegeven. Groepen de instellingen met betrekking tot het schema van het geretourneerde Pijl-antwoord.
Field Optioneel. Groepen instellingen met betrekking tot een specifiek veld.
Type Vereist als Field is opgegeven. Geeft het veldtype aan. Geldige waarden zijn Int, Float, Decimal en Bool.
Precision Optioneel. Geeft de precisie van het veld aan.
Scale Optioneel. Geeft de schaal van het veld aan.

Antwoord

Het antwoord bevat een HTTP-statuscode, een set antwoordheaders en de hoofdtekst van het antwoord. De hoofdtekst van het antwoord heeft de binaire indeling Avro. Omdat de lengte van de antwoordinhoud onbekend is, wordt het antwoord gestreamd met gesegmenteerde codering.

Statuscode

Als de queryaanvraag goed is opgemaakt en geautoriseerd, retourneert de bewerking statuscode 202 (Geaccepteerd). Eventuele fouten of voortgangsberichten die zijn aangetroffen tijdens het streamen van het antwoord, worden geretourneerd als onderdeel van de hoofdtekst van het antwoord.

Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook extra standaard-HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Syntax Description
Last-Modified Geeft de datum/tijd aan waarop de blob het laatst is gewijzigd. De datumnotatie volgt RFC 1123.

Elke bewerking die de blob wijzigt, inclusief een update van de metagegevens of eigenschappen van de blob, wijzigt de tijd van de laatste wijziging van de blob.
Content-Type Hiermee geeft u de indeling op waarin de resultaten worden geretourneerd. Op dit moment is avro/binarydeze waarde .
ETag Bevat een waarde die u kunt gebruiken om bewerkingen voorwaardelijk uit te voeren. Zie Voorwaardelijke headers opgeven voor Blob Storage-bewerkingen voor meer informatie. Als de aanvraagversie 2011-08-18 of hoger is, staat de ETag waarde tussen aanhalingstekens.
Content-Encoding Retourneert de waarde die is opgegeven voor de Content-Encoding aanvraagheader.
Content-Language Retourneert de waarde die is opgegeven voor de Content-Language aanvraagheader.
Cache-Control Wordt geretourneerd als deze header eerder is opgegeven voor de blob.
Content-Disposition Geretourneerd voor aanvragen op basis van versie 2013-08-15 en hoger. Deze header retourneert de waarde die is opgegeven voor de x-ms-blob-content-disposition header.

Het Content-Disposition veld antwoordheader bevat aanvullende informatie over het verwerken van de nettolading van het antwoord. U kunt ook het veld antwoordheader gebruiken om aanvullende metagegevens toe te voegen. Als het veld antwoordheader bijvoorbeeld is ingesteld op attachment, moet de gebruikersagent het antwoord niet weergeven. In plaats daarvan moet het dialoogvenster Opslaan als worden weergegeven met een andere bestandsnaam dan de opgegeven blobnaam.
x-ms-blob-type: <BlockBlob> Retourneert het type van de blob.
x-ms-request-id Identificeert op unieke wijze de aanvraag die is gedaan. U kunt deze gebruiken om problemen met de aanvraag op te lossen. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
x-ms-version Geeft de versie van Azure Blob Storage aan die wordt gebruikt om de aanvraag uit te voeren. Opgenomen voor aanvragen die zijn gedaan met versie 2009-09-19 en hoger.

Deze header wordt ook geretourneerd voor anonieme aanvragen zonder een versie die is opgegeven, als de container is gemarkeerd voor openbare toegang met behulp van de 2009-09-19-versie van Blob Storage.
Date Een UTC-datum/tijd-waarde die het tijdstip aangeeft waarop de service het antwoord heeft verzonden.
Access-Control-Allow-Origin Wordt geretourneerd als de aanvraag een Origin header bevat en CORS is ingeschakeld met een overeenkomende regel. Deze header retourneert de waarde van de aanvraagheader van de oorsprong in het geval van een overeenkomst.
Access-Control-Expose-Headers Wordt geretourneerd als de aanvraag een Origin header bevat en CORS is ingeschakeld met een overeenkomende regel. Deze header retourneert de lijst met antwoordheaders die worden weergegeven aan de client of verlener van de aanvraag.
Vary Wordt geretourneerd met de waarde van de Origin header wanneer CORS-regels worden opgegeven. Zie CORS-ondersteuning voor Azure Storage voor meer informatie.
Access-Control-Allow-Credentials Wordt geretourneerd als de aanvraag een Origin header bevat en CORS is ingeschakeld met een overeenkomende regel die niet alle origins toestaat. Deze header is ingesteld op true.
x-ms-blob-committed-block-count Geeft het aantal vastgelegde blokken aan dat aanwezig is in de blob. Deze koptekst wordt alleen geretourneerd voor toevoeg-blobs.
x-ms-server-encrypted: true/false Versie 2015-12-11 of hoger. De waarde van deze header wordt ingesteld op true als de blobgegevens en metagegevens van de toepassing volledig zijn versleuteld via het opgegeven algoritme. Wanneer de blob niet is versleuteld of als alleen delen van de metagegevens van de blob/toepassing zijn versleuteld, wordt de waarde ingesteld op false.

Hoofdtekst van de reactie

De antwoordtekst bevat de gefilterde inhoud van de blob die is verzonden als een reeks berichten in binaire Indeling van Avro. Er wordt gebruikgemaakt van het volgende 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"
      }
    ]
  }
]

Voorbeeldantwoord

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

Autorisatie

Autorisatie is vereist bij het aanroepen van een bewerking voor gegevenstoegang in Azure Storage. U kunt de Query Blob Contents bewerking autoriseren zoals hieronder wordt beschreven.

Belangrijk

Microsoft raadt het gebruik van Microsoft Entra ID met beheerde identiteiten aan om aanvragen voor Azure Storage te autoriseren. Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak in vergelijking met autorisatie met gedeelde sleutels.

Azure Storage ondersteunt het gebruik van Microsoft Entra ID om aanvragen voor blobgegevens te autoriseren. Met Microsoft Entra ID kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om machtigingen te verlenen aan een beveiligingsprincipal. De beveiligingsprincipal kan een gebruiker, groep, toepassingsservice-principal of beheerde Azure-identiteit zijn. De beveiligingsprincipal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token te retourneren. Het token kan vervolgens worden gebruikt om een aanvraag voor de Blob-service te autoriseren.

Zie Toegang tot blobs autoriseren met Microsoft Entra ID voor meer informatie over autorisatie met behulp van Microsoft Entra ID.

Machtigingen

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra gebruiker, groep, beheerde identiteit of service-principal om de Query Blob Contents bewerking aan te roepen, en de ingebouwde Azure RBAC-rol met de minste bevoegdheden die deze actie omvat:

Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie over het toewijzen van rollen met behulp van Azure RBAC.

Opmerkingen

  • De Query Blob Contents bewerking wordt alleen ondersteund voor een BlockBlob type.
  • Het uitvoeren van query's op de inhoud van een blob die is versleuteld met door de klant verstrekte sleutels, wordt niet ondersteund in deze versie van de API.
  • Deze bewerking wordt niet ondersteund voor blobs in accounts waarvoor infrastructuurversleuteling is ingeschakeld.
  • De x-ms-version header is vereist om een blob op te halen die deel uitmaakt van een privécontainer. Als de blob deel uitmaakt van een container die beschikbaar is voor volledige of gedeeltelijke openbare toegang, kan elke client deze lezen zonder een versie op te geven. De serviceversie is niet vereist voor het ophalen van een blob die deel uitmaakt van een openbare container. Zie Restrict access to containers and blobs (De toegang tot containers en blobs beperken) voor meer informatie.
  • U kunt de Query Blob Contents bewerking gebruiken om alleen query's uit te voeren op objecten met een scheidingsteken/CSV- of JSON-indeling.

Billing

Prijsaanvragen kunnen afkomstig zijn van clients die gebruikmaken van Blob Storage-API's, rechtstreeks via de Blob Storage REST API of vanuit een Azure Storage-clientbibliotheek. Met deze aanvragen worden kosten per transactie in rekening gebracht. Het type transactie is van invloed op de manier waarop de rekening in rekening wordt gebracht. Leestransacties hebben bijvoorbeeld een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor Query Blob Contents aanvragen op basis van het type opslagaccount:

Bewerking Type opslagaccount Factureringscategorie
Inhoud van queryblob Premium blok-blob
Standaard v2 voor algemeen gebruik
Leesbewerkingen1

1Naast leeskosten worden voor het account kosten in rekening gebracht voor de transactiecategorieën QueryVersnelling - Gegevens gescand en Queryversnelling - Geretourneerde gegevens . Prijzen voor deze categorieën worden weergegeven op de pagina met Azure Data Lake Storage prijzen.

Zie ook

Aanvragen autoriseren voor Azure Storage-statusen foutcodesBlob Storage-foutcodesTime-outs instellen voor Blob Storage-bewerkingenQueryversnelling: SQL-taalverwijzing