Blob 나열

아티클
03/16/2023

작업은 List Blobs 지정된 컨테이너 아래의 Blob 목록을 반환합니다.

요청

다음과 같이 요청을 생성할 List Blobs 수 있습니다. HTTPS를 사용하는 것이 좋습니다. myaccount를 스토리지 계정의 이름으로 바꿉니다.

메서드	요청 URI	HTTP 버전
`GET`	`https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list`	HTTP/1.1

에뮬레이트된 스토리지 서비스 URI

에뮬레이트된 스토리지 서비스에 대해 요청할 때 에뮬레이터 호스트 이름 및 Azure Blob Storage 포트를 로 127.0.0.1:10000지정한 다음 에뮬레이트된 스토리지 계정 이름을 지정합니다.

메서드	요청 URI	HTTP 버전
`GET`	`http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list`	HTTP/1.1

자세한 내용은 로컬 Azure Storage 개발에 Azurite 에뮬레이터 사용을 참조하세요.

URI 매개 변수

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

매개 변수	Description
`prefix`	선택 사항입니다. 지정된 접두사로 시작하는 이름의 Blob만 반환하도록 결과를 필터링합니다. 계층 구조 네임스페이스가 있는 계정에서 파일 이름이 접두사 경로 중간에 표시되는 경우 오류가 발생합니다. 예를 들어 접두사 경로 `folder1/folder2/readme/readmefile.txt`를 사용하여 이름이 지정된 `readmefile.txt` Blob을 찾으려고 시도할 수 있습니다. 하위 폴더에 라는 `readme`파일이 있으면 오류가 표시됩니다.
`delimiter`	선택 사항입니다. 요청에 이 매개 변수가 포함되면 작업은 응답 본문의 요소를 반환합니다 `BlobPrefix` . 이 요소는 구분 기호 문자의 모양까지 동일한 부분 문자열로 시작하는 이름의 모든 Blob에 대한 자리 표시자 역할을 합니다. 이 구분 기호는 단일 문자이거나 문자열일 수 있습니다.
`marker`	선택 사항입니다. 다음 목록 작업으로 반환할 목록 부분을 식별하는 문자열 값입니다. 이 작업은 반환된 목록이 완전하지 않은 경우 응답 본문 내의 마커 값을 반환합니다. 그런 다음, 후속 호출에서 표식 값을 사용하여 다음 목록 항목 집합을 요청할 수 있습니다. 마커 값은 클라이언트에 불투명합니다.
`maxresults`	선택 사항입니다. 모든 `BlobPrefix` 요소를 포함하여 반환할 최대 Blob 수를 지정합니다. 요청이 를 지정 `maxresults`하지 않거나 5,000보다 큰 값을 지정하는 경우 서버는 최대 5,000개의 항목을 반환합니다. 반환할 추가 결과가 있는 경우 서비스는 응답 요소에 연속 토큰을 `NextMarker` 반환합니다. 경우에 따라 서비스는 에서 지정한 `maxresults`것보다 적은 결과를 반환하고 연속 토큰도 반환할 수 있습니다. 0 이하로 `maxresults`를 설정하면 오류 응답 코드 400(잘못된 요청)를 반환합니다.
`include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,` `deletedwithversions,immutabilitypolicy,legalhold,permissions}`	선택 사항입니다. 응답에 포함시킬 데이터 집합을 하나 이상 지정합니다. - `snapshots`: 스냅샷을 열거형에 포함되도록 지정합니다. 응답에서 스냅숏은 생성된 시간 순서로 나열됩니다. - `metadata`: 응답에서 Blob 메타데이터가 반환되도록 지정합니다. - `uncommittedblobs`: 블록이 업로드되었지만 블록 배치 목록을 사용하여 커밋되지 않은 Blob이 응답에 포함되도록 지정합니다. - `copy`: 버전 2012-02-12 이상. 응답에 포함해야 할, 현재 또는 이전 `Copy Blob` 작업에 관련된 메타데이터를 지정합니다. -`deleted`: 버전 2017-07-29 이상. 일시 삭제된 Blob을 응답에 포함되도록 지정합니다. -`tags`: 버전 2019-12-12 이상. 사용자 정의 Blob 인덱스 태그를 응답에 포함되도록 지정합니다. -`versions`: 버전 2019-12-12 이상. Blob 버전을 열거형에 포함되도록 지정합니다. -`deletedwithversions`: 버전 2020-10-02 이상. 모든 버전(활성 또는 삭제됨)이 있는 삭제된 Blob을 응답에 포함되도록 지정합니다. 영구적으로 삭제한 항목은 가비지 수집에서 처리될 때까지 응답에 표시됩니다. 태그 `\<HasVersionsOnly\>`및 값을 `true`사용합니다. -`immutabilitypolicy`: 버전 2020-06-12 이상. 열거형에 날짜까지 불변성 정책 및 Blob의 불변성 정책 모드가 포함되도록 지정합니다. -`legalhold`: 버전 2020-06-12 이상. 열거형에 Blob의 법적 보존이 포함되도록 지정합니다. -`permissions`: 버전 2020-06-12 이상. 계층 구조 네임스페이스가 사용하도록 설정된 계정에 대해서만 지원됩니다. 요청에 이 매개 변수가 포함된 경우 나열된 Blob 또는 디렉터리에 대한 소유자, 그룹, 권한 및 액세스 제어 목록이 열거형에 포함됩니다. URI에 이러한 작업을 하나 이상을 지정하려면 URL로 인코딩된 쉼표("%82")로 각 옵션을 구분해야 합니다.
`showonly={deleted,files,directories}`	선택 사항입니다. 응답에서 반환할 다음 데이터 세트 중 하나를 지정합니다. -`deleted`:선택적. 버전 2020-08-04 이상. 계층 구조 네임스페이스에서 사용하도록 설정된 계정에만 해당합니다. 요청에 이 매개 변수가 포함된 경우 목록에는 일시 삭제된 Blob만 포함됩니다. 일시 삭제된 Blob을 나열하는 데 POSIX ACL 권한 부여 대체는 지원되지 않습니다. 도 지정된 경우 `include=deleted` 잘못된 요청(400)으로 요청이 실패합니다. -`files`:선택적. 버전 2020-12-06 이상. 계층 구조 네임스페이스에서 사용하도록 설정된 계정에만 해당합니다. 요청에 이 매개 변수가 포함된 경우 목록에는 파일만 포함됩니다. -`directories`:선택적. 버전 2020-12-06 이상. 계층 구조 네임스페이스에서 사용하도록 설정된 계정에만 해당합니다. 요청에 이 매개 변수가 포함된 경우 목록에는 디렉터리만 포함됩니다.
`timeout`	선택 사항입니다. `timeout` 매개 변수는 초 단위로 표시됩니다. 자세한 내용은 Blob Storage 작업에 대한 시간 제한 설정을 참조하세요.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

