Daftar Kontainer

  • Artikel

Operasi List Containers mengembalikan daftar kontainer di bawah akun penyimpanan yang ditentukan.

Minta

Anda dapat membuat List Containers permintaan sebagai berikut. HTTPS disarankan. Ganti myaccount dengan nama akun penyimpanan Anda.

Metode Meminta URI Versi HTTP
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

Perhatikan bahwa URI harus selalu menyertakan garis miring (/) untuk memisahkan nama host dari jalur dan bagian kueri URI. Dalam kasus List Containers operasi, bagian jalur URI kosong.

Permintaan layanan penyimpanan yang ditimulasikan

Saat Anda membuat permintaan terhadap layanan penyimpanan yang ditimulasi, tentukan nama host emulator dan port Azure Blob Storage sebagai 127.0.0.1:10000, diikuti dengan nama akun penyimpanan yang ditimulasi.

Metode Meminta URI Versi HTTP
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Perhatikan bahwa penyimpanan yang ditimulasi hanya mendukung ukuran blob hingga 2 GiB.

Untuk informasi selengkapnya, lihat Menggunakan emulator Azurite untuk pengembangan Azure Storage lokal dan Perbedaan antara emulator Penyimpanan dan layanan Azure Storage.

Parameter URI

Anda dapat menentukan parameter tambahan berikut pada URI permintaan.

Parameter Deskripsi
prefix Opsional. Memfilter hasil untuk mengembalikan hanya kontainer dengan nama yang dimulai dengan awalan yang ditentukan.
marker Pilihan. Nilai string yang mengidentifikasi bagian dari daftar kontainer yang akan dikembalikan dengan operasi daftar berikutnya. Operasi mengembalikan NextMarker nilai dalam isi respons, jika operasi daftar tidak mengembalikan semua kontainer yang tersisa untuk dicantumkan dengan halaman saat ini. Anda dapat menggunakan NextMarker nilai sebagai nilai untuk marker parameter dalam panggilan berikutnya untuk meminta halaman item daftar berikutnya.

Nilai penanda buram untuk klien.
maxresults Pilihan. Menentukan jumlah maksimum kontainer yang akan dikembalikan. Jika permintaan tidak menentukan maxresults, atau menentukan nilai yang lebih besar dari 5000, server akan mengembalikan hingga 5000 item.

Perhatikan bahwa jika operasi daftar melewati batas partisi, maka layanan akan mengembalikan token kelanjutan untuk mengambil sisa hasil. Untuk alasan ini, ada kemungkinan bahwa layanan akan mengembalikan lebih sedikit hasil daripada yang ditentukan oleh maxresults, atau daripada default 5000.

Jika parameter diatur ke nilai yang kurang dari atau sama dengan nol, server mengembalikan kode status 400 (Permintaan Buruk).
include={metadata,deleted,system} Pilihan. Menentukan satu atau beberapa himpunan data untuk disertakan dalam respons:

-metadata: Perhatikan bahwa metadata yang diminta dengan parameter ini harus disimpan sesuai dengan pembatasan penamaan yang diberlakukan oleh Blob Storage versi 2009-09-19. Dimulai dengan versi ini, semua nama metadata harus mematuhi konvensi penamaan untuk pengidentifikasi C#.
-deleted: Versi 2019-12-12 dan yang lebih baru. Menentukan bahwa kontainer yang dihapus sementara harus disertakan dalam respons.
-system: Versi 2020-10-02 dan yang lebih baru. Menentukan apakah kontainer sistem akan disertakan dalam respons. Termasuk opsi ini akan mencantumkan kontainer sistem, seperti $logs dan $changefeed. Perhatikan bahwa kontainer sistem tertentu yang dikembalikan akan bervariasi, berdasarkan fitur layanan mana yang diaktifkan pada akun penyimpanan.
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 otorisasi, 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 yang diotorisasi. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage.
x-ms-client-request-id Opsional. 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. Untuk informasi selengkapnya, lihat Memantau Azure Blob Storage.

Isi permintaan

Tidak ada.

Respons

Respons mencakup kode status HTTP, sekumpulan header respons, dan isi respons dalam format XML.

Kode status

