Kapsayıcıları Listele

  • Makale

İşlem, List Containers belirtilen depolama hesabı altındaki kapsayıcıların listesini döndürür.

İstek

İsteği aşağıdaki gibi oluşturabilirsiniz List Containers . HTTPS önerilir. myaccount değerini depolama hesabınızın adıyla değiştirin.

Yöntem İstek URI'si HTTP sürümü
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

Ana bilgisayar adını URI'nin yolundan ve sorgu bölümlerinden ayırmak için URI'nin her zaman eğik çizgi (/) içermesi gerektiğini unutmayın. İşlem söz konusu olduğunda List Containers , URI'nin yol kısmı boş olur.

Öykünülmüş depolama hizmeti isteği

Öykünülen depolama hizmetine yönelik bir istekte bulunurken öykünücü ana bilgisayar adını ve Azure Blob Depolama bağlantı noktasını olarak 127.0.0.1:10000belirtin ve ardından öykünülen depolama hesabı adını belirtin.

Yöntem İstek URI'si HTTP sürümü
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Öykünülmüş depolamanın yalnızca 2 GiB'ye kadar blob boyutlarını desteklediğini unutmayın.

Daha fazla bilgi için bkz . Yerel Azure Depolama geliştirmesi için Azurite öykünücüsü kullanma ve Depolama öykünücüsü ile Azure Depolama hizmetleri arasındaki farklar.

URI parametreleri

İstek URI'sinde aşağıdaki ek parametreleri belirtebilirsiniz.

Parametre Açıklama
prefix İsteğe bağlı. Sonuçları yalnızca belirtilen ön ekle başlayan bir ada sahip kapsayıcılar döndürecek şekilde filtreler.
marker İsteğe bağlı. Bir sonraki listeleme işlemiyle döndürülecek kapsayıcı listesinin bölümünü tanımlayan dize değeri. Listeleme işlemi geçerli sayfayla birlikte listelenecek kalan tüm kapsayıcıları döndürmediyse, işlem yanıt gövdesindeki değeri döndürür NextMarker . Sonraki liste öğelerinin NextMarker sayfasını istemek için marker sonraki bir çağrıda parametresinin değeri olarak değerini kullanabilirsiniz.

İşaretçi değeri istemci için opaktır.
maxresults İsteğe bağlı. Döndürülecek kapsayıcı sayısı üst sınırını belirtir. İstek belirtmezse maxresultsveya 5000'den büyük bir değer belirtirse, sunucu en fazla 5000 öğe döndürür.

Listeleme işlemi bir bölüm sınırını geçerse, hizmetin sonuçların geri kalanını almak için bir devamlılık belirteci döndüreceğini unutmayın. Bu nedenle, hizmetin tarafından maxresultsbelirtilenden veya varsayılan 5000'den daha az sonuç döndürmesi mümkündür.

Parametre sıfırdan küçük veya sıfıra eşit bir değere ayarlanırsa, sunucu 400 (Hatalı İstek) durum kodunu döndürür.
include={metadata,deleted,system} İsteğe bağlı. Yanıta eklenecek bir veya daha fazla veri kümesini belirtir:

-metadata: Bu parametreyle istenen meta verilerin Blob Depolama'nın 2009-09-19 sürümü tarafından uygulanan adlandırma kısıtlamalarına uygun olarak depolanması gerektiğini unutmayın. Bu sürümden başlayarak, tüm meta veri adları C# tanımlayıcıları için adlandırma kurallarına uymalıdır.
-deleted: Sürüm 2019-12-12 ve üzeri. Geçici olarak silinen kapsayıcıların yanıta eklenmesi gerektiğini belirtir.
-system: Sürüm 2020-10-02 ve üzeri. Sistem kapsayıcılarının yanıta eklenip eklenmediğini belirtir. Bu seçenek dahil olmak üzere ve $changefeedgibi $logs sistem kapsayıcıları listelenir. Döndürülen belirli sistem kapsayıcılarının, depolama hesabında hangi hizmet özelliklerinin etkinleştirildiğine bağlı olarak değişeceğini unutmayın.
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. Yetkilendirme 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 Tüm yetkili istekler için gereklidir. 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.
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. Daha fazla bilgi için bkz. İzleme Azure Blob Depolama.

İstek gövdesi

Yok.

Yanıt

