Blob 나열

아티클
06/27/2024

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에 다음 추가 매개 변수를 지정할 수 있습니다.

매개 변수	묘사
`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`지정한 것보다 적은 결과를 반환하고 연속 토큰도 반환할 수 있습니다. `maxresults` 0보다 작거나 같은 값으로 설정하면 오류 응답 코드 400(잘못된 요청)이 발생합니다.
`include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,` `deletedwithversions,immutabilitypolicy,legalhold,permissions}`	선택적. 응답에 포함할 하나 이상의 데이터 세트를 지정합니다. - `snapshots`: 스냅샷을 열거형에 포함되도록 지정합니다. 스냅샷은 응답에서 가장 오래된 스냅샷에서 최신 항목으로 나열됩니다. - `metadata`: 응답에서 Blob 메타데이터가 반환되도록 지정합니다. : 블록이 업로드되었지만 블록 목록사용하여 커밋되지 않은 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만 포함됩니다. POSIX ACL 권한 부여 대체는 일시 삭제된 Blob을 나열하는 데 지원되지 않습니다. `include=deleted` 지정되면 잘못된 요청(400)으로 요청이 실패합니다. - `files`: 선택 사항입니다. 버전 2020-12-06 이상. 계층 구조 네임스페이스에서 사용하도록 설정된 계정에만 해당합니다. 요청에 이 매개 변수가 포함된 경우 목록에는 파일만 포함됩니다. - `directories`: 선택 사항입니다. 버전 2020-12-06 이상. 계층 구조 네임스페이스에서 사용하도록 설정된 계정에만 해당합니다. 요청에 이 매개 변수가 포함된 경우 목록에는 디렉터리만 포함됩니다.
`timeout`	선택적. `timeout` 매개 변수는 초 단위로 표현됩니다. 자세한 내용은 Blob Storage 작업대한 시간 제한 설정을 참조하세요.

요청 헤더

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

