Kontainer Daftar

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

Minta

Permintaan List Containers dapat dibuat sebagai berikut. HTTPS direkomendasikan. Ganti akun saya dengan nama akun penyimpanan Anda:

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

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

Permintaan Layanan Storage yang Ditiru

Saat mengajukan permintaan terhadap layanan penyimpanan yang ditiru, tentukan nama host emulator dan port layanan Blob sebagai 127.0.0.1:10000, diikuti dengan nama akun penyimpanan yang ditiru:

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

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

Untuk informasi selengkapnya, lihat Menggunakan Emulator Azure Storage untuk Pengembangan dan Pengujian serta Perbedaan Antara Emulator Storage dan Layanan Azure Storage.

Parameter URI

Parameter tambahan berikut dapat ditentukan pada permintaan URI.

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

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

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

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

-metadata: Perhatikan bahwa metadata yang diminta dengan parameter ini harus disimpan sesuai dengan pembatasan penamaan yang diberlakukan oleh layanan Blob 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 atau yang lebih baru. Menentukan apakah kontainer sistem harus 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 Opsional. Parameter timeout dinyatakan dalam hitungan detik. Untuk informasi selengkapnya, lihat Mengatur Batas Waktu untuk Operasi Layanan Blob.

Header permintaan

Tabel berikut menjelaskan header permintaan yang diperlukan dan opsional.

Header Permintaan Deskripsi
Authorization Wajib diisi. Menentukan skema otorisasi, nama akun, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan untuk Azure Storage.
Date atau x-ms-date Wajib diisi. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan untuk Azure Storage.
x-ms-version Diperlukan untuk semua permintaan resmi. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Pembuatan versi untuk Layanan Azure Storage.
x-ms-client-request-id Opsional. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 KiB yang dicatat dalam log analitik saat pencatatan analitik diaktifkan. Menggunakan header ini sangat direkomendasikan untuk mengkorelasi aktivitas sisi klien dengan permintaan yang diterima oleh server. Untuk informasi selengkapnya, lihat Tentang Storage Logging Analytics dan Azure Logging: Menggunakan Log untuk Melacak Permintaan Storage.

Isi Permintaan

Tidak ada.

Jawaban

Respons mencakup kode status HTTP, satu set header respons, dan badan 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 hasilnya 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 layanan Blob yang digunakan untuk menjalankan permintaan. Header ini dikembalikan untuk permintaan yang dibuat terhadap versi 2009-09-19 ke atas.
Date Nilai tanggal/waktu UTC yang dihasilkan oleh layanan yang menunjukkan waktu di mana respons dimulai.
x-ms-client-request-id Header ini dapat digunakan untuk memecahkan masalah permintaan dan tanggapan yang sesuai. Nilai header ini sama dengan nilai x-ms-client-request-id header jika ada dalam permintaan dan nilainya paling banyak 1024 karakter ASCII yang terlihat. x-ms-client-request-id Jika header tidak ada dalam permintaan, header ini tidak akan hadir dalam respons.

Isi Respons

Format badan 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 disebutkan, pastikan untuk menambahkan parameter ini untuk menunjukkan bahwa jenis sumber daya adalah kontainer.

Prefix, Marker, dan MaxResults elemen hanya ada jika ditentukan pada URI. Elemen NextMarker memiliki nilai hanya jika hasil daftar tidak lengkap.

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

Jika pasangan nilai nama metadata melanggar pembatasan penamaan yang diberlakukan oleh versi 2009-09-19, badan respons menunjukkan nama bermasalah dalam suatu elemen, seperti yang x-ms-invalid-name ditunjukkan pada fragmen XML berikut:

  
<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 akan disediakan di properti PublicAccess. Ini menunjukkan apakah data dalam kontainer dapat diakses secara publik dan tingkat akses. Nilai yang mungkin termasuk:

  • kontainer: Menunjukkan akses baca publik penuh untuk data kontainer dan blob. Klien dapat menghitung blob dalam kontainer berdasarkan 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 pribadi bagi pemilik akun.

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

Catatan

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

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

Otorisasi

Hanya pemilik akun yang dapat menghubungi operasi ini.

Keterangan

Jika Anda menentukan nilai untuk maxresults parameter dan jumlah kontainer yang akan dikembalikan melebihi nilai ini, atau melebihi nilai default untuk maxresults, badan respons akan berisi NextMarker elemen (juga disebut sebagai token kelanjutan). NextMarker menunjukkan kontainer berikutnya untuk kembali pada permintaan berikutnya. Untuk mengembalikan kumpulan item berikutnya, tentukan nilai NextMarker parameter marker pada URI untuk permintaan berikutnya. Perhatikan bahwa nilai NextMarker harus diperlakukan sebagai buram.

Jika operasi daftar melintasi 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 satu set item yang lebih kecil yang dikembalikan daripada yang ditentukan oleh maxresults, atau dari default 5000. Aplikasi Anda harus selalu memeriksa keberadaan NextMarker elemen saat Anda melakukan operasi daftar, dan menanganinya sesuai dengan itu.

Kontainer tercantum dalam urutan abjad dalam badan respons.

Waktu List Containers operasi keluar setelah 30 detik.

Contoh Permintaan dan Respons

Contoh URI berikut meminta daftar kontainer untuk akun, menetapkan hasil maksimum untuk kembali untuk operasi awal menjadi 3.

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 permintaan URI, sebagai berikut. Rangkaian hasil berikutnya dikembalikan dimulai dengan kontainer yang ditentukan oleh penanda.

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

Lihat juga

Otorisasi permintaan untuk Azure Storage
Kode Status dan Kesalahan
Kode Kesalahan Layanan Blob
Menghitung Sumber Daya Blob
Menggunakan Emulator Azure Storage untuk Pengembangan dan Pengujian
Mengatur Batas Waktu untuk Operasi Layanan Blob