Yanıt bir HTTP durum kodu, yanıt üst bilgileri kümesi ve XML biçiminde bir yanıt gövdesi içerir.

Durum kodu

Başarılı bir işlem 200 (Tamam) durum kodunu döndürü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 ayrıca ek, standart HTTP üst bilgileri içerir. Tüm standart üst bilgiler HTTP/1.1 protokol belirtimine uygundur.

Yanıt üst bilgisi Description
Content-Type Standart HTTP/1.1 üst bilgisi. Sonuçların döndürüldiği biçimi belirtir. Şu anda bu değer şeklindedir application/xml.
x-ms-request-id Bu üst bilgi, yapılan isteği benzersiz olarak tanımlar ve isteğin sorunlarını gidermek için kullanılabilir. Daha fazla bilgi için bkz. API işlemleriyle ilgili sorunları giderme.
x-ms-version İsteği çalıştırmak için kullanılan Blob Depolama sürümünü gösterir. Bu üst bilgi, 2009-09-19 ve sonraki sürümlerde yapılan istekler için döndürülür.
Date Yanıtın başlatıldığı saati gösteren utc tarih/saat değeri. Hizmet bu değeri oluşturur.
x-ms-client-request-id İstekler ve karşılık gelen yanıtlarla ilgili sorunları gidermek için bu üst bilgiyi kullanabilirsiniz. Bu üst bilginin değeri, istekte varsa üst bilginin değerine x-ms-client-request-id eşittir. Değer en fazla 1024 görünür ASCII karakterdir. x-ms-client-request-id Üst bilgi istekte yoksa, yanıtta bu üst bilgi bulunmaz.

Yanıt gövdesi

Yanıt gövdesinin biçimi aşağıdaki gibidir.

<?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, LeaseStateve LeaseDuration yalnızca 2012-02-12 ve sonraki sürümlerde görünür.

Sürüm 2013-08-15'le başlayarak, öğesinin AccountNameEnumerationResults özniteliği olarak yeniden adlandırıldı ServiceEndpoint. URL öğesi de öğesinden Container kaldırıldı. 2013-08-15 öncesi sürümler için kapsayıcının URL'si, alanı tarafından URL belirtildiği gibi parametresini restype=container içermez. Numaralandırılmış kapsayıcılara karşı sonraki istekleri yapmak için bu değeri kullanırsanız, kaynak türünün bir kapsayıcı olduğunu belirtmek için bu parametreyi eklediğinizden emin olun.

Prefix, Markerve MaxResults öğeleri yalnızca URI'de belirttiğinizde bulunur. öğesinin NextMarker bir değeri olması için liste sonuçlarının tamamlanmamış olması gerekir.

Metadata öğesi yalnızca URI'de parametresini include=metadata belirtirseniz bulunur. öğesinde Metadata , her ad-değer çiftinin değeri, çiftin adına karşılık gelen bir öğe içinde listelenir.

Meta veri ad-değer çifti 2009-09-19 sürümü tarafından uygulanan adlandırma kısıtlamalarını ihlal ederse, yanıt gövdesi bir x-ms-invalid-name öğe içindeki sorunlu adı gösterir. Aşağıdaki XML parçası bunu gösterir:

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

2016-05-31 sürümünden başlayarak, kapsayıcı genel izinleri özelliğinde PublicAccess sağlanır. Kapsayıcıdaki verilere genel olarak erişilip erişilemeyeceğini ve erişim düzeyini gösterir. Olası değerler şunlardır:

  • container: Kapsayıcı ve blob verileri için tam ve genel okuma erişimini gösterir. İstemciler anonim istek yoluyla kapsayıcı içindeki blobları numaralandırabilir, ancak depolama hesabındaki kapsayıcıları numaralandıramaz.
  • blob: Bloblar için genel okuma erişimini gösterir. Bu kapsayıcıdaki blob verileri anonim istekle okunabilir ancak kapsayıcı verileri kullanılamaz. İstemciler anonim istek aracılığıyla kapsayıcı içindeki blobları numaralandıramaz.

Bu özellik bölümünde belirtilmezse <properties> , kapsayıcı hesap sahibine özeldir.

HasImmutabilityPolicy ve HasLegalHold yalnızca sürüm 2017-11-09 ve sonraki sürümlerde görünür. HasImmutabilityPolicytrue kapsayıcının üzerinde bir değişmezlik ilkesi ayarlanıp ayarlanmadığını gösterir.false HasLegalHoldtrue kapsayıcının üzerinde bir veya daha fazla yasal ayrım olup olmadığını gösterir.false