요청 헤더	묘사
`Authorization`	필수. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage대한 요청 권한 부여를 참조하세요.
`Date` 또는 `x-ms-date`	필수. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage대한 요청 권한 부여를 참조하세요.
`x-ms-version`	모든 권한 있는 요청에 필요하고 익명 요청에는 선택 사항입니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스대한 버전 관리를 참조하세요.
`x-ms-client-request-id`	선택적. 로깅이 구성될 때 로그에 기록되는 1kibibyte(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 프로토콜 사양준수합니다.

응답 헤더	묘사
`Content-Type`	결과가 반환되는 형식을 지정합니다. 현재 이 값은 `application/xml`.
`x-ms-request-id`	이 헤더는 만들어진 요청을 고유하게 식별하며 요청 문제를 해결하는 데 사용할 수 있습니다. 자세한 내용은 API 작업문제 해결을 참조하세요.
`x-ms-version`	요청을 실행하는 데 사용되는 Blob Storage의 버전을 나타냅니다. 이 헤더는 버전 2009-09-19 이상을 사용하여 수행한 요청에 대해 반환됩니다. 컨테이너가 Blob Storage의 2009-09-19 버전을 사용하여 공용 액세스용으로 표시된 경우 이 헤더는 지정된 버전 없이 익명 요청에 대해서도 반환됩니다.
`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은 요청 URI의 include 매개 변수로 지정된 경우에만 응답에 포함됩니다.

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

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

LeaseState 및 LeaseDuration 버전 2012-02-12 이상에만 나타납니다.

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

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

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

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

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

버전 2017-04-17 이상에서는 액세스 계층이 명시적으로 설정된 경우 List BlobsAccessTier 요소를 반환합니다. 허용되는 프리미엄 페이지 Blob 계층 목록은 VM대한 고성능 Premium Storage 및 관리 디스크를 참조하세요. Blob Storage 또는 범용 v2 계정의 경우 유효한 값은 Hot, Cool및 Archive. 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 이상에서는 이 작업에 include={deleted} 매개 변수가 포함되면 Deleted, DeletedTime및 RemainingRetentionDays 표시됩니다. 이 Blob이 삭제되지 않은 경우 이러한 요소는 표시되지 않습니다. 이러한 요소는 일시 삭제 기능을 사용하도록 설정한 경우 DELETE 작업으로 삭제된 Blob 또는 스냅샷에 대해 나타납니다. Deleted 요소는 일시 삭제된 Blob 및 스냅샷에 대해 true 설정됩니다. Deleted-Time Blob이 삭제된 시간에 해당합니다. RemainingRetentionDays 일시 삭제된 Blob이 영구적으로 삭제된 후의 일 수를 나타냅니다.

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

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

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

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

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

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

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

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

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

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

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

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

버전 2020-06-12 이상에서는 계층 구조 네임스페이스가 활성화된 계정의 경우 구분 기호가 있는 List BlobsBlobPrefix 요소의 Properties 요소를 반환합니다. 디렉터리의 속성에 해당합니다.

버전 2020-08-04 이상에서는 계층 구조 네임스페이스가 설정된 계정의 경우 List Blobs 삭제된 Blob에 대한 DeletionId 요소를 반환합니다. 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 BlobsPlaceholder 속성 요소를 반환합니다. 삭제된 Blob을 구분 기호로 나열할 때 자리 표시자 디렉터리에 대한 BlobPrefix 요소에서 이 요소를 반환합니다. 일시 삭제된 Blob에 대한 탐색을 용이하게 하기 위해 이러한 자리 표시자 디렉터리도 존재합니다.

버전 2021-06-08 이상에서는 계층 구조 네임스페이스가 설정된 계정의 경우 List BlobsEncryptionContext 요소를 반환합니다. 암호화 컨텍스트 속성 값이 설정되면 집합 값이 반환됩니다.

버전 2020-02-10 이상에서는 계층 구조 네임스페이스가 활성화된 계정의 경우 List Blobs 삭제된 Blob에 대한 Expiry-Time 요소를 반환합니다. 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 작업에 권한을 부여할 수 있습니다.

중요하다

Microsoft는 관리 ID와 함께 Microsoft Entra ID를 사용하여 Azure Storage에 대한 요청을 승인하는 것이 좋습니다. Microsoft Entra ID는 공유 키 권한 부여에 비해 뛰어난 보안 및 사용 편의성을 제공합니다.

microsoft Entra ID(권장)
SAS(공유 액세스 서명)
공유 키

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

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

권한을

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

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

include=tags지정하는 경우:

azure RBAC 작업 : microsoft.Storage/storageAccounts/blobServices/containers/blob/tags/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에 대해 지정된 권한으로 보호됩니다.

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

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

서비스 SAS

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

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

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

계정 SAS

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

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

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

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

발언

응답의 Blob 속성

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

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

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

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

Content-MD5 요소는 버전 2009-09-19 이상을 사용하여 Blob에 설정된 경우에만 응답 본문에 표시됩니다. Blob을 만들 때 또는 Blob 속성 설정호출하여 Content-MD5 속성을 설정할 수 있습니다. 버전 2012-02-12 이상에서는 Put BlobPut Blob 요청에 MD5 헤더가 포함되지 않은 경우에도 블록 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 요소 내에서 사용자 정의 Blob 인덱스 태그의 key 및 value 포함하는 최대 10개의 Tag 요소가 반환됩니다. 태그 순서는 응답에서 보장되지 않습니다.

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

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

응답의 스냅샷

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

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

응답에서 커밋되지 않은 Blob

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

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

응답에서 삭제된 Blob

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

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

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

OrMetadata 요소는 Blob에서 개체 복제 정책을 평가하고 버전 2019-12-12 이상을 사용하여 List Blobs 호출한 경우에 존재합니다. 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 요소를 반환할 수 있습니다.

다음 항목 집합을 반환하려면 NextMarker 값을 후속 요청에 대한 URI의 표식 매개 변수로 지정합니다. NextMarker 값은 불투명한 것으로 처리되어야 합니다.

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

delimiter 매개 변수를 사용하면 호출자가 사용자가 구성한 구분 기호를 사용하여 Blob 네임스페이스를 트래버스할 수 있습니다. 이러한 방식으로 파일 시스템인 것처럼 Blob의 가상 계층 구조를 트래버스할 수 있습니다. 구분 기호는 단일 문자 또는 문자열일 수 있습니다.

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

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

반환된 각 BlobPrefix 요소는 각 Blob 요소와 마찬가지로 최대 결과에 대한 개수를 계산합니다.

Blob은 응답 본문에 사전순으로 나열되고 대문자가 먼저 나열됩니다.

복사 상태 설명의 복사 오류

CopyStatusDescription Copy Blob 오류에 대한 자세한 정보를 포함합니다.

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

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

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

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