セールス: 1-800-867-1380

List Blobs

更新日: 2014年2月

List Blobs 操作は、指定されたコンテナーにある BLOB の一覧を列挙します。

List Blobs 要求の構成は次のとおりです。HTTPS が推奨されます。myaccount はストレージ アカウントの名前に置き換えます。

 

メソッド 要求 URI HTTP バージョン

GET

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list

HTTP/1.1

エミューレートされたストレージ サービスに対する要求では、エミュレーターのホスト名と BLOB サービス ポートを 127.0.0.1:10000 と指定し、その後にエミューレートされたストレージ アカウント名を指定します。

 

メソッド 要求 URI HTTP バージョン

GET

http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list

HTTP/1.1

詳細については、「開発とテストのための Azure のストレージ エミュレーター使用」を参照してください。

次の追加パラメーターを URI で指定できます。

 

Parameter 説明

prefix

省略可能。結果をフィルター処理し、名前が指定されたプレフィックスで始まる BLOB のみを返します。

delimiter

省略可能。要求にこのパラメーターが含まれる場合、操作は、応答の本文で BlobPrefix 要素を返します。この要素は、区切り文字が出現するまで同じサブ文字列で名前が始まるすべての BLOB に対するプレースホルダーとして機能します。区切り記号には単一文字または文字列を使用できます。

marker

省略可能。次の一覧操作で返される一覧の部分を識別する文字列値です。返される一覧が完全ではなかった場合、操作では応答本文にマーカー値が返されます。マーカー値を後続の呼び出しで使用して、一覧項目の次のセットを要求できます。

マーカー値はクライアントに対して非透過的です。

maxresults

省略可能。すべての BlobPrefix 要素も含め、返される BLOB の最大数を指定します。要求で maxresults が指定されていないか、5,000 を超える値が指定されている場合、サーバーは最大 5,000 項目を返します。

maxresults をゼロ以下の値に設定すると、エラー応答コード 400 (Bad Request) が発生します。

include={snapshots,metadata,uncommittedblobs,copy}

省略可能。応答に含める 1 つ以上のデータセットを指定します。

  • snapshots: スナップショットが列挙に含まれるように指定します。応答では、スナップショットは古いものから新しいものの順に列挙されます。

  • metadata: BLOB メタデータを応答で返すように指定します。

  • uncommittedblobs: ブロックは既にアップロードされているが、Put Block List を使用してコミットされていない BLOB を応答に含めるように指定します。

  • copy: バージョン 2012-02-12 以降。現在または以前の Copy Blob 操作に関連するメタデータを応答に含めるように指定します。

複数のオプションを URI で指定するには、URL エンコードのコンマ ("%82") で各オプションを区切る必要があります。

timeout

省略可能。timeout パラメーターは、秒単位で表されます。詳細については、「BLOB サービス操作のタイムアウトの設定」を参照してください。

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

 

要求ヘッダー 説明

Authorization

必須。認証スキーム、アカウント名、および署名を指定します。詳細については、「Azure ストレージ サービスの認証」を参照してください。

Date またはx-ms-date

必須。要求の世界協定時刻 (UTC) を指定します。詳細については、「Azure ストレージ サービスの認証」を参照してください。

x-ms-version

認証された要求では常に必須、匿名要求では省略可能です。この要求に使用する操作のバージョンを指定します。詳細については、「Azure ストレージ サービスのバージョン設定」を参照してください。

x-ms-client-request-id

省略可能。Storage Analytics Logging が有効な場合に解析ログに記録される、クライアントで生成された非透過の値を 1 KB の文字制限付きで提供します。クライアント側のアクティビティとサーバーが受け取る要求を相互に関連付けるには、このヘッダーを使用することを強くお勧めします。詳細については、「Storage Analytics Logging について」および「Azure のログ: ログを使用した、ストレージ要求の追跡」を参照してください。

なし。

要求の例は、「BLOB リソースの列挙」を参照してください。

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