Operasi yang berhasil mengembalikan kode status 200 (OK). Untuk informasi tentang kode status, lihat Kode status dan kesalahan.

Header respons

Respons untuk operasi ini mencakup header berikut. Respons juga mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.

Header respons Deskripsi
Content-Type Header HTTP/1.1 standar. Menentukan format di mana hasil dikembalikan. Saat ini, nilai ini adalah application/xml.
x-ms-request-id Header ini secara unik mengidentifikasi permintaan yang dibuat, dan dapat digunakan untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Pemecahan masalah operasi API.
x-ms-version Menunjukkan versi Blob Storage yang digunakan untuk menjalankan permintaan. Header ini dikembalikan untuk permintaan yang dibuat terhadap versi 2009-09-19 dan yang lebih baru.
Date Nilai tanggal/waktu UTC yang menunjukkan waktu di mana respons dimulai. Layanan menghasilkan nilai ini.
x-ms-client-request-id Anda dapat menggunakan header ini untuk memecahkan masalah permintaan dan respons terkait. Nilai header ini sama dengan nilai x-ms-client-request-id header, jika ada dalam permintaan. Nilainya paling banyak 1024 karakter ASCII yang terlihat. x-ms-client-request-id Jika header tidak ada dalam permintaan, header ini tidak akan ada dalam respons.

Isi Respons

Format isi respons adalah sebagai berikut.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

LeaseStatus, LeaseState, dan LeaseDuration hanya muncul di versi 2012-02-12 dan yang lebih baru.

Dimulai dengan versi 2013-08-15, AccountName atribut untuk EnumerationResults elemen telah diganti namanya menjadi ServiceEndpoint. Elemen URL juga telah dihapus dari Container elemen . Untuk versi sebelum 2013-08-15, URL kontainer, seperti yang ditentukan oleh URL bidang , tidak menyertakan restype=container parameter . Jika Anda menggunakan nilai ini untuk membuat permintaan berikutnya terhadap kontainer yang dijumlahkan, pastikan untuk menambahkan parameter ini untuk menunjukkan bahwa jenis sumber daya adalah kontainer.

Elemen Prefix, Marker, dan MaxResults hanya ada jika Anda menentukannya pada URI. Elemen NextMarker memiliki nilai hanya jika hasil daftar tidak selesai.

Elemen Metadata hanya ada jika Anda menentukan include=metadata parameter pada URI. Metadata Dalam elemen , nilai setiap pasangan nama-nilai tercantum dalam elemen yang sesuai dengan nama pasangan.

Jika pasangan nilai nama metadata melanggar pembatasan penamaan yang diberlakukan oleh versi 2009-09-19, isi respons menunjukkan nama yang x-ms-invalid-name bermasalah dalam elemen. Fragmen XML berikut menunjukkan hal ini:

  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>

Dimulai dengan versi 2016-05-31, izin publik kontainer disediakan di PublicAccess properti . Ini menunjukkan apakah data dalam kontainer dapat diakses secara publik, dan tingkat akses. Nilai yang mungkin termasuk:

  • container: Menunjukkan akses baca publik penuh untuk data kontainer dan blob. Klien dapat menghitung blob dalam kontainer melalui permintaan anonim, tetapi tidak dapat menghitung kontainer dalam akun penyimpanan.
  • blob: Menunjukkan akses baca publik untuk blob. Data blob dalam kontainer ini dapat dibaca melalui permintaan anonim, tetapi data kontainer tidak tersedia. Klien tidak dapat menghitung blob dalam kontainer melalui permintaan anonim.

Jika properti ini tidak ditentukan di bagian <properties> , kontainer bersifat privat bagi pemilik akun.

HasImmutabilityPolicy dan HasLegalHold hanya muncul di versi 2017-11-09 dan yang lebih baru. HasImmutabilityPolicy adalah true jika kontainer memiliki kebijakan kekekalan yang ditetapkan di dalamnya, dan false sebaliknya. HasLegalHold adalah true jika kontainer memiliki satu atau beberapa penahanan hukum di atasnya, dan false sebaliknya.

Catatan

Dimulai dengan versi 2009-09-19, isi respons untuk List Containers mengembalikan waktu modifikasi terakhir kontainer, dalam elemen bernama Last-Modified. Dalam versi sebelumnya, elemen ini diberi nama LastModified.

