Sorgu Blobu İçeriği
İşlem, Query Blob Contents blobun içeriğine basit bir Yapılandırılmış Sorgu Dili (SQL) deyimi uygular ve verilerin yalnızca sorgulanan alt kümesini döndürür. Bir sürümün veya anlık görüntünün içeriğini sorgulamak için de çağrısı Query Blob Contents yapabilirsiniz.
İstek
İsteği aşağıdaki gibi oluşturabilirsiniz Query Blob Contents . HTTPS kullanmanızı öneririz. myaccount değerini depolama hesabınızın adıyla değiştirin.
| POST yöntemi istek URI'si | HTTP sürümü |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=queryhttps://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 parametreleri
İstek URI'sinde aşağıdaki ek parametreleri belirtebilirsiniz:
| Parametre | Açıklama |
|---|---|
snapshot |
İsteğe bağlı. Snapshot parametresi opak DateTime bir değerdir. Mevcut olduğunda sorguya eklenecek blob anlık görüntüsünü belirtir. Blob anlık görüntüleriyle çalışma hakkında daha fazla bilgi için bkz. Blobun anlık görüntüsünü oluşturma. |
versionid |
İsteğe bağlı, sürüm 2019-12-12 ve üzeri. versionid parametresi opak DateTime bir değerdir. Mevcut olduğunda, alınacak blobun sürümünü belirtir. |
timeout |
İsteğe bağlı. timeout parametresi saniye cinsinden ifade edilir. Daha fazla bilgi için bkz. Blob Depolama işlemleri için zaman aşımlarını ayarlama. |
İstek üst bilgileri
Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır:
| İstek üst bilgisi | Açıklama |
|---|---|
Authorization |
Gereklidir. Kimlik doğrulama düzenini, hesap adını ve imzayı belirtir. Daha fazla bilgi için bkz. Azure Depolama isteklerini yetkilendirme. |
Date veya x-ms-date |
Gereklidir. İstek için Eşgüdümlü Evrensel Saat (UTC) biçimini belirtir. Daha fazla bilgi için bkz. Azure Depolama isteklerini yetkilendirme. |
x-ms-version |
Kimliği doğrulanmış tüm istekler için gereklidir ve anonim istekler için isteğe bağlıdır. Bu istek için kullanılacak işlemin sürümünü belirtir. Daha fazla bilgi için bkz. Azure Depolama hizmetleri için sürüm oluşturma. |
Content-Type |
Gereklidir. Bu üst bilginin değeri olmalıdır application/xml; charset=UTF-8. |
x-ms-lease-id:<ID> |
İsteğe bağlı. Bu üst bilgi belirtilirse, işlem yalnızca aşağıdaki koşulların her ikisi de karşılandığında gerçekleştirilir: - Blob'un kirası şu anda etkin. - İstekte belirtilen kira kimliği blobunkiyle eşleşir. Bu üst bilgi belirtilirse ve bu koşulların her ikisi de karşılanmazsa istek başarısız olur ve Query Blob Contents işlem 412 durum koduyla başarısız olur (Önkoşul Başarısız oldu). |
Origin |
İsteğe bağlı. İsteğin verildiği kaynağı belirtir. Bu üst bilginin varlığı, yanıtta Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) üst bilgileriyle sonuçlanır. |
x-ms-client-request-id |
İsteğe bağlı. Günlüğe kaydetme yapılandırıldığında günlüklere kaydedilen 1 kibibaytlık (KiB) karakter sınırıyla istemci tarafından oluşturulan, opak bir değer sağlar. İstemci tarafı etkinlikleriyle sunucunun aldığı istekler arasında bağıntı sağlamak için bu üst bilgiyi kullanmanızı kesinlikle öneririz. |
Bu işlem, yalnızca belirtilen bir koşul karşılandığında blob içeriğini sorgulamak için koşullu üst bilgilerin kullanımını da destekler. Daha fazla bilgi için bkz. Blob Depolama işlemleri için koşullu üst bilgileri belirtme.
İstek gövdesi
bu sürümü Query Blob Contents için istek gövdesi aşağıdaki XML biçimini kullanır:
<?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>
Aşağıdaki tabloda istek gövdesinin öğeleri açıklanmaktadır:
| Öğe adı | Açıklama |
|---|---|
QueryRequest |
Gereklidir. Sorgu isteği ayarları kümesini gruplandırın. |
QueryType |
Gereklidir. Sağlanan sorgu ifadesinin türünü gösterir. Geçerli sürüm için tek geçerli değer: SQL. |
Expression |
Gereklidir. SQL'de sorgu ifadesini gösterir. Sorgu ifadesinin boyut üst sınırı 256 KiB'dir. İfade söz dizimi hakkında daha fazla bilgi için bkz . Sorgu hızlandırma: SQL dil başvurusu. |
InputSerialization |
İsteğe bağlı. Blob içeriğinin giriş serileştirmesi ile ilgili ayarları gruplandırır. Belirtilmezse, sınırlandırılmış metin yapılandırması kullanılır. |
Format |
Belirtilirse InputSerialization gereklidir. Blob verilerinin biçimiyle ilgili ayarları gruplandırın. |
Type |
Belirtilirse InputSerialization gereklidir. Biçim türünü gösterir. Geçerli değerler , csvve jsondeğerleridirdelimited. |
DelimitedTextConfiguration |
İsteğe bağlı. Blob sınırlandırılmış metinle biçimlendirildiyse blob verilerini yorumlamak için kullanılan ayarları gruplandırır. |
ColumnSeparator |
İsteğe bağlı. Sütunları ayırmak için kullanılan dizeyi gösterir. |
FieldQuote |
İsteğe bağlı. Belirli bir alandan alıntı yapmak için kullanılan dizeyi gösterir. |
RecordSeparator |
İsteğe bağlı. Kayıtları ayırmak için kullanılan dizeyi gösterir. |
EscapeChar |
İsteğe bağlı. Kaçış karakteri olarak kullanılan dizeyi gösterir. |
HasHeaders |
İsteğe bağlı. Verilerin üst bilgileri olup olmadığını gösteren bir Boole değeri belirtir. |
JsonTextConfiguration |
İsteğe bağlı. Blob JSON biçimlendirilmişse blob verilerini yorumlamak için kullanılan ayarları gruplandırır. |
RecordSeparator |
İsteğe bağlı. Kayıtları ayırmak için kullanılan dizeyi gösterir. |
OutputSerialization |
İsteğe bağlı. Yanıtta döndürülen blobun filtrelenmiş içeriğinin seri hale getirme biçimini gösterir. Belirtilmezse, sınırlandırılmış metin yapılandırması kullanılır. |
Format |
Belirtilirse OutputSerialization gereklidir. Döndürülen yanıtın biçimiyle ilgili ayarları gruplandırın. |
Type |
Belirtilirse OutputSerialization gereklidir. Biçim türünü gösterir. Geçerli değerler delimited, csv, json veya arrow değerleridir. |
DelimitedTextConfiguration |
İsteğe bağlı. Yanıtın sınırlandırılmış metinle biçimlendirilmesi gerekiyorsa, yanıtı biçimlendirmek için kullanılan ayarları gruplandırır. |
ColumnSeparator |
İsteğe bağlı. Sütunları ayırmak için kullanılan dizeyi gösterir. |
FieldQuote |
İsteğe bağlı. Belirli bir alandan alıntı yapmak için kullanılan dizeyi gösterir. |
RecordSeparator |
İsteğe bağlı. Kayıtları ayırmak için kullanılan dizeyi gösterir. |
EscapeChar |
İsteğe bağlı. Kaçış karakteri olarak kullanılan dizeyi gösterir. |
HasHeaders |
İsteğe bağlı. Verilerin üst bilgileri olup olmadığını gösteren bir Boole değeri belirtir. |
JsonTextConfiguration |
İsteğe bağlı. Yanıtın JSON biçiminde olması gerekiyorsa, yanıtı biçimlendirmek için kullanılan ayarları gruplandırır. |
RecordSeparator |
İsteğe bağlı. Kayıtları ayırmak için kullanılan dizeyi gösterir. |
ArrowConfiguration |
İsteğe bağlı. Yanıtın Ok biçiminde olması gerekiyorsa, yanıtı biçimlendirmek için kullanılan ayarları gruplandırır. |
Schema |
Belirtilirse ArrowConfiguration gereklidir. Döndürülen Ok yanıtının şemasıyla ilgili ayarları gruplandırın. |
Field |
İsteğe bağlı. Belirli bir alanla ilgili ayarları gruplar. |
Type |
Belirtilirse Field gereklidir. Alan türünü gösterir. Geçerli değerler Int, Float, Decimal veya Bool değerleridir. |
Precision |
İsteğe bağlı. Alanın duyarlığı gösterir. |
Scale |
İsteğe bağlı. Alanın ölçeğini gösterir. |
Yanıt
Yanıt bir HTTP durum kodu, bir dizi yanıt üst bilgisi ve yanıt gövdesi içerir. Yanıt gövdesi Avro ikili biçimindedir. Yanıt içeriği uzunluğu bilinmediğinden, yanıt öbekli kodlama ile akışa aktarılır.
Durum kodu
Sorgu isteği iyi biçimlendirilmiş ve yetkilendirilmişse, işlem 202 (Kabul Edildi) durum kodunu döndürür. Yanıt akışı sırasında karşılaşılan hatalar veya ilerleme iletileri yanıt gövdesinin bir parçası olarak döndürülür.
Durum kodları hakkında bilgi için bkz. Durum ve hata kodları.
Yanıt üst bilgileri
Bu işlemin yanıtı aşağıdaki üst bilgileri içerir. Yanıt ek standart HTTP üst bilgileri de içerebilir. Tüm standart üst bilgiler HTTP/1.1 protokol belirtimine uygundur.
| Syntax | Description |
|---|---|
Last-Modified |
Blob'un son değiştirildiği tarihi/saati gösterir. Tarih biçimi RFC 1123'e göredir. Blobun meta verilerinin veya özelliklerinin güncelleştirilmiş olması da dahil olmak üzere blobu değiştiren tüm işlemler, blobun son değiştirme zamanını değiştirir. |
Content-Type |
Sonuçların döndürüldiği biçimi belirtir. Şu anda bu değer şeklindedir avro/binary. |
ETag |
İşlemleri koşullu olarak gerçekleştirmek için kullanabileceğiniz bir değer içerir. Daha fazla bilgi için bkz. Blob Depolama işlemleri için koşullu üst bilgileri belirtme. İstek sürümü 2011-08-18 veya üzeriyse, ETag değer tırnak içindedir. |
Content-Encoding |
İstek üst bilgisi için Content-Encoding belirtilen değeri döndürür. |
Content-Language |
İstek üst bilgisi için Content-Language belirtilen değeri döndürür. |
Cache-Control |
Bu üst bilgi daha önce blob için belirtilmişse döndürülür. |
Content-Disposition |
Sürüm 2013-08-15 ve sonraki sürümlere yönelik istekler için döndürüldü. Bu üst bilgi, üst bilgi için x-ms-blob-content-disposition belirtilen değeri döndürür.Yanıt Content-Disposition üst bilgisi alanı, yanıt yükünün nasıl işlendiği hakkında ek bilgi aktarır. Ek meta veriler eklemek için yanıt üst bilgisi alanını da kullanabilirsiniz. Örneğin, yanıt üst bilgisi alanı olarak attachmentayarlanırsa, kullanıcı aracısı yanıtı görüntülememelidir. Bunun yerine, belirtilen blob adı dışında bir dosya adına sahip farklı kaydet iletişim kutusu göstermelidir. |
x-ms-blob-type: <BlockBlob> |
Blob'un türünü döndürür. |
x-ms-request-id |
Yapılan isteği benzersiz olarak tanımlar. İstekle ilgili sorunları gidermek için bunu kullanabilirsiniz. Daha fazla bilgi için bkz . API işlemleriyle ilgili sorunları giderme. |
x-ms-version |
İsteği yürütmek için kullanılan Azure Blob Depolama sürümünü gösterir. Sürüm 2009-09-19 ve üzeri kullanılarak yapılan isteklere dahildir. Kapsayıcı Blob Depolama'nın 2009-09-19 sürümü kullanılarak genel erişim için işaretlenmişse, bu üst bilgi, belirtilen bir sürüm olmadan anonim istekler için de döndürülür. |
Date |
Hizmetin yanıtı gönderdiği saati gösteren UTC tarih/saat değeri. |
Access-Control-Allow-Origin |
İstek bir Origin üst bilgi içeriyorsa ve CORS eşleşen bir kuralla etkinleştirildiyse döndürülür. Bu üst bilgi, eşleşme olması durumunda kaynak istek üst bilgisinin değerini döndürür. |
Access-Control-Expose-Headers |
İstek bir Origin üst bilgi içeriyorsa ve CORS eşleşen bir kuralla etkinleştirildiyse döndürülür. Bu üst bilgi, isteğin istemcisine veya verene sunulacak yanıt üst bilgilerinin listesini döndürür. |
Vary |
CORS kuralları belirtildiğinde Origin üst bilgi değeriyle döndürülür. Ayrıntılar için bkz. Azure Depolama için CORS desteği. |
Access-Control-Allow-Credentials |
İstek bir Origin üst bilgi içeriyorsa ve CORS tüm çıkış noktalarına izin vermeyecek bir eşleştirme kuralıyla etkinleştirildiyse döndürülür. Bu üst bilgi olarak trueayarlanır. |
x-ms-blob-committed-block-count |
Blobda bulunan kaydedilmiş blok sayısını gösterir. Bu üst bilgi yalnızca ekleme blobları için döndürülür. |
x-ms-server-encrypted: true/false |
Sürüm 2015-12-11 veya üzeri. Blob verileri ve uygulama meta verileri belirtilen algoritma aracılığıyla tamamen şifrelenirse, bu üst bilginin değeri olarak ayarlanır true . Blob şifrelenmemişse veya blob/uygulama meta verilerinin yalnızca bazı bölümleri şifrelendiğinde, değer olarak falseayarlanır. |
Yanıt gövdesi
Yanıt gövdesi, Avro ikili biçiminde bir dizi ileti olarak gönderilen blobun filtrelenmiş içeriğini içerir. Aşağıdaki şemayı kullanır:
{
"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"
}
]
}
]
Örnek yanıt
"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":{...}
Yetkilendirme
Azure Depolama'da herhangi bir veri erişim işlemi çağrılırken yetkilendirme gereklidir. İşlemi aşağıda açıklandığı gibi yetki Query Blob Contents verebilirsiniz.
Azure Depolama, blob verilerine yönelik istekleri yetkilendirmek için Microsoft Entra ID kullanılmasını destekler. Microsoft Entra ID ile Azure rol tabanlı erişim denetimini (Azure RBAC) kullanarak bir güvenlik sorumlusuna izin vekleyebilirsiniz. Güvenlik sorumlusu bir kullanıcı, grup, uygulama hizmet sorumlusu veya Azure yönetilen kimliği olabilir. OAuth 2.0 belirtecini döndürmek için güvenlik sorumlusunun kimliği Microsoft Entra ID tarafından doğrulanır. Belirteç daha sonra Blob hizmetine karşı bir isteği yetkilendirmek için kullanılabilir.
Microsoft Entra ID kullanarak yetkilendirme hakkında daha fazla bilgi edinmek için bkz. Microsoft Entra ID kullanarak bloblara erişimi yetkilendirme.
İzinler
Aşağıda, Microsoft Entra kullanıcı, grup veya hizmet sorumlusunun işlemi çağırması Query Blob Contents için gereken RBAC eylemi ve bu eylemi içeren en az ayrıcalıklı yerleşik Azure RBAC rolü verilmiştir:
- Azure RBAC eylemi:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- En az ayrıcalıklı yerleşik rol:Depolama Blob Veri Okuyucusu
Azure RBAC kullanarak rol atama hakkında daha fazla bilgi edinmek için bkz. Blob verilerine erişim için Azure rolü atama.
Açıklamalar
- İşlem
Query Blob Contentsyalnızca birBlockBlobtür üzerinde desteklenir. - Müşteri tarafından sağlanan anahtarlarla şifrelenmiş bir blobun içeriğinin sorgulanması API'nin bu sürümünde desteklenmez.
- Bu işlem, altyapı şifrelemesi etkinleştirilmiş hesaplardaki bloblarda desteklenmez.
- Üst
x-ms-versionbilgi, özel bir kapsayıcıya ait bir blobu almak için gereklidir. Blob tam veya kısmi genel erişim için kullanılabilen bir kapsayıcıya aitse, herhangi bir istemci sürümü belirtmeden bu kapsayıcıyı okuyabilir. Hizmet sürümü, genel kapsayıcıya ait bir blobu almak için gerekli değildir. Daha fazla bilgi için bkz. Kapsayıcılara ve blob'lara erişimi kısıtlama. - yalnızca sınırlandırılmış/CSV veya JSON biçimine sahip nesneleri sorgulamak için işlemini kullanabilirsiniz
Query Blob Contents.
Faturalama
Fiyatlandırma istekleri, Blob Depolama API'lerini kullanan istemcilerden, doğrudan Blob Depolama REST API'si aracılığıyla veya bir Azure Depolama istemci kitaplığından kaynaklanabilir. Bu istekler işlem başına ücret tahakkuk eder. İşlem türü, hesabın nasıl ücretlendirildiğinden etkilenir. Örneğin, okuma işlemleri yazma işlemlerinden farklı bir faturalama kategorisine tahakkuk eder. Aşağıdaki tabloda, depolama hesabı türüne göre istekler için Query Blob Contents faturalama kategorisi gösterilmektedir:
| İşlem | Depolama hesabı türü | Faturalama kategorisi |
|---|---|---|
| Sorgu Blobu İçeriği | Premium blok blobu Standart genel amaçlı v2 |
Okuma işlemleri1 |
1Okuma ücretine ek olarak, hesap Sorgu Hızlandırma - Taranan Veriler ve Sorgu Hızlandırma - Döndürülen Veriler işlem kategorileri için ücretlendirilir. Bu kategorilerin fiyatlandırması Azure Data Lake Storage fiyatlandırma sayfasında görünür.
Ayrıca bkz.
Azure DepolamaDurumu isteklerini yetkilendirme ve hata kodlarıBlob Depolama hata kodları Blob Depolamaişlemleri için zaman aşımlarını ayarlamaSorgu hızlandırma: SQL dil başvurusu