요청 헤더	Description
`Authorization`	필수 사항입니다. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`Date` 또는 `x-ms-date`	필수 사항입니다. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`x-ms-version`	모든 권한 있는 요청에 필요하고 익명 요청에는 선택 사항입니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요.
`x-ms-client-request-id`	선택 사항입니다. 로깅이 구성될 때 로그에 기록되는 1키비바이트(KiB) 문자 제한을 사용하여 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Blob Storage 모니터링을 참조하세요.
`x-ms-upn`	선택 사항입니다. 계정에 `include=permissions` 대해 계층 구조 네임스페이스를 사용하도록 설정하고 요청에 제공된 경우에만 유효합니다. 이면 `true`소유자>, <그룹> 및 <Acl> 필드에 반환<된 사용자 ID 값이 Microsoft Entra 개체 ID에서 사용자 계정 이름으로 변환됩니다. 이면 `false`값이 Microsoft Entra 개체 ID로 반환됩니다. 기본값은 `false`입니다. 그룹 및 애플리케이션 개체 ID는 고유한 식별 이름이 없으므로 번역되지 않습니다.

요청 본문

없음

샘플 요청

샘플 요청 은 Blob 리소스 열거 를 참조하세요.

응답

응답에는 HTTP 상태 코드, 응답 헤더 집합 및 응답 본문이 XML 형식으로 포함되어 있습니다.

상태 코드

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

응답 헤더

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

응답 헤더	Description
`Content-Type`	결과가 반환될 형식을 지정합니다. 현재 이 값은 `application/xml`입니다.
`x-ms-request-id`	이 헤더는 만들어진 요청을 고유하게 식별하며 요청 문제 해결에 사용할 수 있습니다. 자세한 내용은 API 작업 문제 해결을 참조하세요.
`x-ms-version`	요청을 실행하는 데 사용되는 Blob Storage의 버전을 나타냅니다. 이 헤더는 버전 2009-09-19 이상을 사용하여 수행한 요청에 대해 반환됩니다. 컨테이너가 2009-09-19 버전의 Blob Storage를 사용하여 공용 액세스용으로 표시된 경우 지정된 버전 없이 익명 요청에 대해서도 이 헤더가 반환됩니다.
`Date`	응답이 시작된 시간을 나타내는 UTC 날짜/시간 값입니다. 서비스는 이 값을 생성합니다.
`x-ms-client-request-id`	이 헤더를 사용하여 요청 및 해당 응답 문제를 해결할 수 있습니다. 이 헤더의 값은 요청에 있는 경우 헤더 값 `x-ms-client-request-id` 과 같습니다. 값은 최대 1024자 표시 ASCII 문자입니다. 헤더가 `x-ms-client-request-id` 요청에 없는 경우 이 헤더는 응답에 존재하지 않습니다.

