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 Membuat 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. Mengelompokkan 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	Pilihan. Mengelompokkan pengaturan mengenai serialisasi input konten blob. Jika tidak ditentukan, konfigurasi teks yang dibatasi akan digunakan.
Format	diperlukan jika InputSerialization ditentukan. Mengelompokkan pengaturan mengenai format data blob.
Type	diperlukan jika InputSerialization ditentukan. Menunjukkan jenis format. Nilai yang valid adalah delimited, csv, dan json.
DelimitedTextConfiguration	Opsional. Mengelompokkan 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. Mengelompokkan 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. Mengelompokkan 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. Mengelompokkan pengaturan yang digunakan untuk memformat respons jika respons harus diformat dengan teks yang dibatasi.
ColumnSeparator	Opsional. 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. Mengelompokkan pengaturan yang digunakan untuk memformat respons jika respons harus diformat JSON.
RecordSeparator	Pilihan. Menunjukkan string yang digunakan untuk memisahkan rekaman.
ArrowConfiguration	Pilihan. Mengelompokkan pengaturan yang digunakan untuk memformat respons jika respons harus diformat Panah.
Schema	diperlukan jika ArrowConfiguration ditentukan. Mengelompokkan pengaturan mengenai skema respons Arrow yang dikembalikan.
Field	Opsional. Pengaturan grup 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 Status dan kode 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 di mana 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 ada 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 penampingan.
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.

Microsoft Entra ID

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. Prinsip keamanan dapat berupa pengguna, grup, perwakilan layanan aplikasi, atau identitas terkelola Azure. Prinsip 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 bagi pengguna, grup, atau perwakilan layanan Microsoft Entra untuk memanggil Query Blob Contents operasi, dan peran Azure RBAC bawaan 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.

Tanda tangan akses bersama (SAS)

Tanda tangan akses bersama (SAS) menyediakan akses delegasi yang aman ke sumber daya di akun penyimpanan. Dengan SAS, Anda memiliki kontrol terperinci atas bagaimana klien dapat mengakses data. Anda dapat menentukan sumber daya apa yang dapat diakses klien, izin apa yang mereka miliki ke sumber daya tersebut, dan berapa lama SAS valid.

Operasi ini Query Blob Contents mendukung tiga jenis tanda tangan akses bersama: SAS delegasi pengguna, SAS layanan, dan SAS akun.

Sebagai praktik terbaik keamanan, kami sarankan Anda menggunakan kredensial Microsoft Entra daripada kunci akun penyimpanan, yang dapat lebih mudah disusupi. Jika desain aplikasi Anda memerlukan tanda tangan akses bersama, gunakan kredensial Microsoft Entra untuk membuat SAS delegasi pengguna, jika memungkinkan.

Ketika akses Kunci Bersama tidak diizinkan untuk akun penyimpanan, token SAS layanan atau token SAS akun tidak akan diizinkan berdasarkan permintaan ke Blob Storage. Untuk mempelajari lebih lanjut, lihat Memahami bagaimana melarang Kunci Bersama memengaruhi token SAS.

Delegasi pengguna SAS

SAS delegasi pengguna diamankan dengan kredensial Microsoft Entra dan juga oleh izin yang ditentukan untuk SAS.

Memanggil Query Blob Contents operasi menggunakan token SAS yang didelegasikan ke sumber daya kontainer atau blob memerlukan izin Baca (r) sebagai bagian dari token SAS delegasi pengguna.

Untuk mempelajari selengkapnya tentang SAS delegasi pengguna, lihat Membuat SAS delegasi pengguna.

Layanan SAS

Layanan SAS diamankan dengan kunci akun penyimpanan. SAS layanan mendelegasikan akses ke sumber daya dalam satu layanan Azure Storage, seperti penyimpanan blob.

Memanggil Query Blob Contents operasi menggunakan token SAS yang didelegasikan ke kontainer atau sumber daya blob memerlukan izin Baca (r) sebagai bagian dari token SAS layanan.

Untuk mempelajari selengkapnya tentang layanan SAS, lihat Membuat layanan SAS.

Akun SAS

Akun SAS diamankan dengan kunci akun penyimpanan. Akun SAS delegasikan akses ke sumber daya di satu atau beberapa layanan penyimpanan. Semua operasi yang tersedia melalui layanan atau delegasi pengguna SAS juga tersedia melalui akun SAS.

Tabel berikut menunjukkan jenis sumber daya yang ditandatangani dan izin yang ditandatangani untuk menentukan saat mendelegasikan akses:

Operasi	Layanan yang ditandatangani	Jenis sumber daya yang ditandatangani	Izin yang ditandatangani
Konten Blob Kueri	Blob (b)	Objek (o)	Baca (r)

Untuk mempelajari selengkapnya tentang akun SAS, lihat Membuat akun SAS.

Kunci Bersama

Operasi ini Query Blob Contents mendukung otorisasi Kunci Bersama. Otorisasi dengan kunci akun tidak disarankan untuk sebagian besar skenario, karena kurang aman.

Microsoft merekomendasikan untuk melarang otorisasi Kunci Bersama untuk akun penyimpanan jika memungkinkan. Untuk informasi selengkapnya, lihat Mencegah otorisasi dengan Kunci Bersama.

Keterangan

• Query Blob Contents Operasi ini hanya didukung pada BlockBlob 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

¹Selain 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