List Containers

この操作は List Containers 、指定されたストレージ アカウントの下にあるコンテナーの一覧を返します。

Request

要求は List Containers 次のように構築できます。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。

Method 要求 URI HTTP バージョン
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

URI には必ずスラッシュ (/) を含めて、ホスト名を URI のパス部分とクエリ部分から分離する必要があります。 List Containers 操作の場合、URI のパス部分は空です。

エミュレートされたストレージ サービス要求

エミュレートされたストレージ サービスに対して要求を行う場合は、エミュレーターのホスト名と Azure Blob Storage ポートを次のように127.0.0.1:10000指定し、その後にエミュレートされたストレージ アカウント名を指定します。

Method 要求 URI HTTP バージョン
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

エミュレートされたストレージでは、最大 2 GiB の BLOB サイズのみがサポートされることに注意してください。

詳細については、「 Azure Storage のローカル開発に Azurite エミュレーターを使用する 」および 「ストレージ エミュレーターと Azure Storage サービスの違い」を参照してください。

URI パラメーター

要求 URI には、次の追加パラメーターを指定できます。

パラメーター 説明
prefix 省略可能。 結果をフィルター処理して、指定したプレフィックスで始まる名前のコンテナーのみを返します。
marker 省略可能。 次のリスト操作で返されるコンテナーの一覧の一部を識別する文字列値。 リスト操作が現在の NextMarker ページに残っているすべてのコンテナーを返さなかった場合、操作は応答本文内の値を返します。 この値は、後続の NextMarker 呼び出しでパラメーターの marker 値として使用して、リスト アイテムの次のページを要求できます。

マーカー値はクライアントに対して非透過的です。
maxresults 省略可能。 返されるコンテナーの最大数を指定します。 要求で 5000 を超える値が指定 maxresultsされていない場合、サーバーは最大 5,000 個の項目を返します。

リスト操作がパーティション境界を越えた場合、サービスは結果の残りの部分を取得するための継続トークンを返します。 このため、サービスから返される結果は、既定の 5000 で指定された maxresults結果よりも少なくなる可能性があります。

パラメーターが 0 以下の値に設定されている場合、サーバーは状態コード 400 (Bad Request) を返します。
include={metadata,deleted,system} 省略可能。 応答に含める 1 つ以上のデータセットを指定します。

-metadata: このパラメーターで要求されたメタデータは、2009-09-19 バージョンの Blob Storage によって課される名前付け制限に従って格納する必要があることに注意してください。 このバージョン以降、すべてのメタデータ名は C# 識別子の名前付け規則に従う必要があります。
-deleted: バージョン 2019-12-12 以降。 論理的に削除されたコンテナーを応答に含める必要があることを指定します。
-system: バージョン 2020-10-02 以降。 システム コンテナーを応答に含めるかどうかを指定します。 このオプションを含めると、次のような $logs システム コンテナーが $changefeed一覧表示されます。 返される特定のシステム コンテナーは、ストレージ アカウントで有効になっているサービス機能によって異なります。
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 Blob Storage 操作のタイムアウトの設定」を参照してください。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
x-ms-client-request-id 省略可能。 ログ記録の構成時に Azure Monitor ログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成される不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティをサーバーが受け取る要求と関連付けるよう強くお勧めします。 詳細については、「Azure Blob Storageの監視」を参照してください。

要求本文

ありません。

[応答]

応答には HTTP ステータス コード、一連の応答ヘッダー、および応答の本文が XML 形式で含まれます。

状態コード

操作に成功すると、状態コード 200 (OK) が返されます。 状態コードの詳細については、 状態コードとエラー コードに関するページを参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。 応答には、追加の標準 HTTP ヘッダーも含まれます。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています

応答ヘッダー 説明
Content-Type 標準 HTTP/1.1 ヘッダー。 返される結果の形式を指定します。 現在、この値は application/xml.
x-ms-request-id このヘッダーは、行われた要求を一意に識別し、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用される Blob Storage のバージョンを示します。 このヘッダーはバージョン 2009-09-19 以降で行った要求に対して返されます。
Date 応答が開始された時刻を示す UTC 日付/時刻値。 この値はサービスによって生成されます。
x-ms-client-request-id このヘッダーを使用して、要求と対応する応答のトラブルシューティングを行うことができます。 このヘッダーの値は、要求に存在する x-ms-client-request-id 場合、ヘッダーの値と等しくなります。 この値は、最大 1024 個の表示 ASCII 文字です。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。

応答本文

応答本文の形式は次のとおりです。

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

LeaseStatusLeaseState、および LeaseDuration が含まれるのは、バージョン 2012-02-12 以降に限られます。