응답 본문

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

Prefix, Marker, MaxResults 및 Delimiter 요소의 경우 요청 URI에 지정된 경우에만 포함됩니다. NextMarker 요소에는 목록 결과가 완료되지 않은 경우에만 값이 있습니다.

스냅숏, Blob 메타데이터 및 커밋되지 않은 Blob는 include 매개 변수를 사용하여 요청 URI에 지정된 경우에만 응답에 포함됩니다.

버전 2009-09-19 이상에서는 Blob의 속성이 요소 내에 Properties 캡슐화됩니다.

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 이상에서 Blob Storage는 Blob 배치를 사용하여 Blob을 업로드할 때 값을 계산합니다Content-MD5. 블록 목록 배치를 사용하여 Blob을 만들 때 Blob Storage는 이를 계산하지 않습니다. Blob을 Content-MD5 만들 때 또는 블록 목록 배치 또는 Blob 속성 설정 작업을 호출하여 값을 명시적으로 설정할 수 있습니다.

2009-09-19 이상 버전이지만 버전 2015-02-21 이전의 경우 추가 Blob이 포함된 컨테이너에서 를 호출 List Blobs 할 수 없습니다. 이 서비스는 목록의 결과에 추가 Blob이 포함된 경우 상태 코드 409(충돌)를 반환합니다.

LeaseState 및 LeaseDuration 는 버전 2012-02-12 이상에만 표시됩니다.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTime 및 CopyStatusDescription은 이 작업에 include={copy} 매개 변수가 포함될 경우 2012-02-12 이후 버전에서만 표시됩니다. 이 Blob이 작업의 대상이 Copy Blob 된 적이 없는 경우 이러한 요소는 표시되지 않습니다. , Put Blob또는 Put Block List를 사용하여 Set Blob Properties종료된 Copy Blob 작업 후에 이 Blob이 수정된 경우 요소가 나타나지 않습니다. 또한 이러한 요소는 버전 2012-02-12 이전의 Blob 복사에서 만든 Blob과 함께 표시되지 않습니다.

버전 2013-08-15 이상 EnumerationResults 에서는 요소에 Blob 엔드포인트를 ServiceEndpoint 지정하는 특성이 포함되어 있습니다. 이 요소에는 ContainerName 컨테이너의 이름을 지정하는 필드도 포함되어 있습니다. 이전 버전에서는 이러한 두 특성이 필드에서 함께 ContainerName 결합되었습니다. 또한 버전 2013-08-15 이상에서는 Url 아래 Blob 요소가 제거되었습니다.

버전 2015-02-21 이상 List Blobs 에서는 모든 형식(블록, 페이지 및 추가 Blob)의 Blob을 반환합니다.

버전 2015-12-11 이상 List Blobs 에서는 요소를 반환합니다 ServerEncrypted . 이 요소는 Blob 및 애플리케이션 메타데이터가 완전히 암호화된 경우 로 설정되며false, 그렇지 않으면 로 설정 true 됩니다.

버전 2016-05-31 이상 List Blobs 에서는 값이 로 설정된 true증분 복사 Blob 및 스냅샷에 대한 요소를 반환 IncrementalCopy 합니다.

버전 2017-04-17 이상 List Blobs 에서는 액세스 계층이 명시적으로 설정된 경우 요소를 반환합니다 AccessTier . 허용되는 프리미엄 페이지 Blob 계층 목록은 VM용 고성능 Premium Storage 및 관리 디스크를 참조하세요. Blob Storage 또는 범용 v2 계정의 경우 유효한 값은 , Cool및 Archive입니다Hot. Blob이 리하일레이트 보류 상태에 ArchiveStatus 있는 경우 요소는 유효한 값(rehydrate-pending-to-hot, rehydrate-pending-to-cool또는 rehydrate-pending-to-cold) 중 하나를 사용하여 반환됩니다. 블록 Blob 계층화에 대한 자세한 내용은 핫, 쿨 및 보관 스토리지 계층을 참조하세요.

버전 2017-04-17 이상 List Blobs 에서는 Blob Storage 또는 범용 v2 계정의 요소를 반환 AccessTierInferred 합니다. 블록 Blob에 액세스 계층 집합이 없는 경우 계층 정보는 스토리지 계정 속성에서 유추되고 이 값은 로 true설정됩니다. 이 헤더는 계층이 계정 속성에서 유추되는 경우에만 존재합니다.

버전 2017-04-17 이상 List Blobs 에서는 Blob Storage 또는 범용 v2 계정의 요소를 반환 AccessTierChangeTime 합니다. 블록 Blob의 계층이 설정된 경우에만 반환됩니다. 자세한 내용은 헤더의 날짜-시간 값 표현을 참조하세요.

