Konten Blob Kueri
Operasi ini Query Blob Contents
menerapkan pernyataan Bahasa Permintaan Terstruktur sederhana (SQL) pada konten blob dan hanya mengembalikan subset data yang dikueri. Anda juga dapat memanggil Query Blob Contents
untuk mengkueri konten versi atau rekam jepret.
Minta
Anda dapat membuat Query Blob Contents
permintaan sebagai berikut. Kami merekomendasikan HTTPS. Ganti myaccount dengan nama akun penyimpanan Anda.
URI permintaan metode POST | Versi HTTP |
---|---|
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 |
Parameter URI
Anda dapat menentukan parameter tambahan berikut pada URI permintaan:
Parameter | Deskripsi |
---|---|
snapshot |
Opsional. Parameter rekam jepret adalah nilai buram DateTime . Saat ada, itu menentukan rekam jepret blob untuk dikueri. Untuk informasi selengkapnya tentang bekerja dengan rekam jepret blob, lihat Create rekam jepret blob. |
versionid |
Opsional, versi 2019-12-12 dan yang lebih baru. Parameter versionid adalah nilai buram DateTime . Ketika ada, itu menentukan versi blob yang akan diambil. |
timeout |
Pilihan. Parameter timeout dinyatakan dalam hitung detik. Untuk informasi selengkapnya, lihat Mengatur batas waktu untuk operasi Blob Storage. |
Header permintaan
Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional:
Meminta kop | Deskripsi |
---|---|
Authorization |
Wajib diisi. Menentukan skema autentikasi, nama akun, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage. |
Date atau x-ms-date |
Wajib diisi. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage. |
x-ms-version |
Diperlukan untuk semua permintaan terautentikasi, opsional untuk permintaan anonim. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage. |
Content-Type |
Wajib diisi. Nilai header ini harus application/xml; charset=UTF-8 . |
x-ms-lease-id:<ID> |
Opsional. Jika header ini ditentukan, operasi akan dilakukan hanya jika kedua kondisi berikut terpenuhi: - Sewa blob saat ini aktif. - ID sewa yang ditentukan dalam permintaan cocok dengan blob. Jika header ini ditentukan dan kedua kondisi ini tidak terpenuhi, permintaan akan gagal dan Query Blob Contents operasi akan gagal dengan kode status 412 (Prasyarat Gagal). |
Origin |
Pilihan. Menentukan asal dari mana permintaan dikeluarkan. Kehadiran header ini menghasilkan header Cross-Origin Resource Sharing (CORS) pada respons. |
x-ms-client-request-id |
Pilihan. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 kibibyte (KiB) yang dicatat dalam log saat pengelogan dikonfigurasi. Kami sangat menyarankan Anda menggunakan header ini untuk menghubungkan aktivitas sisi klien dengan permintaan yang diterima server. |
Operasi ini juga mendukung penggunaan header kondisional untuk mengkueri konten blob hanya jika kondisi tertentu terpenuhi. Untuk informasi selengkapnya, lihat Menentukan header kondisional untuk operasi Blob Storage.
Isi permintaan
Isi permintaan untuk versi Query Blob Contents
ini menggunakan format XML berikut:
<?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>
Tabel berikut ini menjelaskan elemen isi permintaan:
Nama elemen | Deskripsi |
---|---|
QueryRequest |
Wajib diisi. Grup kumpulan pengaturan permintaan kueri. |
QueryType |
Wajib diisi. Menunjukkan jenis ekspresi kueri yang disediakan. Satu-satunya nilai yang valid untuk versi saat ini adalah SQL . |
Expression |
Wajib diisi. Menunjukkan ekspresi kueri di SQL. Ukuran maksimum ekspresi kueri adalah 256 KiB. Untuk informasi selengkapnya tentang sintaks ekspresi, lihat Akselerasi kueri: Referensi bahasa SQL. |
InputSerialization |
Opsional. Grup pengaturan mengenai serialisasi input konten blob. Jika tidak ditentukan, konfigurasi teks yang dibatasi akan digunakan. |
Format |
diperlukan jika InputSerialization ditentukan. Grup pengaturan mengenai format data blob. |
Type |
diperlukan jika InputSerialization ditentukan. Menunjukkan jenis format. Nilai yang valid adalah delimited , csv , dan json . |
DelimitedTextConfiguration |
Pilihan. Grup pengaturan yang digunakan untuk menginterpretasikan data blob jika blob diformat dengan teks yang dibatasi. |
ColumnSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan kolom. |
FieldQuote |
Pilihan. Menunjukkan string yang digunakan untuk mengutip bidang tertentu. |
RecordSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan rekaman. |
EscapeChar |
Pilihan. Menunjukkan string yang digunakan sebagai karakter escape. |
HasHeaders |
Pilihan. Menentukan Boolean yang mewakili apakah data memiliki header. |
JsonTextConfiguration |
Pilihan. Grup pengaturan yang digunakan untuk menginterpretasikan data blob jika blob diformat JSON. |
RecordSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan rekaman. |
OutputSerialization |
Pilihan. Menunjukkan format serialisasi konten blob yang difilter yang dikembalikan dalam respons. Jika tidak ditentukan, konfigurasi teks yang dibatasi akan digunakan. |
Format |
diperlukan jika OutputSerialization ditentukan. Grup pengaturan mengenai format respons yang dikembalikan. |
Type |
diperlukan jika OutputSerialization ditentukan. Menunjukkan jenis format. Nilai yang valid adalah: delimited , csv , json , dan arrow . |
DelimitedTextConfiguration |
Pilihan. Grup pengaturan yang digunakan untuk memformat respons jika respons harus diformat dengan teks yang dibatasi. |
ColumnSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan kolom. |
FieldQuote |
Pilihan. Menunjukkan string yang digunakan untuk mengutip bidang tertentu. |
RecordSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan rekaman. |
EscapeChar |
Pilihan. Menunjukkan string yang digunakan sebagai karakter escape. |
HasHeaders |
Pilihan. Menentukan Boolean yang mewakili apakah data memiliki header. |
JsonTextConfiguration |
Pilihan. Grup pengaturan yang digunakan untuk memformat respons jika respons harus diformat JSON. |
RecordSeparator |
Pilihan. Menunjukkan string yang digunakan untuk memisahkan rekaman. |
ArrowConfiguration |
Pilihan. Grup pengaturan yang digunakan untuk memformat respons jika respons harus diformat Panah. |
Schema |
diperlukan jika ArrowConfiguration ditentukan. Grup pengaturan mengenai skema respons Arrow yang dikembalikan. |
Field |
Opsional. Grup pengaturan mengenai bidang tertentu. |
Type |
diperlukan jika Field ditentukan. Menunjukkan jenis bidang. Nilai yang valid adalah: Int , Float , Decimal , dan Bool . |
Precision |
Pilihan. Menunjukkan presisi bidang. |
Scale |
Pilihan. Menunjukkan skala bidang. |
Respons
Respons mencakup kode status HTTP, sekumpulan header respons, dan isi respons. Isi respons dalam format biner Avro. Karena panjang konten respons tidak diketahui, respons dialirkan dengan pengodean yang dipotong.
Kode status
Jika permintaan kueri dibentuk dengan baik dan diotorisasi, operasi mengembalikan kode status 202 (Diterima). Setiap kesalahan atau pesan kemajuan yang ditemui selama streaming respons akan dikembalikan sebagai bagian dari isi respons.
Untuk informasi tentang kode status, lihat Kode status dan kesalahan.
Header respons
Respons untuk operasi ini mencakup header berikut. Respons mungkin juga menyertakan header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.
Sintaks | Deskripsi |
---|---|
Last-Modified |
Menunjukkan tanggal/waktu blob terakhir diubah. Format tanggal mengikuti RFC 1123. Setiap operasi yang memodifikasi blob, termasuk pembaruan metadata atau properti blob, mengubah waktu blob yang terakhir dimodifikasi. |
Content-Type |
Menentukan format di mana hasil dikembalikan. Saat ini, nilai ini adalah avro/binary . |
ETag |
Berisi nilai yang dapat Anda gunakan untuk melakukan operasi secara kondisional. Untuk informasi selengkapnya, lihat Menentukan header kondisional untuk operasi Blob Storage. Jika versi permintaan adalah 2011-08-18 atau yang lebih baru, ETag nilainya dalam tanda kutip. |
Content-Encoding |
Mengembalikan nilai yang ditentukan untuk Content-Encoding header permintaan. |
Content-Language |
Mengembalikan nilai yang ditentukan untuk Content-Language header permintaan. |
Cache-Control |
Dikembalikan jika header ini sebelumnya ditentukan untuk blob. |
Content-Disposition |
Dikembalikan untuk permintaan terhadap versi 2013-08-15 dan yang lebih baru. Header ini mengembalikan nilai yang ditentukan untuk x-ms-blob-content-disposition header .Bidang Content-Disposition header respons menyampaikan informasi tambahan tentang cara memproses payload respons. Anda juga dapat menggunakan bidang header respons untuk melampirkan metadata tambahan. Misalnya, jika bidang header respons diatur ke attachment , agen pengguna tidak boleh menampilkan respons. Sebaliknya, ini akan menampilkan dialog Simpan Sebagai dengan nama file selain nama blob yang ditentukan. |
x-ms-blob-type: <BlockBlob> |
Mengembalikan jenis blob. |
x-ms-request-id |
Secara unik mengidentifikasi permintaan yang dibuat. Anda dapat menggunakannya untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Memecahkan masalah operasi API. |
x-ms-version |
Menunjukkan versi Azure Blob Storage yang digunakan untuk menjalankan permintaan. Disertakan untuk permintaan yang dibuat menggunakan versi 2009-09-19 dan yang lebih baru. Header ini juga dikembalikan untuk permintaan anonim tanpa versi yang ditentukan, jika kontainer ditandai untuk akses publik menggunakan Blob Storage versi 2009-09-19. |
Date |
Nilai tanggal/waktu UTC yang menunjukkan waktu layanan mengirim respons. |
Access-Control-Allow-Origin |
Dikembalikan jika permintaan menyertakan Origin header dan CORS diaktifkan dengan aturan yang cocok. Header ini mengembalikan nilai header permintaan asal jika terjadi kecocokan. |
Access-Control-Expose-Headers |
Dikembalikan jika permintaan menyertakan Origin header dan CORS diaktifkan dengan aturan yang cocok. Header ini mengembalikan daftar header respons yang akan diekspos ke klien atau penerbit permintaan. |
Vary |
Dikembalikan dengan nilai Origin header saat aturan CORS ditentukan. Untuk detailnya, lihat Dukungan CORS untuk Azure Storage. |
Access-Control-Allow-Credentials |
Dikembalikan jika permintaan menyertakan Origin header dan CORS diaktifkan dengan aturan yang cocok yang tidak mengizinkan semua asal. Header ini diatur ke true . |
x-ms-blob-committed-block-count |
Menunjukkan jumlah blok yang diterapkan yang ada dalam blob. Header ini hanya dikembalikan untuk blob tambahan. |
x-ms-server-encrypted: true/false |
Versi 2015-12-11 atau yang lebih baru. Nilai header ini diatur ke true jika data blob dan metadata aplikasi sepenuhnya dienkripsi melalui algoritma yang ditentukan. Ketika blob tidak terenkripsi, atau jika hanya bagian dari metadata blob/aplikasi yang dienkripsi, nilai diatur ke false . |
Isi Respons
Isi respons berisi konten blob yang difilter yang dikirim sebagai serangkaian pesan dalam format biner Avro. Ini menggunakan skema berikut:
{
"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"
}
]
}
]
Respons sampel
"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":{...}
Authorization
Otorisasi diperlukan saat memanggil operasi akses data apa pun di Azure Storage. Anda dapat mengotorisasi operasi seperti yang Query Blob Contents
dijelaskan di bawah ini.
Penting
Microsoft merekomendasikan penggunaan Microsoft Entra ID dengan identitas terkelola untuk mengotorisasi permintaan ke Azure Storage. Microsoft Entra ID memberikan keamanan yang unggul dan kemudahan penggunaan dibandingkan dengan otorisasi Kunci Bersama.
Azure Storage mendukung penggunaan Microsoft Entra ID untuk mengotorisasi permintaan ke data blob. Dengan Microsoft Entra ID, Anda dapat menggunakan kontrol akses berbasis peran Azure (Azure RBAC) untuk memberikan izin kepada prinsip keamanan. Perwakilan keamanan mungkin pengguna, grup, perwakilan layanan aplikasi, atau identitas terkelola Azure. Perwakilan keamanan diautentikasi oleh Microsoft Entra ID untuk mengembalikan token OAuth 2.0. Token kemudian dapat digunakan untuk mengotorisasi permintaan terhadap Blob service.
Untuk mempelajari selengkapnya tentang otorisasi menggunakan Microsoft Entra ID, lihat Mengotorisasi akses ke blob menggunakan Microsoft Entra ID.
Izin
Tercantum di bawah ini adalah tindakan RBAC yang diperlukan untuk pengguna Microsoft Entra, grup, identitas terkelola, atau perwakilan layanan untuk memanggil Query Blob Contents
operasi, dan peran Azure RBAC bawaan yang paling tidak istimewa yang mencakup tindakan ini:
- Tindakan Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- Peran bawaan yang paling tidak istimewa:Pembaca Data Blob Penyimpanan
Untuk mempelajari selengkapnya tentang menetapkan peran menggunakan Azure RBAC, lihat Menetapkan peran Azure untuk akses ke data blob.
Keterangan
-
Query Blob Contents
Operasi ini hanya didukung padaBlockBlob
jenis . - Mengkueri konten blob yang dienkripsi dengan kunci yang disediakan pelanggan tidak didukung dalam versi API ini.
- Operasi ini tidak didukung pada blob di akun yang mengaktifkan enkripsi infrastruktur .
- Header
x-ms-version
diperlukan untuk mengambil blob milik kontainer privat. Jika blob milik kontainer yang tersedia untuk akses publik penuh atau parsial, klien mana pun dapat membacanya tanpa menentukan versi. Versi layanan tidak diperlukan untuk mengambil blob milik kontainer publik. Untuk informasi selengkapnya, lihat Membatasi akses ke kontainer dan blob. - Anda dapat menggunakan
Query Blob Contents
operasi untuk mengkueri hanya objek yang memiliki format dibatasi/CSV atau JSON.
Billing
Permintaan harga dapat berasal dari klien yang menggunakan API Blob Storage, baik langsung melalui Blob Storage REST API, atau dari pustaka klien Azure Storage. Permintaan ini mengumpulkan biaya per transaksi. Jenis transaksi memengaruhi cara akun ditagih. Misalnya, transaksi baca bertambah ke kategori penagihan yang berbeda dari transaksi tulis. Tabel berikut ini memperlihatkan kategori penagihan untuk Query Blob Contents
permintaan berdasarkan jenis akun penyimpanan:
Operasi | Jenis akun penyimpanan | Kategori penagihan |
---|---|---|
Konten Blob Kueri | Objek besar biner blok premium Tujuan umum standar v2 |
Membaca operasi1 |
1Selain biaya baca, akun dikenakan biaya untuk Akselerasi Kueri - Data yang Dipindai dan Akselerasi Kueri - Kategori transaksi yang Dikembalikan Data . Harga untuk kategori ini muncul di halaman harga Azure Data Lake Storage.
Lihat juga
Otorisasi permintaan ke Status Azure Storagedan kode kesalahanBlob Storage kode kesalahanAtur batas waktu untuk operasi Blob StorageAkselerasi kueri: Referensi bahasa SQL