디렉터리 및 파일 나열

List Directories and Files 작업은 지정된 공유 또는 디렉터리 아래의 파일 또는 디렉터리 목록을 반환합니다. 디렉터리 계층 구조의 단일 수준에 대해서만 콘텐츠를 나열합니다. 이 작업은 NFS 프로토콜이 설정된 파일 공유에 대해 버전 2025-05-05 이상에서 지원됩니다.

프로토콜 가용성

파일 공유 프로토콜 사용	이용할 수 있는
SMB
NFS

요청

List Directories and Files 요청은 다음과 같이 생성됩니다. HTTPS를 사용하는 것이 좋습니다.

요청 URI에 표시된 경로 구성 요소를 다음과 같이 사용자 고유의 경로 구성 요소로 바꿉니다.

경로 명명 제한에 대한 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 명명 및 참조를 참조하세요.

URI 매개 변수

URI에 다음 추가 매개 변수를 지정할 수 있습니다.

일반적인 URI 매개 변수

SMB 전용 URI 매개 변수

NFS 전용 URI 매개 변수

없음.

요청 헤더

필수 및 선택적 요청 헤더는 다음 표에 설명되어 있습니다.

일반적인 요청 헤더

SMB 전용 요청 헤더

NFS만 요청 헤더

없음.

요청 본문

없음.

응답

응답에는 HTTP 상태 코드, 응답 헤더 집합 및 XML 형식의 응답 본문이 포함됩니다.

상태 코드

작업이 성공하면 상태 코드 200(확인)이 반환됩니다. 상태 코드에 대한 자세한 내용은 상태 및 오류 코드참조하세요.

응답 헤더

이 작업에 대한 응답에는 다음 표의 헤더가 포함됩니다. 응답에는 추가 표준 HTTP 헤더도 포함될 수 있습니다. 모든 표준 헤더는 HTTP/1.1 프로토콜 사양준수합니다.

일반적인 응답 헤더

SMB 전용 응답 헤더

없음.

NFS만 응답 헤더

없음.

응답 본문

XML 응답의 형식은 다음과 같습니다.

Marker, ShareSnapshot및 MaxResults 요소는 요청 URI에 지정하는 경우에만 존재합니다. NextMarker 요소에는 목록 결과가 완료되지 않은 경우에만 값이 있습니다.

Content-Length 요소는 파일의 크기를 나타내는 파일 목록에 반환됩니다. 그러나 SMB 또는 NFS 클라이언트가 파일을 로컬로 수정했을 수 있으므로 이 값은 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>

타임스탬프 필드의 날짜/시간 형식 및 API 버전

권한 부여

계정 소유자만 이 작업을 호출할 수 있습니다.

발언

Content-Length 요소에서 반환되는 값은 파일의 x-ms-content-length 헤더 값에 해당합니다.

반환된 각 Directory 요소는 각 File 요소와 마찬가지로 최대 결과에 대한 개수를 계산합니다. 파일 및 디렉터리에는 응답 본문에서 어휘적으로 정렬된 순서로 섞여 나열됩니다.

목록은 디렉터리 계층 구조의 단일 수준으로 제한됩니다. 여러 수준을 나열하려면 반복적인 방식으로 여러 호출을 수행할 수 있습니다. Directory후속 호출에서 한 결과에서 반환된 List Directories and Files 값을 사용합니다.

참고 항목

디렉터리 작업