버전 2017-07-29 이상에서는 Deleted, DeletedTime및 RemainingRetentionDays 가 이 작업에 매개 변수를 포함할 include={deleted} 때 나타납니다. 이 Blob이 삭제되지 않은 경우 이러한 요소가 표시되지 않습니다. 이러한 요소는 일시 삭제 기능을 사용하도록 설정한 경우 작업과 함께 DELETE 삭제된 Blob 또는 스냅샷에 대해 나타납니다. Deleted 요소는 일시 삭제된 Blob 및 스냅샷에 대해 로 설정 true 됩니다. Deleted-Time 는 Blob이 삭제된 시간에 해당합니다. RemainingRetentionDays 는 일시 삭제된 Blob이 영구적으로 삭제된 후의 일 수를 나타냅니다.

버전 2017-11-09 이상 Creation-Time 에서는 이 Blob이 만들어진 시간을 반환합니다.

버전 2019-02-02 이상 List Blobs 에서는 Blob이 고객이 제공한 키로 암호화된 경우 요소를 반환 CustomerProvidedKeySha256 합니다. 값은 Blob을 암호화하는 데 사용되는 키의 SHA-256 해시로 설정됩니다. 또한 작업에 매개 변수가 include={metadata} 포함되어 있고 고객이 제공한 키 Metadata 로 암호화된 Blob에 애플리케이션 메타데이터가 있는 경우 요소에 특성이 Encrypted="true" 있습니다. 이 특성은 Blob에 작업의 일부로 암호 해독할 수 없는 메타데이터가 List Blobs 있음을 나타냅니다. 이러한 Blob에 대한 메타데이터에 액세스하려면 Blob 속성 가져오기 또는 고객이 제공한 키를 사용하여 Blob 메타데이터 가져오기 를 호출합니다.

버전 2019-02-02 이상 List Blobs 에서는 Blob이 암호화 scope 암호화된 경우 요소를 반환 EncryptionScope 합니다. 값은 Blob을 암호화하는 데 사용되는 암호화 scope 이름으로 설정됩니다. 작업에 매개 변수가 include={metadata} 포함된 경우 Blob의 애플리케이션 메타데이터는 투명하게 암호 해독되고 요소에서 Metadata 사용할 수 있습니다.

버전 2019-12-12 이상 List Blobs 에서는 개체가 RehydratePriority 상태인 경우 Blob Storage 또는 범용 v2 계정의 rehydrate pending 요소를 반환합니다. 유효한 값은 High 및 Standard입니다.

버전 2019-12-12 이상 List Blobs 에서는 계정에서 버전 관리를 사용하도록 설정할 때 Blob 및 생성된 Blob 버전에 대한 요소를 반환 VersionId 합니다.

버전 2019-12-12 이상 List Blobs 에서는 Blob의 현재 버전에 대한 요소를 반환 IsCurrentVersion 합니다. 값이 true로 설정된 경우 이 요소를 사용하면 현재 버전을 자동으로 생성된 읽기 전용 버전과 구분할 수 있습니다.

버전 2019-12-12 이상 List Blobs 에서는 태그가 TagCount 있는 Blob의 요소를 반환합니다. 요소는 이 Tags 작업에 매개 변수가 포함된 include={tags} 경우에만 나타납니다. Blob에 태그가 없으면 이러한 요소가 표시되지 않습니다.

버전 2019-12-12 이상 List Blobs 에서는 추가 Blob에 Sealed 대한 요소를 반환합니다. 요소는 Sealed 추가 Blob이 봉인된 경우에만 나타납니다. 추가 Blob이 봉인되지 않은 경우 이러한 요소가 표시되지 않습니다.

버전 2020-02-10 이상 List Blobs 에서는 요소를 반환합니다 LastAccessTime . 요소는 스토리지 계정의 마지막 액세스 시간 추적 정책에 따라 Blob의 데이터에 마지막으로 액세스한 시간을 표시합니다. 스토리지 계정에 이 정책이 없거나 정책이 비활성화된 경우 요소가 반환되지 않습니다. 계정의 마지막 액세스 시간 추적 정책을 설정하는 방법에 대한 자세한 내용은 Blob Service API를 참조하세요. 요소는 LastAccessTime Blob의 메타데이터에 액세스한 마지막 시간을 추적하지 않습니다.

버전 2020-06-12 이상 List Blobs 에서는 이 작업에 매개 변수가 ImmutabilityPolicyUntilDate 포함된 include={immutabilitypolicy} 경우 및 ImmutabilityPolicyMode 요소를 반환합니다.

버전 2020-06-12 이상 List Blobs 에서는 이 작업에 매개 변수가 LegalHold 포함된 include={legalhold} 경우 요소를 반환합니다.

버전 2020-06-12 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 List Blobs 계정의 경우 , , GroupPermissions및 Acl 요소를 반환Owner합니다. 요청에는 매개 변수가 include={permissions} 포함되어야 합니다. Acl 요소는 파일 또는 디렉터리에 설정된 액세스 및 기본 액세스 제어 목록의 결합된 목록입니다.

