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 , csv en 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/binary deze 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:
- Azure RBAC-actie:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- Ingebouwde rol met minimale bevoegdheden:Lezer voor opslagblobgegevens
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 eenBlockBlob
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