이 페이지에서는 버킷의 스토리지 레이아웃을 확인하는 방법을 설명합니다. 스토리지 레이아웃은 객체가 버킷 내에서 플랫 네임스페이스 또는 계층적 네임스페이스로 구성되는 방식을 나타냅니다. 객체 액세스 및 조작 메서드는 레이아웃에 따라 다르므로 버킷과 상호작용하는 애플리케이션에는 레이아웃이 중요합니다. 스토리지 레이아웃에는 버킷 위치에 관한 정보도 포함됩니다.
getStorageLayout API를 사용하면 애플리케이션이 버킷이 계층적 네임스페이스를 사용하는지 여부에 따라 동작을 조정할 수 있어, 버킷 구성에 따라 적절한 기능을 활용하고 최적의 호환성을 보장할 수 있습니다.
필수 역할
Cloud Storage 버킷의 스토리지 레이아웃를 가져오는 데 필요한 권한을 얻으려면 관리자에게 버킷에 대한 스토리지 객체 사용자(roles/storage.objectUser) 역할을 부여해 달라고 요청하세요.
이 역할에는 버킷의 스토리지 레이아웃을 가져오는 데 필요한 storage.objects.list 권한이 포함되어 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[],[],null,["# Get a bucket's storage layout\n\n| **Preview**\n|\n|\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis page describes how to determine the storage layout of your bucket. Storage\nlayout refers to how objects are organized within a bucket, either in a flat\nnamespace or a [hierarchical namespace](/storage/docs/hns-overview). The layout is important for\napplications that interact with the bucket, as object access and manipulation\nmethods vary depending on the layout. Storage layout also includes information\nabout the bucket's location.\n\nBy using the [`getStorageLayout`](/storage/docs/json_api/v1/buckets/getStorageLayout) API, your application can adapt its\nbehavior based on whether a bucket uses hierarchical namespace or not, ensuring\noptimal compatibility and leveraging the appropriate features based on the\nbucket configuration.\n\n#### Roles required\n\nIn order to get the required permissions for getting the storage layout of a Cloud Storage bucket , ask your administrator to grant you the Storage Object User (`roles/storage.objectUser`) role on the bucket.\n\nThe role contains the `storage.objects.list` permission, which is\nrequired to get the storage layout of the bucket.\n\nYou might also be able to get this permission with other [custom roles](/iam/docs/creating-custom-roles) or\n[predefined roles](/iam/docs/understanding-roles#predefined). To see which roles are associated with which permissions, refer to [IAM roles for Cloud Storage.](/storage/docs/access-control/iam-roles)\n\nFor instructions on granting roles on buckets, see [Use IAM with buckets.](/storage/docs/access-control/using-iam-permissions)\n\nGet a bucket's storage layout\n-----------------------------\n\n### Command line\n\nUse the [`gcloud alpha storage buckets describe`](/sdk/gcloud/reference/alpha/storage/buckets/describe) command with the `--format` flag: \n\n```\ngcloud alpha storage buckets describe gs://BUCKET_NAME --raw --format=\"default(hierarchicalNamespace)\"\n```\n\nWhere:\n\n- \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e is the name of the relevant bucket. For example, `my-bucket`.\n\nIf successful and hierarchical namespace is enabled, the response looks\nsimilar to the following example: \n\n```\n hierarchicalNamespace:\n enabled: true\n```\n\n### JSON API\n\n1. Have gcloud CLI [installed and initialized](/sdk/docs/install), which lets\n you generate an access token for the `Authorization` header.\n\n\n2.\n\n Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](/storage/docs/json_api)\n with a [`getStorageLayout`](/storage/docs/json_api/v1/buckets/getStorageLayout) request: \n\n ```\n curl -X GET \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/storageLayout\"\n ```\n\n Where \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e is the name of the\n relevant bucket. For example, `my-bucket`.\n\n If successful, the response looks like the following example:\n\n \u003cbr /\u003e\n\n ```json\n {\n \"kind\": \"storage#storageLayout\",\n \"bucket\": \"my-bucket\",\n \"location\": \"us-central1\",\n \"locationType\": \"region\",\n \"hierarchicalNamespace\":{enabled: true},\n }\n ```\n\n \u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Understand folders](/storage/docs/folders-overview).\n- [Create and manage folders](/storage/docs/create-folders).\n- [Rename folders](/storage/docs/rename-hns-folders).\n\nTry it for yourself\n-------------------\n\n\nIf you're new to Google Cloud, create an account to evaluate how\nCloud Storage performs in real-world\nscenarios. New customers also get $300 in free credits to run, test, and\ndeploy workloads.\n[Try Cloud Storage free](https://console.cloud.google.com/freetrial)"]]