버전 2020-06-12 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 List Blobs 계정의 경우 구분 기호를 사용하여 요소의 PropertiesBlobPrefix 요소를 반환합니다. 이는 디렉터리의 속성에 해당합니다.

버전 2020-08-04 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 계정의 DeletionId 경우 삭제된 List Blobs Blob에 대한 요소를 반환합니다. DeletionId 는 서명되지 않은 64비트 식별자입니다. 요소는 일시 삭제된 경로를 고유하게 식별하여 동일한 경로를 사용하여 삭제된 다른 Blob과 구분합니다.

버전 2020-10-02 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 List Blobs 계정의 ResourceType 경우 경로에 대한 속성 요소를 반환합니다. file 또는 directory일 수 있습니다.

버전 2021-02-12 이상 List Blobs 에서는 모든 BlobName 또는 BlobPrefixName 요소 값(RFC 2396당)을 백분율로 인코딩합니다. 특히 XML(U+FFFE 또는 U+FFFF)에서 유효하지 않은 문자가 포함된 값에 대해 이 작업을 수행합니다. 인코딩된 경우 요소에 Name 특성이 Encoded=true 포함됩니다. 이는 응답의 Name 나머지 요소가 아니라 XML에서 유효하지 않은 문자를 포함하는 요소 값에 대해서만 발생합니다 Name .

버전 2021-06-08 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 List Blobs 계정의 Placeholder 경우 속성 요소를 반환합니다. 구분 기호를 BlobPrefix 사용하여 삭제된 Blob을 나열할 때 자리 표시자 디렉터리에 대한 요소에서 이 요소를 반환합니다. 이러한 자리 표시자 디렉터리 때문에 일시 삭제된 Blob으로 쉽게 탐색할 수 있습니다.

버전 2021-06-08 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 List Blobs 계정의 EncryptionContext 경우 요소를 반환합니다. 암호화 컨텍스트 속성 값이 설정되면 set 값을 반환합니다.

버전 2020-02-10 이상에서는 계층 구조 네임스페이스가 사용하도록 설정된 계정의 Expiry-Time 경우 삭제된 List Blobs Blob에 대한 요소를 반환합니다. Expiry-Time 는 파일이 만료되는 시간이며, 만료가 동일하게 설정된 경우 파일에 대해 반환됩니다.

<?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>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <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|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <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>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

샘플 응답

샘플 응답은 Blob 리소스 열거 를 참조하세요.

권한 부여

Azure Storage에서 데이터 액세스 작업을 호출할 때 권한 부여가 필요합니다. 아래에 설명된 대로 작업에 권한을 부여할 List Blobs 수 있습니다.

Azure Storage는 Microsoft Entra ID 사용하여 Blob 데이터에 대한 요청에 권한을 부여할 수 있도록 지원합니다. Microsoft Entra ID 사용하면 Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 보안 주체에 권한을 부여할 수 있습니다. 보안 주체는 사용자, 그룹, 애플리케이션 서비스 주체 또는 Azure 관리 ID일 수 있습니다. 보안 주체는 Microsoft Entra ID 인증되어 OAuth 2.0 토큰을 반환합니다. 그런 다음 토큰을 사용하여 Blob service에 대한 요청을 승인할 수 있습니다.

Microsoft Entra ID 사용하여 권한 부여에 대한 자세한 내용은 Microsoft Entra ID 사용하여 Blob에 대한 액세스 권한 부여를 참조하세요.

사용 권한

아래에는 Microsoft Entra 사용자, 그룹 또는 서비스 주체가 작업을 호출 List Blobs 하는 데 필요한 RBAC 작업과 이 작업을 포함하는 최소 권한의 기본 제공 Azure RBAC 역할이 나와 있습니다.

Azure RBAC 작업:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
최소 권한 기본 제공 역할:Storage Blob 데이터 읽기 권한자

Azure RBAC를 사용하여 역할을 할당하는 방법에 대한 자세한 내용은 Blob 데이터에 액세스하기 위해 Azure 역할 할당을 참조하세요.

SAS(공유 액세스 서명)는 스토리지 계정의 리소스에 대한 보안 위임 액세스를 제공합니다. SAS를 사용하면 클라이언트가 데이터에 액세스하는 방법을 세분화하여 제어할 수 있습니다. 클라이언트가 액세스할 수 있는 리소스, 해당 리소스에 대한 사용 권한 및 SAS가 유효한 기간을 지정할 수 있습니다.

이 List Blobs 작업은 사용자 위임 SAS, 서비스 SAS 및 계정 SAS의 세 가지 유형의 공유 액세스 서명을 지원 합니다.