Elemen Version, Deleted, DeletedTime, dan RemainingRetentiondays hanya muncul di versi 2019-12-12 dan yang lebih baru jika Anda menentukan deleted nilai untuk parameter includekueri . Elemen-elemen ini hanya muncul jika kontainer dihapus sementara dan memenuhi syarat untuk dipulihkan. Elemen Version, Deleted, DeletedTime, dan RemainingRetentiondays hanya muncul dalam versi 2019-12-12 dan yang lebih baru jika nilai yang dihapus ditentukan untuk include parameter kueri dan jika kontainer dihapus sementara dan memenuhi syarat untuk dipulihkan.

Authorization

Otorisasi diperlukan saat memanggil operasi akses data apa pun di Azure Storage. Anda dapat mengotorisasi operasi seperti yang List Containers dijelaskan di bawah ini.

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, grup, atau perwakilan layanan yang Microsoft Entra untuk memanggil List Containers operasi, dan peran Azure RBAC bawaan yang paling tidak istimewa yang mencakup tindakan ini:

Untuk mempelajari selengkapnya tentang menetapkan peran menggunakan Azure RBAC, lihat Menetapkan peran Azure untuk akses ke data blob.

Keterangan

Jika Anda menentukan nilai untuk maxresults parameter , dan jumlah kontainer yang akan dikembalikan melebihi nilai ini, atau melebihi nilai default untuk maxresults, isi respons akan berisi NextMarker elemen . (Ini juga disebut sebagai token kelanjutan).

NextMarker menunjukkan kontainer berikutnya untuk kembali pada permintaan berikutnya. Untuk mengembalikan kumpulan item berikutnya, tentukan nilai NextMarker untuk marker parameter pada URI untuk permintaan berikutnya. Perhatikan bahwa nilai NextMarker harus diperlakukan sebagai buram.

Jika operasi daftar melewati batas partisi, maka layanan akan mengembalikan nilai untuk NextMarker elemen untuk mengambil sisa hasil dari partisi berikutnya. Operasi daftar yang mencakup lebih dari satu partisi menghasilkan sekumpulan item yang lebih kecil yang dikembalikan daripada yang ditentukan oleh maxresults, atau daripada default 5000. Aplikasi Anda harus selalu memeriksa keberadaan NextMarker elemen saat Anda melakukan operasi daftar, dan menanganinya dengan sesuai.

Kontainer tercantum dalam urutan alfabet dalam isi respons.

Waktu List Containers operasi habis setelah 30 detik.

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 bagaimana akun ditagih. Misalnya, membaca transaksi bertambah ke kategori penagihan yang berbeda dari transaksi tulis. Tabel berikut ini memperlihatkan kategori penagihan untuk List Containers permintaan berdasarkan jenis akun penyimpanan:

Operasi Jenis akun penyimpanan Kategori penagihan
Daftar Kontainer Objek besar biner blok premium
Tujuan umum standar v2
Tujuan umum standar v1		 Mencantumkan dan Membuat operasi Kontainer

Untuk mempelajari tentang harga untuk kategori penagihan yang ditentukan, lihat harga Azure Blob Storage.

Sampel permintaan dan respons

Contoh URI berikut meminta daftar kontainer untuk akun, mengatur hasil maksimum yang akan dikembalikan untuk operasi awal menjadi tiga.

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1

Permintaan dikirim dengan header ini:

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Kode status dan header respons dikembalikan sebagai berikut:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

XML respons untuk permintaan ini adalah sebagai berikut. Perhatikan bahwa NextMarker elemen mengikuti set kontainer, dan menyertakan nama kontainer berikutnya yang akan dikembalikan.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

Operasi daftar berikutnya menentukan penanda pada URI permintaan, sebagai berikut. Kumpulan hasil berikutnya dikembalikan, dimulai dengan kontainer yang ditentukan oleh penanda.

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video

Lihat juga

Mengotorisasi permintaan ke Azure Storage
Status dan kode galat
Kode kesalahan Blob Storage
Menghitung sumber daya blob
Menggunakan emulator Azure Storage untuk pengembangan dan pengujian
Mengatur batas waktu untuk operasi Blob Storage