操作が正常に終了すると、ステータス コード 200 (OK) が返されます。

ステータス コードの詳細については、「ステータス コードとエラー コード」を参照してください。

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

 

応答ヘッダー 説明

Content-Type

返される結果の形式を指定します。現在、この値は application/xml です。

x-ms-request-id

このヘッダーは要求を一意に識別するので、要求のトラブルシューティングに使用できます。詳細については、「API 操作のトラブルシューティング」を参照してください。

x-ms-version

要求の実行に使用する BLOB サービスのバージョンを示します。このヘッダーはバージョン 2009-09-19 以降を使用して行った要求に対して返されます。

このヘッダーは、コンテナーが BLOB サービスの 2009-09-19 バージョンを使用するパブリック アクセス用にマークされている場合は、バージョン指定のない匿名要求に対しても返されます。

Date

サービスによって生成される、応答の開始時刻を示す UTC 日付/時刻値。

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

PrefixMarkerMaxResultsDelimiter の各要素は、要求 URI で指定された場合にのみ存在します。NextMarker 要素は、一覧結果が不完全な場合にのみ値を持ちます。

スナップショット、BLOB メタデータ、およびコミットされていない BLOB は、要求の URI の include パラメーターで指定されている場合にのみ、応答に含まれます。

バージョン 2009-09-19 以降では、BLOB のプロパティは Properties 要素内にカプセル化されています。

バージョン 2013-08-15 以降では、EnumerationResults 要素には、BLOB エンドポイントを指定する ServiceEndpoint 属性と、コンテナーの名前を指定する ContainerName フィールドがあります。以前のバージョンでは、この 2 つの属性は ContainerName フィールドにまとめられていました。また、バージョン 2013-08-15 以降では、BlobUrl 要素が削除されました。

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">
  <Prefix>string-value</Prefix>
  <Marker>string-value</Marker>
  <MaxResults>int-value</MaxResults>
  <Delimiter>string-value</Delimiter>
  <Blobs>
    <Blob>
      <Name>blob-name</name>
      <Snapshot>date-time-value</Snapshot>
      <Properties>
        <Last-Modified>date-time-value</Last-Modified>
        <Etag>etag</Etag>
        <Content-Length>size-in-bytes</Content-Length>
        <Content-Type>blob-content-type</Content-Type>
        <Content-Encoding />
        <Content-Language />
        <Content-MD5 />
        <Cache-Control />
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>
        <BlobType>BlockBlob|PageBlob</BlobType>
        <LeaseStatus>locked|unlocked</LeaseStatus>
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>
        <LeaseDuration>infinite | fixed</LeaseDuration>
        <CopyId>id</CopyId>
        <CopyStatus>pending | success | aborted | failed </CopyStatus>
        <CopySource>source url</CopySource>
        <CopyProgress>bytes copied/bytes total</CopyProgress>
        <CopyCompletionTime>datetime</CopyCompletionTime>
        <CopyStatusDescription>error string</CopyStatusDescription>
      </Properties>
      <Metadata>   
        <Name>value</Name>
      </Metadata>
    </Blob>
    <BlobPrefix>
      <Name>blob-prefix</Name>
    </BlobPrefix>
  </Blobs>
  <NextMarker />
</EnumerationResults>

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

CopyIdCopyStatusCopySourceCopyProgressCopyCompletionTime、および CopyStatusDescription が含まれるのは、バージョン 2012-02-12 以降で、この操作に include={copy} パラメーターが含まれている場合に限られます。Copy Blob 操作でこの BLOB がコピー先になったことがない場合、あるいは Set Blob PropertiesPut Blob、または Put Block List を使用した Copy Blob 操作の完了後にこの BLOB が変更された場合には、これらの要素は表示されません。また、バージョン 2012-02-12 より前の Copy Blob で作成された BLOB についても、これらの要素は表示されません。