보안 모범 사례로 더 쉽게 손상될 수 있는 스토리지 계정 키 대신 Microsoft Entra 자격 증명을 사용하는 것이 좋습니다. 애플리케이션 디자인에 공유 액세스 서명이 필요한 경우 Microsoft Entra 자격 증명을 사용하여 가능한 경우 사용자 위임 SAS를 만듭니다.

스토리지 계정에 대한 공유 키 액세스가 허용되지 않는 경우 Blob Storage에 대한 요청에 서비스 SAS 토큰 또는 계정 SAS 토큰이 허용되지 않습니다. 자세한 내용은 공유 키를 허용하지 않는 것이 SAS 토큰에 미치는 영향 이해를 참조하세요.

사용자 위임 SAS

사용자 위임 SAS는 Microsoft Entra 자격 증명과 SAS에 대해 지정된 권한으로 보호됩니다.

List Blobs 컨테이너 리소스에 위임된 SAS 토큰을 사용하여 작업을 호출하려면 사용자 위임 SAS 토큰의 일부로 목록(l) 권한이 필요합니다.

사용자 위임 SAS에 대한 자세한 내용은 사용자 위임 SAS 만들기를 참조하세요.

서비스 SAS

서비스 SAS는 스토리지 계정 키로 보호됩니다. 서비스 SAS는 Blob Storage와 같은 단일 Azure Storage 서비스의 리소스에 대한 액세스를 위임합니다.

List Blobs 컨테이너 리소스에 위임된 SAS 토큰을 사용하여 작업을 호출하려면 서비스 SAS 토큰의 일부로 목록(l) 권한이 필요합니다.

서비스 SAS에 대한 자세한 내용은 서비스 SAS 만들기를 참조하세요.

계정 SAS

계정 SAS는 스토리지 계정 키로 보호됩니다. 계정 SAS는 하나 이상의 스토리지 서비스에서 리소스에 대한 액세스 권한을 위임합니다. 서비스 SAS 또는 사용자 위임 SAS를 통해 가능한 모든 작업은 계정 SAS를 통해서도 가능합니다.

다음 표에서는 액세스를 위임할 때 지정할 서명된 리소스 종류 및 서명된 권한을 나타냅니다.

작업	서명된 서비스	서명된 리소스 종류	서명된 권한
Blob 나열	Blob(b)	컨테이너(c)	목록(l)

계정 SAS에 대한 자세한 내용은 계정 SAS 만들기를 참조하세요.

작업은 List Blobs공유 키 권한 부여를 지원합니다. 보안이 떨어지기 때문에 대부분의 시나리오에서는 계정 키를 사용하여 권한을 부여하지 않는 것이 좋습니다.

가능한 경우 스토리지 계정에 대한 공유 키 권한 부여를 허용하지 않는 것이 좋습니다. 자세한 내용은 공유 키로 권한 부여 방지를 참조하세요.

설명

응답의 Blob 속성

커밋되지 않은 Blob을 열거형에 포함하도록 요청한 경우 Blob이 커밋될 때까지 일부 속성이 설정되지 않습니다. 일부 속성은 응답에 반환되지 않을 수 있습니다.

페이지 Blob에 대해 x-ms-blob-sequence-number 요소만 반환됩니다.

요소는 OrMetadata 블록 Blob에 대해서만 반환됩니다.

페이지 Blob의 경우 Content-Length 요소는 Blob의 x-ms-blob-content-length 헤더 값에 해당되는 값을 반환합니다.

요소는 Content-MD5 버전 2009-09-19 이상을 사용하여 Blob에 설정된 경우에만 응답 본문에 표시됩니다. Blob을 Content-MD5 만들 때 또는 Blob 속성 설정을 호출하여 속성을 설정할 수 있습니다. 버전 2012-02-12 이상 Put Blob 에서는 요청에 MD5 헤더가 포함되지 않은 경우에도 Put Blob 블록 Blob의 MD5 값을 설정합니다.

응답의 메타데이터

Metadata 요소는 include=metadata 매개 변수가 URI에 지정된 경우에만 제공됩니다. Metadata 요소 내에서 각 이름-값 쌍의 값은 해당 쌍의 이름에 해당하는 요소 내에 나열됩니다.

이 매개 변수로 요청된 메타데이터는 Blob Storage의 2009-09-19 버전에서 적용되는 명명 제한에 따라 저장되어야 합니다. 이 버전부터 모든 메타데이터 이름은 C# 식별자에 대한 명명 규칙을 준수해야 합니다.

메타데이터 이름-값 쌍이 이러한 명명 제한을 위반하는 경우 응답 본문은 요소 내에서 문제가 있는 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>  
…

응답의 태그

요소는 Tags 매개 변수가 include=tags URI에 지정되고 Blob에 태그가 있는 경우에만 존재합니다. TagSet 요소 내에서 최대 10 Tag 개의 요소가 반환되며, 각 요소는 사용자 정의 Blob 인덱스 태그의 및 value 를 포함합니다key. 태그 순서는 응답에서 보장되지 않습니다.