バージョン 2013-08-15 以降では、AccountName 要素の EnumerationResults 属性の名前が ServiceEndpoint に変更されました。 また、URL 要素が Container 要素から削除されました。 2013-08-15 より前のバージョンの場合、フィールドで URL 指定されたコンテナーの URL にはパラメーターは restype=container 含まれません。 列挙されたコンテナーに対する後続の要求にこの値を使用する場合は、このパラメーターを追加して、リソースの種類がコンテナーであることを指定します。

PrefixMarkerおよびMaxResults要素は、URI で指定した場合にのみ存在します。 リストの NextMarker 結果が完全でない場合にのみ、要素に値が含まれます。

要素は Metadata 、URI でパラメーターを指定した include=metadata 場合にのみ存在します。 Metadata 要素内では、名前と値の各ペアの値が、ペアの名前に対応する要素内に一覧表示されます。

メタデータ名と値のペアが 2009-09-19 バージョンによって適用される名前付け制限に違反している場合、応答本文は要素内の問題のある名前を x-ms-invalid-name 示します。 次の XML フラグメントは、これを示しています。

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

2016-05-31 バージョン以降、コンテナーのパブリック アクセス許可がプロパティに PublicAccess 提供されます。 コンテナー内のデータにパブリックにアクセスできるかどうかを示し、アクセスレベルを示します。 指定できる値は、次のとおりです。

  • container: コンテナーデータと BLOB データの完全なパブリック読み取りアクセスを示します。 クライアントは匿名要求を介してコンテナー内の BLOB を列挙できますが、ストレージ アカウント内のコンテナーを列挙することはできません。
  • blob: BLOB のパブリック読み取りアクセスを示します。 このコンテナー内の BLOB データは匿名要求を介して読み取ることができますが、コンテナー データは使用できません。 クライアントは、匿名要求を介してコンテナー内の BLOB を列挙できません。

このプロパティがセクションで <properties> 指定されていない場合、コンテナーはアカウント所有者に対してプライベートです。

HasImmutabilityPolicy バージョン HasLegalHold 2017-11-09 以降でのみ表示されます。 HasImmutabilityPolicy は、 true コンテナーに不変ポリシーが設定されている場合はそれ以外の false 場合です。 HasLegalHold は、 true コンテナーに 1 つ以上の訴訟ホールドがある false 場合、それ以外の場合です。

注意

バージョン 2009-09-19 以降、応答本文 List Containers はコンテナーの最終変更時刻を、という名前 Last-Modifiedの要素で返します。 以前のバージョンでは、この要素は LastModified という名前でした。

Deleted、、DeletedTimeおよびRemainingRetentiondays要素はVersion、クエリ パラメーターincludeの値を指定deletedした場合、バージョン 2019-12-12 以降でのみ表示されます。 これらの要素は、コンテナーが論理的に削除され、復元できる場合にのみ表示されます。 DeletedTimeDeleted要素、およびRemainingRetentiondays要素はVersion、クエリ パラメーターに削除された値が指定されinclude、コンテナーが論理的に削除され、復元可能な場合にのみ、バージョン 2019-12-12 以降で表示されます。

承認

この操作を呼び出すことができるのは、アカウント所有者だけです。

解説

パラメーターの maxresults 値を指定し、返すコンテナーの数がこの値を超えているか、既定値 maxresultsを超えている場合、応答本文には要素が NextMarker 含まれます。 (これは 継続トークンとも呼ばれます)。

NextMarker は、後続の要求で返される次のコンテナーを示します。 項目の次のセットを返すには、後続の要求の URI のパラメーターのNextMarkermarker値を指定します。 NextMarker の値は非透過的に扱う必要があります。

リスト操作がパーティション境界を越えた場合、サービスは次のパーティションから結果の残りの部分を取得するための要素の値 NextMarker を返します。 複数のパーティションにまたがるリスト操作を実行すると、返される項目のセットが maxresults、既定値の 5000 よりも小さくなります。 アプリケーションでは、リスト操作を実行するときに常に NextMarker 要素の存在を確認し、それに応じて処理する必要があります。

コンテナーは、応答本文でアルファベット順に一覧表示されます。

List Containers 操作は 30 秒後にタイムアウトになります。

要求と応答の例

次のサンプル URI は、アカウントのコンテナーの一覧を要求し、最初の操作で返される最大結果を 3 に設定します。

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

要求は次のヘッダーと共に送信されます。

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

ステータス コードと応答ヘッダーは次のように返されます。

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 は次のとおりです。 要素は NextMarker コンテナーのセットに従い、返される次のコンテナーの名前が含まれます。

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

後続の一覧操作では、次のように要求の URI にマーカーを指定します。 次の結果セットは、マーカーで指定されたコンテナーから始まり、返されます。

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

関連項目

Azure Storage への要求を承認する
状態コードとエラー コード
Blob Storage のエラー コード
BLOB リソースの列挙
開発とテストに Azure Storage エミュレーターを使用する
Blob Storage 操作のタイムアウトの設定