ディレクトリとファイルのリスト

  • [アーティクル]

List Directories and Files 操作は、指定した共有またはディレクトリ内の、ファイルまたはディレクトリの一覧を返します。 ディレクトリ階層の 1 つのレベルについてのみ、その内容が一覧表示されます。

プロトコルの可用性

有効なファイル共有プロトコル 利用可能
SMB はい
NFS いいえ

Request

要求は List Directories and Files 次のように構築できます。 HTTPS が推奨されます。

Method 要求 URI HTTP バージョン
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

次のように、要求 URI に示されたパス コンポーネントを独自の URI に置き換えます。

パス コンポーネント 説明
myaccount ご利用のストレージ アカウントの名前。
myshare ファイル共有の名前。
mydirectorypath ディレクトリへのパス。

パスの名前付け制限の詳細については、「 共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

URI パラメーター

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

パラメーター 説明
prefix 省略可能。 バージョン 2016-05-31 以降。 結果をフィルター処理して、指定したプレフィックスで始まる名前を持つファイルとディレクトリのみを返します。
sharesnapshot 省略可能。 バージョン 2017-04-17 以降。 共有スナップショット パラメーターは不透明DateTimeな値であり、存在する場合は、ファイルとディレクトリの一覧に対してクエリを実行する共有スナップショットを指定します。
marker 省略可能。 次の一覧操作で返される一覧の部分を識別する文字列値です。 返されたリストが完了していない場合、操作は応答本文内のマーカー値を返します。 その後、後続の呼び出しでマーカー値を使用して、リスト アイテムの次のセットを要求できます。

マーカー値はクライアントに対して非透過的です。
maxresults 省略可能。 返すファイルまたはディレクトリの最大数を指定します。 要求で を指定 maxresultsしない場合、または 5,000 を超える値を指定した場合、サーバーは最大 5,000 個のアイテムを返します。

maxresults をゼロ以下の値に設定すると、エラー応答コード 400 (Bad Request) が発生します。
include={Timestamps, ETag, Attributes, PermissionKey} 必要に応じて、バージョン 2020-04-08 以降で使用できます。 応答に含める 1 つ以上のプロパティを指定します。
  • Timestamps
  • ETag
  • Attributes (Win32 ファイル属性)
  • PermissionKey

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

このパラメーターが指定されている場合、ヘッダー x-ms-file-extended-info は暗黙的に true と見なされます。
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「Azure Files操作のタイムアウトの設定」を参照してください。

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。匿名要求の場合は省略可能です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
x-ms-client-request-id 省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Filesの監視」を参照してください。
x-ms-file-extended-info: {true} 省略可能。 バージョン 2020-04-08 以降。 クエリ パラメーターが空でない場合、このヘッダーは暗黙的に include true と見なされます。 true の場合、 Content-Length プロパティは最新の状態になります。 バージョン 2020-04-08、2020-06-12、および 2020-08-04 では、このヘッダーが true の場合にのみ、 FileId ファイルとディレクトリに対して が返されます。 バージョン 2020-10-02 以降では、 FileId は常にファイルとディレクトリに対して返されます。
x-ms-file-request-intent ヘッダーが OAuth トークンを指定する場合 Authorization は必須。 許容される値は です backup。 このヘッダーは、 ヘッダーをMicrosoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action使用してAuthorization承認された ID に割り当てられた RBAC ポリシーに 含まれている場合に、 または Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action を許可するように指定します。 バージョン 2022-11-02 以降で使用できます。
x-ms-allow-trailing-dot: { <Boolean> } 省略可能。 バージョン 2022-11-02 以降。 ブール値は、要求 URL に存在する末尾のドットをトリミングするかどうかを指定します。 詳細については、「共有、 ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

要求本文

[なし] :

Response

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

status code

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

応答ヘッダー

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

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

応答本文

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

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

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">  
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>  
      <Properties>  
        <Content-Length>size-in-bytes</Content-Length>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive | Hidden | Offline | ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </File>  
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>  
      <Properties>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive | Hidden | Offline | ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </Directory>  
  </Entries>  
  <NextMarker />  
</EnumerationResults>

Content-Length 要素は一覧で返されます。 ただし、SMB クライアントがファイルをローカルで変更した可能性があるため、この値は最新ではない可能性があります。 の Content-Length 値は、ハンドルが閉じられるか、操作ロックが解除されるまで、その事実を反映しない可能性があります。 現在のプロパティ値を取得するには、 を使用 x-ms-file-extended-info: trueするか、 ファイルのプロパティの取得を呼び出します。

バージョン 2020-04-08、2020-06-12、および 2020-08-04 では、ヘッダーx-ms-file-extended-infoが true の場合、FileIdファイルとディレクトリに対して が返されます。 バージョン 2020-10-02 以降では、 FileId 常にファイルとディレクトリに対して が返されます。

バージョン 2020-04-08 では、include={timestamps}、、および LastWriteTimeのタイムスタンプ プロパティCreationTimeLastAccessTimeが返されます。 バージョン2020-06-12以降では、include={timestamps}、および Last-Modifiedのタイムスタンプ プロパティLastWriteTimeCreationTimeLastAccessTimeChangeTimeを返します。

バージョン 2020-10-02 以降では、 DirectoryId が応答で返されます。 API が FileId 呼び出されるディレクトリの を指定します。

バージョン 2021-12-02 以降では、 は XML List Directory and Files で無効な文字 (具体的には U+FFFE または U+FFFF) FileNameを含むすべての 、 DirectoryName、 Prefix または DirectoryPath 要素の値をパーセントエンコードします (RFC 2396 ごと)。 エンコードされた場合、 NamePrefix 要素または EnumerationResults 要素には 属性がEncoded=true含まれます。 これは、応答の Name 残りの Name 要素ではなく、XML で無効な文字を含む要素値に対してのみ発生することに注意してください。

タイムスタンプ フィールドの Datetime 形式と API バージョン

要素 日時の形式 値の例 API バージョン
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 以降
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 以降
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 以降
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 以降
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 以降

承認

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

解説

要素で Content-Length 返される値は、ファイル x-ms-content-length のヘッダーの値に対応します。

返される各 Directory 要素が、各 File 要素と同じように、結果の最大件数に加算されることに注意してください。 ファイルとディレクトリは、応答本文で構文的に並べ替えられた順序で混在して一覧表示されます。

一覧表示は、ディレクトリ階層の 1 つのレベルに制限されています。 複数のレベルを一覧表示するには、反復的な方法で複数の呼び出しを行うことができます。 の後続の Directory 呼び出しで、1 つの結果から返される値を使用します List Directories and Files。

関連項目

ディレクトリに対する操作