noteメモ
バージョン 2009-09-19 以降、List Blobs の応答本文で返される要素の名前は以下のように変更されています。

  • Last-Modified (旧称 LastModified)

  • Content-Length (旧称 Size)

  • Content-Type (旧称 ContentType)

  • Content-Encoding (旧称 ContentEncoding)

  • Content-Language (旧称 ContentLanguage)

Content-MD5 要素は、バージョン 2009-09-19 以降で作成された BLOB に対して表示されます。バージョン 2012-02-12 以降では、Content-MD5 値は、Put Blob を使用して BLOB を更新するときに BLOB サービスによって計算されます。Put Block List を使用して BLOB を作成するときは計算されません。この Content-MD5 は、BLOB を作成するとき、あるいは Put Block List または Set Blob Properties を呼び出すことで、明示的に設定できます。

応答の例については、「BLOB リソースの列挙」を参照してください。

コンテナーのアクセス制御リスト (ACL: Access Control List) がコンテナーへの匿名アクセスを許可するように設定されている場合、クライアントはこの操作を呼び出して BLOB のコンテンツを読み取ることができます。それ以外の場合、この操作は、アカウント所有者と、コンテナー内の BLOB を一覧表示するためのアクセス許可がある共有アクセス署名を持つ任意のユーザーが呼び出すことができます。

応答での BLOB のプロパティ

コミットされていない BLOB を列挙に含めるように要求した場合、一部のプロパティは BLOB がコミットされるまで設定されないため、一部のプロパティが応答で返されない場合があることに注意してください。

x-ms-blob-sequence-number 要素は、ページ BLOB に対してのみ返されます。

ページ BLOB の場合、Content-Length 要素で返される値は、BLOB の x-ms-blob-content-length ヘッダーの値に対応します。

Content-MD5 要素は、2009-09-19 以降のバージョンを使用して BLOB に設定された場合にのみ、応答の本文に含まれます。Content-MD5 プロパティは、BLOB の作成時、または Set Blob Properties を呼び出すことで設定できます。バージョン 2012-02-12 以降では、Put Blob 要求に MD5 ヘッダーが含まれていない場合でも、Put Blob でブロック BLOB の MD5 値が設定されます。

応答でのメタデータ

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

このパラメーターで要求されたメタデータは、2009-09-19 バージョンの BLOB サービスで設定されている名前付けの制約に従って格納する必要があります。このバージョン以降では、すべてのメタデータの名前は C# 識別子の名前付け規則に従う必要があります。

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


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

応答でのスナップショット

スナップショットは、URI で include=snapshots パラメーターが指定されていた場合にのみ、応答の一覧に含まれます。スナップショットはアクティブなリースを持つことができないので、応答の一覧のスナップショットには LeaseStatus 要素は含まれません。

区切り文字を指定して List Blobs を呼び出す場合、列挙にスナップショットも含めることはできません。要求に両方が含まれる場合は、InvalidQueryParameter エラー (HTTP ステータス コード 400 – Bad Request) が返されます。

応答でのコミットされていない BLOB

コミットされていない BLOB は、include=uncommittedblobs パラメーターが URI で指定されている場合にのみ、応答の一覧に含まれます。応答の一覧のコミットされていない BLOB には、次の要素は含まれません。

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

マーカー値を使用して結果セットを返す場合

maxresults パラメーターの値を指定し、返す BLOB の数がこの値を超えた場合、または maxresults の既定値を超えた場合、応答本文には、後続の要求で返す次の BLOB を示す NextMarker 要素が含まれます。次の項目セットを返すには、後続の要求の URI で NextMarker の値をマーカー パラメーターとして指定します。

NextMarker の値は非透過的に扱う必要があります。

BLOB の名前空間をスキャンするための区切り文字の使用

