次の方法で共有

ディレクトリとファイルを一覧表示する

  • [アーティクル]

List Directories and Files 操作は、指定した共有またはディレクトリの下にあるファイルまたはディレクトリの一覧を返します。 ディレクトリ階層の 1 つのレベルについてのみ内容が一覧表示されます。 この操作は、NFS プロトコルが有効になっているファイル共有のバージョン 2025-05-05 以降でサポートされています。

プロトコルの可用性

有効なファイル共有プロトコル 利用できる
SMB はい
NFS はい

依頼

List Directories and Files 要求は次のように構成されます。 HTTPS を使用することをお勧めします。

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

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

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

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

URI パラメーター

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

一般的な URI パラメーター

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

マーカー値はクライアントに対して不透明です。
maxresults 随意。 返されるファイルまたはディレクトリの最大数を指定します。 要求で maxresultsを指定しない場合、または 5,000 を超える値を指定した場合、サーバーは最大 5,000 個の項目を返します。

maxresults を 0 以下の値に設定すると、エラー応答コード 400 (Bad Request) が発生します。
timeout 随意。 timeout パラメーターは秒単位で表されます。 詳細については、「Azure Files 操作のタイムアウトの設定」を参照してください。

SMB のみの URI パラメーター

パラメーター 形容
include={Timestamps, ETag, Attributes, PermissionKey} 必要に応じて、バージョン 2020-04-08 以降で使用できます。 応答に含める 1 つ以上のプロパティを指定します。
  • Timestamps
  • ETag
  • Attributes (Win32 ファイル属性)
  • PermissionKey

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

このパラメーターを指定すると、ヘッダー x-ms-file-extended-info は暗黙的に true と見なされます。

NFS のみの URI パラメーター

何一つ。

要求ヘッダー

必須および省略可能な要求ヘッダーについては、次の表で説明します。

一般的な要求ヘッダー

要求ヘッダー 形容
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。
Date または x-ms-date 必須。 要求の世界協定時刻 (UTC) を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 この操作は、NFS プロトコルが有効になっているファイル共有のバージョン 2025-05-05 以降でサポートされています。

詳細については、Azure Storage サービス のバージョン管理のに関するページを参照してください。
x-ms-client-request-id 随意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Files」を参照してください。
x-ms-file-request-intent ヘッダー Authorization OAuth トークンを指定する場合は必須です。 許容される値は backupです。 このヘッダーは、Authorization ヘッダーを使用して承認された ID に割り当てられた RBAC ポリシーに含まれている場合、Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action または Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action を付与するように指定します。 バージョン 2022-11-02 以降で使用できます。
x-ms-allow-trailing-dot: { <Boolean> } 随意。 バージョン 2022-11-02 以降。 ブール値は、要求 URL に存在する末尾のドットをトリミングするかどうかを指定します。

ターゲットが NFS プロトコルが有効なファイル共有上にある場合、このヘッダーは無視され、既定では末尾のドットがサポートされます。

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

SMB のみの要求ヘッダー

要求ヘッダー 形容
x-ms-file-extended-info: {true} 随意。 バージョン 2020-04-08 以降。 include クエリ パラメーターが空でない場合、このヘッダーは暗黙的に true と見なされます。 true の場合、ファイルのサイズを示すファイルの Content-Length プロパティは最新の状態になります。

NFS 要求ヘッダーのみ

何一つ。

要求本文

何一つ。

応答

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

状態コード

操作が成功すると、状態コード 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 ヘッダーが要求に存在しない場合、このヘッダーは応答に存在しません。

SMB のみの応答ヘッダー

何一つ。

NFS のみの応答ヘッダー

何一つ。

応答本文

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

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

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

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

SMB プロトコルが有効になっているファイル共有の応答本文

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

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

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

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

NFS プロトコルが有効になっているファイル共有の応答本文

<?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>
      </Properties>
    </File>
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>
    </Directory>
  </Entries>
  <NextMarker />
</EnumerationResults>

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

要素 Datetime 形式 サンプル値 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 値を使用します。

関連項目

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