List Containers

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

要求

要求は 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 省略可能。 返されるコンテナーの最大数を指定します。 要求で を指定 maxresultsしない場合、または 5000 を超える値を指定した場合、サーバーは最大 5,000 個のアイテムを返します。

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

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

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

要求ヘッダー

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

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

要求本文

[なし] :

Response

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

status code

操作に成功すると、状態コード 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 場合は、ヘッダーの値と同じです。 この値は、表示可能な ASCII 文字が最大 1024 文字です。 ヘッダーが 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 以降でのみ表示されます。 HasImmutabilityPolicytrue 、コンテナーに不変ポリシーが設定されている場合は です false 。それ以外の場合は です。 HasLegalHoldtrue 、コンテナーに 1 つ以上の訴訟ホールドがある場合は であり、 false それ以外の場合は です。

注意

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

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

承認

Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 以下で説明するように、操作を List Containers 承認できます。

Azure Storage では、Microsoft Entra IDを使用して BLOB データへの要求を承認することがサポートされています。 Microsoft Entra IDでは、Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、セキュリティ プリンシパルにアクセス許可を付与できます。 セキュリティ プリンシパルには、ユーザー、グループ、アプリケーション サービス プリンシパル、または Azure マネージド ID を指定できます。 セキュリティ プリンシパルは、OAuth 2.0 トークンを返すためにMicrosoft Entra IDによって認証されます。 その後、そのトークンを、Blob service に対する要求を認可するために使用できます。

Microsoft Entra IDを使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。

アクセス許可

Microsoft Entraユーザー、グループ、またはサービス プリンシパルが操作を呼び出List Containersすために必要な RBAC アクションと、このアクションを含む最小限の特権を持つ組み込み Azure RBAC ロールを次に示します。

Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。

注釈

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

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

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

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

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

請求

価格要求は、Blob Storage REST API を介して直接、または Azure Storage クライアント ライブラリから Blob Storage API を使用するクライアントから送信できます。 これらの要求では、トランザクションあたりの料金が発生します。 トランザクションの種類は、アカウントの課金方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる課金カテゴリに計上されます。 次の表は、ストレージ アカウントの種類に基づく要求の課金カテゴリ List Containers を示しています。

操作 ストレージ アカウントの種類 課金カテゴリ
List Containers Premium ブロック BLOB
Standard 汎用 v2
Standard 汎用 v1
コンテナー操作の一覧表示と作成

指定した課金カテゴリの価格については、「Azure Blob Storage価格」を参照してください。

要求と応答の例

次のサンプル 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 操作のタイムアウトの設定