delimiter パラメーターは、呼び出し元がユーザー定義の区切り記号を使用して BLOB 名前空間をスキャンできるようにします。この方法で、BLOB の仮想階層をファイル システムと同様にスキャンできます。区切り記号には単一文字または文字列を使用できます。要求にこのパラメーターが含まれている場合、この操作によって BlobPrefix 要素が返されます。区切り文字が出現するまで、同じサブ文字列で名前が始まるすべての BLOB の代わりに BlobPrefix 要素が返されます。BlobPrefix 要素の値は substring+delimiter です。substring は 1 つ以上の BLOB 名の開始文字列となる共通サブ文字列、delimiterdelimiter パラメーターの値を表します。

要求 URI の prefix パラメーターの BlobPrefix の値を指定することで、このプレフィックスで始まる BLOB 一覧の後続の呼び出しに BlobPrefix の値を使用できます。

返される各 BlobPrefix 要素が、各 Blob 要素と同じように、結果の最大件数に加算されることに注意してください。

BLOB は、応答本文でアルファベット順に一覧表示されます (大文字が最初に表示されます)。

CopyStatusDescription のコピーのエラー

CopyStatusDescription には、Copy Blob のエラーに関する詳細情報が含まれます。

  • コピーの試行が失敗し、BLOB サービスが引き続き操作を再試行している場合、CopyStatuspending に設定され、CopyStatusDescription のテキストでは、最後にコピーしようとしたときに発生した可能性のあるエラーについて説明されます。

  • CopyStatusfailed に設定されている場合、CopyStatusDescription のテキストでは、コピー操作を失敗させたエラーについて説明されます。

CopyStatusDescription 値の 3 つのフィールドの説明を次の表に示します。

 

コンポーネント 説明

HTTP 状態コード

エラーを示す標準の 3 桁の整数。

エラー コード

<ErrorCode> 要素で Azure から提供されるエラーを説明するキーワード。<ErrorCode> 要素がない場合は、HTTP 仕様の 3 桁の HTTP ステータス コードに関連付けられた標準エラー テキストを含むキーワードが使用されます。「REST API の一般的なエラー コード」を参照してください。

情報

引用符で囲まれたエラーの詳しい説明。

一般的なエラー シナリオの CopyStatusCopyStatusDescription の値を次の表に示します。

Important重要
ここで示す説明テキストは、バージョン変更が行われなくても、警告なしに変更される可能性があるため、このテキストと厳密に一致しない場合があることに注意してください。

 

シナリオ CopyStatus 値 CopyStatusDescription 値

コピー操作が正常に完了した。

success

コピー操作が完了する前にユーザーが操作を中止した。

aborted

コピー操作の実行中、コピー元 BLOB からの読み取り時にエラーが発生したが、操作が再試行される。

pending

502 BadGateway "コピー元の読み取り時に再試行可能なエラーが発生しました。再試行します。エラーの時刻:<時刻>"

コピー操作でコピー先 BLOB への書き込み時にエラーが発生したが、操作が再試行される。

pending

500 InternalServerError "再試行可能なエラーが発生しました。再試行します。エラーの時刻:<時刻>"

コピー操作でコピー元 BLOB からの読み取り時に回復不能なエラーが発生した。

失敗

404 ResourceNotFound "コピー元の読み取り時にコピーに失敗しました。"

noteメモ
この基になるエラーを報告するときには、Azure から <ErrorCode> 要素で ResourceNotFound が返されます。応答に <ErrorCode> 要素がない場合は、HTTP ステータスの標準の文字列表記 (NotFound など) が表示されます。

すべてのコピー操作を制限するタイムアウト期間が経過した (現在、タイムアウト期間は 2 週間です)。

失敗

500 OperationCancelled "コピーの最大許容時間を超えました。"

コピー元からの読み取り時にコピー操作が何度も失敗しており、試行の最小成功率に達していなかった (このタイムアウトにより、失敗まで 2 週間にわたって状態の良くないコピー元に対して再試行が繰り返されるのを防ぎます)。

失敗

500 OperationCancelled "コピー元の読み取り時にコピーに失敗しました。"

この情報は役に立ちましたか。
(残り 1500 文字)
フィードバックをいただき、ありがとうございました
表示:
© 2014 Microsoft