Not

2009-09-19 sürümünden başlayarak, için List Containers yanıt gövdesi adlı Last-Modifiedbir öğede kapsayıcının son değiştirme zamanını döndürür. Önceki sürümlerde bu öğe olarak adlandırıldı LastModified.

Version, Deleted, DeletedTimeve RemainingRetentiondays öğeleri yalnızca 2019-12-12 ve sonraki sürümlerinde görüntülenir. Sorgu parametresinin includedeğerini belirtirsenizdeleted. Bu öğeler yalnızca kapsayıcı geçici olarak silindiyse ve geri yüklenmeye uygunsa görünür. Version, Deleted, DeletedTimeve RemainingRetentiondays öğeleri yalnızca sorgu parametresi için include silinen değer belirtilmişse ve kapsayıcı geçici olarak silinmişse ve geri yüklenmeye uygunsa 2019-12-12 ve sonraki sürümlerde görünür.

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 List Containers 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, bir Microsoft Entra kullanıcı, grup veya hizmet sorumlusunun işlemi çağırması List Containers için gereken RBAC eylemi ve bu eylemi içeren en az ayrıcalıklı yerleşik Azure RBAC rolü verilmiştir:

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

parametresi için maxresults bir değer belirtirseniz ve döndürülecek kapsayıcı sayısı bu değeri aşıyorsa veya için maxresultsvarsayılan değeri aşıyorsa, yanıt gövdesi öğesini içerir NextMarker . (Bu, devamlılık belirteci olarak da adlandırılır).

NextMarker sonraki bir istekte döndürülecek bir sonraki kapsayıcıyı gösterir. Sonraki öğe kümesini döndürmek için, sonraki isteğin marker URI'sinde parametresinin değerini NextMarker belirtin. değerinin NextMarker donuk olarak ele alınması gerektiğini unutmayın.

Listeleme işlemi bir bölüm sınırını geçerse, hizmet bir sonraki bölümden sonuçların geri kalanını almak için öğesi için NextMarker bir değer döndürür. Birden fazla bölüme yayılan bir listeleme işlemi, tarafından maxresultsbelirtilenden veya varsayılan değer olan 5000'den daha küçük bir öğe kümesi döndürülür. Bir listeleme işlemi gerçekleştirirken uygulamanız her zaman öğenin varlığını NextMarker denetlemeli ve buna göre işlemelidir.

Kapsayıcılar yanıt gövdesinde alfabetik sırada listelenir.

İşlem List Containers 30 saniye sonra zaman aşımına uğrar.

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 ücretlendirilmeyi etkiler. Ö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 List Containers faturalama kategorisi gösterilmektedir:

İşlem Depolama hesabı türü Faturalama kategorisi
Kapsayıcıları Listele Premium blok blobu
Standart genel amaçlı v2
Standart genel amaçlı v1		 Kapsayıcı işlemlerini listeleme ve oluşturma

Belirtilen faturalama kategorisinin fiyatlandırması hakkında bilgi edinmek için bkz. fiyatlandırma Azure Blob Depolama.

Örnek istek ve yanıt

Aşağıdaki örnek URI bir hesap için kapsayıcı listesini ister ve ilk işlem için döndürülecek en yüksek sonuçları üç olarak ayarlar.

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

İstek şu üst bilgilerle gönderilir:

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

Durum kodu ve yanıt üst bilgileri aşağıdaki gibi döndürülür:

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

Bu isteğin yanıt XML'i aşağıdaki gibidir. öğesinin NextMarker kapsayıcı kümesini izlediğini ve döndürülecek bir sonraki kapsayıcının adını içerdiğini unutmayın.

<?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>

Sonraki liste işlemi, aşağıdaki gibi istek URI'sinde işaretçiyi belirtir. İşaretçi tarafından belirtilen kapsayıcıdan başlayarak sonraki sonuç kümesi döndürülür.

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

Ayrıca bkz.

Azure Depolama'ya yönelik istekleri yetkilendirme
Durum ve hata kodları
Blob Depolama hata kodları
Blob kaynaklarını listeleme
Geliştirme ve test için Azure Depolama öykünücüsü kullanma
Blob Depolama işlemleri için zaman aşımlarını ayarlama