Tags Blob에 태그가 없으면 및 TagCount 요소가 반환되지 않습니다.

스토리지 서비스는 Blob과 해당 태그 간에 강력한 일관성을 유지하지만 보조 인덱스는 결국 일관성이 있습니다. 태그는 작업에 표시되기 전에 에 대한 응답으로 List Blobs 볼 Find Blobs by Tags 수 있습니다.

응답의 스냅샷

URI에 include=snapshots 매개 변수가 지정된 경우에만 스냅숏이 응답에 나열됩니다. 스냅샷에는 활성 임대가 있을 수 없으므로 응답에 나열된 스냅샷에는 요소가 포함되지 LeaseStatus 않습니다.

서비스 버전 2021-06-08 이상을 사용하여 구분 기호를 사용하여 를 호출 List Blobs 하고 열거형에 스냅샷을 포함할 수 있습니다. 2021-06-08 이전 서비스 버전의 경우 둘 다 포함된 요청은 InvalidQueryParameter 오류(HTTP 상태 코드 400 – 잘못된 요청)를 반환합니다.

응답에서 커밋되지 않은 Blob

URI에 include=uncommittedblobs 매개 변수가 지정된 경우에만 커밋되지 않은 Blob가 응답에 나열됩니다. 응답에 나열된 커밋되지 않은 Blob에는 다음 요소가 포함되지 않습니다.

Last-Modified
Etag
Content-Type
Content-Encoding
Content-Language
Content-MD5
Cache-Control
Metadata

응답에서 삭제된 Blob

삭제된 Blob은 매개 변수가 URI에 지정된 경우에만 include=deleted 응답에 나열됩니다. 삭제된 Blob에는 활성 임대가 있을 수 없으므로 응답에 나열된 삭제된 Blob에는 임대 요소가 포함되지 않습니다.

삭제된 스냅샷은 URI에 지정된 경우 include=deleted,snapshot 목록 응답에 포함됩니다.

응답의 개체 복제 메타데이터

요소는 OrMetadata Blob List Blobs 에서 개체 복제 정책을 평가하고 버전 2019-12-12 이상을 사용하여 호출을 수행한 경우에 존재합니다. OrMetadata 요소 내에서 각 이름-값 쌍의 값은 해당 쌍의 이름에 해당하는 요소 내에 나열됩니다. 이름의 형식은 입니다 or-{policy-id}_{rule-id}. 여기서 {policy-id} 는 스토리지 계정의 개체 복제 정책 식별자를 나타내는 GUID입니다. {rule-id} 는 스토리지 컨테이너의 규칙 식별자를 나타내는 GUID입니다. 유효한 값은 complete 또는 failed입니다.

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

응답의 불변성 정책

ImmutabilityPolicyUntilDate 및 ImmutabilityPolicyMode 요소는 매개 변수가 include=immutabilitypolicy URI에 지정된 경우에만 존재합니다.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

응답의 법적 보류

LegalHold 요소는 include=legalhold 매개 변수가 URI에 지정된 경우에만 제공됩니다.

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

표식 값을 사용하여 결과 집합 반환

매개 변수의 maxresults 값을 지정하고 반환할 Blob 수가 이 값을 초과하거나 의 기본값 maxresults을 초과하는 경우 응답 본문에 요소가 포함됩니다 NextMarker . 이 요소는 후속 요청에서 반환할 다음 Blob을 나타냅니다. 반환되는 결과 수가 값maxresults보다 작더라도 서비스에서 요소를 반환 NextMarker 할 수도 있습니다.

다음 항목 집합을 반환하려면 후속 요청의 URI에서 마커 매개 변수로 NextMarker 값을 지정합니다. NextMarker 값은 불투명으로 처리해야 합니다.

구분 기호를 사용하여 Blob 네임스페이스 트래버스

delimiter 매개 변수는 호출자가 사용자 구성 구분 기호를 사용하여 Blob 네임스페이스를 분리할 수 있도록 합니다. 이렇게 하면 파일 시스템에서와 같이 blob의 가상 계층을 트래버스할 수 있습니다. 이 구분 기호는 단일 문자이거나 문자열일 수 있습니다.

요청에 이 매개 변수가 포함되면 작업이 BlobPrefix 요소를 반환합니다. BlobPrefix 요소는 구분 기호 문자의 모양까지 동일한 부분 문자열로 시작하는 이름의 모든 Blob 대신 반환됩니다. 요소의 BlobPrefix 값은 substring+delimiter입니다. 여기서 부분 문자열 은 하나 이상의 Blob 이름을 시작하는 일반적인 부분 문자열이고 구분 기호 는 매개 변수의 delimiter 값입니다.

값을 BlobPrefix 사용하여 후속 호출을 수행하여 이 접두사로 시작하는 Blob을 나열할 수 있습니다. 요청 URI에서 매개 변수의 BlobPrefixprefix 값을 지정하여 이 작업을 수행합니다.

각 BlobPrefix 요소와 마찬가지로 최대 결과 수까지 각 Blob 요소가 반환됩니다.

Blob는 응답 본문에 대문자부터 시작하는 알파벳 순서로 나열됩니다.

복사 상태 설명의 복사 오류

CopyStatusDescription에는 Copy Blob 오류에 대한 자세한 정보가 포함됩니다.

복사 시도가 실패하면 Blob Storage가 작업을 다시 시도하는 경우 가 로 설정 pending 됩니다CopyStatus. 텍스트는 CopyStatusDescription 마지막 복사 시도 중에 발생할 수 있는 오류를 설명합니다.
CopyStatus가 failed로 설정되면 CopyStatusDescription은 복사 작업이 실패하게 된 오류를 설명합니다.

다음 표에서는 모든 CopyStatusDescription 값의 필드를 설명합니다.

구성 요소	Description
HTTP 상태 코드	오류를 지정하는 표준 3자리 정수입니다.
오류 코드	오류를 설명하는 키워드입니다. Azure에서 ErrorCode> 요소에서 <제공합니다. <ErrorCode> 요소가 나타나지 않으면 서비스는 HTTP 사양의 세 자리 HTTP 상태 코드와 연결된 표준 오류 텍스트가 포함된 키워드(keyword) 반환합니다. 자세한 내용은 일반적인 REST API 오류 코드를 참조하세요.
정보	오류에 대한 자세한 설명(따옴표)입니다.

다음 표에서는 일반적인 오류 시나리오의 CopyStatus 및 CopyStatusDescription 값에 대해 설명합니다.

중요

여기에 표시된 설명 텍스트는 버전 변경 없이도 경고 없이 변경할 수 있습니다. 이 정확한 텍스트를 일치시키는 데 의존하지 마세요.

시나리오	상태 값 복사	복사 상태 설명 값
복사 작업이 성공적으로 완료되었습니다.	성공	비어 있음
사용자가 복사 작업을 완료하기 전에 중단했습니다.	중단됨	비어 있음
복사 작업 중에 원본 Blob에서 읽을 때 오류가 발생했습니다. 작업이 다시 시도됩니다.	보류 중	502 잘못된 게이트웨이 "원본을 읽을 때 다시 시도 가능한 오류가 발생했습니다. 다시 시도합니다. 실패 시간: <시간>"
복사 작업의 대상 Blob에 쓸 때 오류가 발생했습니다. 작업이 다시 시도됩니다.	보류 중	500 InternalServerError "다시 시도 가능한 오류가 발생했습니다. 다시 시도합니다. 실패 시간: <시간>"
복사 작업의 원본 blob에서 읽기를 수행할 때 복구할 수 없는 오류가 발생했습니다.	실패	404 ResourceNotFound "원본을 읽을 때 복사에 실패했습니다." 서비스에서 이 기본 오류를 보고하면 ErrorCode> 요소에서 <반환됩니다`ResourceNotFound`. <응답에 ErrorCode> 요소가 나타나지 않으면 HTTP 상태 표준 문자열 표현(예: `NotFound`)이 나타납니다.
모든 복사 작업을 제한하는 제한 시간이 경과되었습니다. (현재 시간 제한 기간은 2주입니다.)	실패	500 OperationCancelled "복사에 허용된 최대 시간을 초과했습니다."
원본에서 읽을 때 복사 작업이 너무 자주 실패했고 최소한의 성공 시도 비율을 충족하지 않았습니다. (이 시간 제한은 실패하기 전에 2주 동안 매우 가난한 원본을 다시 시도하는 것을 방지합니다).	실패	500 OperationCancelled "원본을 읽을 때 복사가 실패했습니다."

결제

가격 책정 요청은 Blob Storage REST API를 통해 직접 또는 Azure Storage 클라이언트 라이브러리에서 Blob Storage API를 사용하는 클라이언트에서 시작됩니다. 이러한 요청은 트랜잭션당 요금을 발생합니다. 트랜잭션 유형은 계정 청구 방식에 영향을 줍니다. 예를 들어 읽기 트랜잭션은 쓰기 트랜잭션이 아닌 다른 청구 범주에 발생합니다. 다음 표에서는 스토리지 계정 유형에 따라 요청에 대한 List Blobs 청구 범주를 보여 줍니다.

작업	Storage 계정 유형	청구 범주
Blob 나열	프리미엄 블록 Blob 표준 범용 v2 표준 범용 v1	컨테이너 작업 나열 및 만들기

지정된 청구 범주의 가격 책정에 대한 자세한 내용은 가격 책정 Azure Blob Storage 참조하세요.

추가 정보

상태 및 오류 코드
Blob Storage 오류 코드