Cloud Storage를 사용하면 애플리케이션으로 동영상 또는 이미지 파일과 같은 큰 데이터 객체를 제공하고 사용자가 큰 데이터 파일을 업로드할 수 있습니다. Python 2 런타임에서 App Engine은 Cloud Storage에서 객체를 쓰고 읽기 위한 고유 클라이언트 라이브러리를 제공합니다. 이 App Engine 라이브러리는 Python 3 런타임을 포함한 새로운 App Engine 런타임에서 사용할 수 없습니다.
Python 2 앱에서 GoogleAppEngineCloudStorageClient 라이브러리를 사용하는 경우 Python 3 런타임에서 앱을 실행하기 전에 Cloud Storage용 Cloud 클라이언트 라이브러리로 마이그레이션해야 합니다. 새 클라이언트 라이브러리를 사용하려면 앱만 마이그레이션하면 됩니다. 기존 Cloud Storage 버킷의 모든 데이터 객체와 권한은 변경되지 않으며 새 클라이언트 라이브러리를 사용하여 기존 버킷에 액세스할 수 있습니다.
App Engine과 Cloud 클라이언트 라이브러리 비교
유사점:
Cloud 클라이언트 라이브러리는 App Engine 클라이언트 라이브러리에서 사용 설정한 객체 읽기, 쓰기, 삭제, 나열 등의 모든 Cloud Storage 기능을 지원합니다. 마이그레이션할 때 코드를 약간만 변경하면 됩니다.
Cloud 클라이언트 라이브러리는 또한 버킷 만들기 및 라벨링과 객체의 이전 버전 검색과 같은 추가 기능을 지원합니다.
차이점:
App Engine 라이브러리에서 객체 목록을 검색하는 함수는 비동기식으로 작동합니다.
Cloud 클라이언트 라이브러리는 객체 나열을 위한 비동기 함수를 제공하지 않지만 페이징을 사용하고 작은 객체 집합을 통해 반복할 수 있습니다.
App Engine 클라이언트 라이브러리는 액세스 제어 목록(ACL)을 사용하여 버킷 및 객체에 대한 액세스를 제어해야 합니다.
하지만 Cloud Storage와 Cloud 클라이언트 라이브러리는 사용자에게 버킷과 객체에 대한 액세스 권한을 부여하는 두 가지 시스템인 ACL과 균일한 버킷 수준 액세스를 지원합니다. 균일한 버킷 수준 액세스는 모든 클라우드 리소스에서 더 단순하고 일관된 액세스 제어 환경을 제공합니다.
Cloud 클라이언트 라이브러리로 마이그레이션한 후 App Engine 클라이언트 라이브러리에서 사용한 모든 ACL이 기존 버킷에 계속 적용되며 필요한 경우 ACL을 계속 사용할 수 있습니다.
균일한 버킷 수준 액세스가 필요에 맞는 경우 새로 만드는 모든 버킷에 이 간단한 시스템을 사용하는 것이 좋습니다. 기존 버킷을 변환하면 동일한 버킷 수준 액세스를 사용할 수 있지만 앱에서 스토리지 객체에 대한 액세스를 보호하는 방법을 대폭 변경해야 할 수 있습니다.
일부 클라이언트 라이브러리는 SSL 라이브러리가 필요하지 않습니다. 필요한 클라이언트 라이브러리의 SSL 라이브러리를 포함하지 않은 경우 앱에서 요청을 수신하면 로그 탐색기에 SSL 오류가 표시됩니다.
Cloud Storage용 Cloud 클라이언트 라이브러리를 종속 항목 목록에 추가하여 requirements.txt 파일을 업데이트합니다.
google-cloud-storage==1.24.1
Python 2.7 앱을 지원하므로 Cloud Storage 클라이언트 라이브러리의 1.24.1 버전을 사용하는 것이 좋습니다.
그런 다음 pip install -t lib -r requirements.txt를 실행하여 앱에 사용 가능한 라이브러리 목록을 업데이트합니다.
Python 2 앱의 경우 앱에서 기본 제공 또는 복사된 라이브러리를 사용한다면 appengine_config.py 파일에 해당 경로를 지정해야 합니다.
importpkg_resourcesfromgoogle.appengine.extimportvendor# Set PATH to your libraries folder.PATH='lib'# Add libraries installed in the PATH folder.vendor.add(PATH)# Add libraries to pkg_resources working set to find the distribution.pkg_resources.working_set.add_entry(PATH)
앞의 예시의 appengine_config.py 파일은 lib 폴더가 현재 작업 디렉터리에 있다고 가정합니다. lib가 항상 현재 작업 디렉터리에 있다고 보장할 수 없으면 lib 폴더에 전체 경로를 지정합니다. 예를 들면 다음과 같습니다.
이전에 설명한 기본 승인 시나리오에서 Cloud Storage 클라이언트는 프로젝트의 버킷 및 객체와 상호작용하도록 승인된 App Engine의 기본 서비스 계정에서 가져온 사용자 인증 정보를 포함합니다. 이 기본 시나리오에서 작업하지 않는 경우 사용자 인증 정보를 제공하는 방법에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보(ADC)를 참조하세요.
Cloud 클라이언트 라이브러리 메서드 사용
다음 표에는 특정 Cloud Storage 기능을 구현할 때 사용할 Cloud 클라이언트 라이브러리의 메서드가 요약되어 있습니다.
[[["이해하기 쉬움","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-04(UTC)"],[[["\u003cp\u003eThe App Engine client library for Cloud Storage in Python 2 is not available in newer runtimes like Python 3, necessitating a migration to the Cloud Client Library for Cloud Storage.\u003c/p\u003e\n"],["\u003cp\u003eMigrating to the Cloud Client Library does not change existing data objects or permissions in Cloud Storage buckets, as the new library can access existing buckets seamlessly.\u003c/p\u003e\n"],["\u003cp\u003eWhile the Cloud Client Library supports all core functionalities of the App Engine library, it also introduces new features like bucket labeling and retrieving older object versions, but listing objects is no longer asynchronous.\u003c/p\u003e\n"],["\u003cp\u003eAccess control in Cloud Storage can be managed through ACLs (as with the App Engine library) or the recommended uniform bucket-level access, although switching existing buckets to the latter might require significant changes.\u003c/p\u003e\n"],["\u003cp\u003eTo migrate, developers must install the Cloud Client Library, update their code to use the new library's methods, test the changes, and then deploy the updated application, including adding necessary libraries to \u003ccode\u003eapp.yaml\u003c/code\u003e and \u003ccode\u003erequirements.txt\u003c/code\u003e files.\u003c/p\u003e\n"]]],[],null,["# Migrating to the Cloud Client Library for Storage\n\n[Cloud Storage](/storage/docs) enables\nyour application to serve large data objects such as video or image files, and\nenables your users to upload large data files. In the Python 2 runtime,\nApp Engine provides its own client library for writing and reading\nobjects in Cloud Storage. This App Engine library is not available\nin newer App Engine runtimes, including the Python 3 runtime.\n\nIf your Python 2 app uses the `GoogleAppEngineCloudStorageClient` library, you\nneed to migrate to the Cloud Client Library for Cloud Storage before you can\nrun the app in the Python 3 runtime. Note that you only need to migrate your\napp to use a new client library. **All of the data objects and permissions in\nyour existing Cloud Storage buckets remain unchanged, and you can access\nyour existing buckets using the new client library**.\n\nComparison of the App Engine and Cloud Client Libraries\n-------------------------------------------------------\n\nSimilarities:\n\n- The Cloud Client Library supports all of the Cloud Storage features enabled\n by the App Engine client library, such as reading, writing, removing,\n and listing objects. Migration should require only small changes\n to your code.\n\n The Cloud Client Library also supports additional features,\n such as creating and [labeling](/storage/docs/using-bucket-labels) buckets, and [retrieving older versions\n of objects](/storage/docs/object-versioning).\n\nDifferences:\n\n- In the App Engine library, the function that retrieves a list of\n objects works [asynchronously](/appengine/docs/legacy/standard/python/googlecloudstorageclient/functions#listbucket).\n The Cloud Client Library doesn't provide an asynchronous function for listing\n objects, though you can use paging and iterate through a small set of objects.\n\n- The App Engine client library requires you to use\n access control lists (ACL) to control access to buckets and objects.\n However, Cloud Storage and the Cloud Client Library support two systems\n for granting users permission to access your buckets and objects: ACLs\n and [uniform bucket-level access](/storage/docs/uniform-bucket-level-access). Uniform bucket-level access provides a\n simpler, consistent access control experience across all of your Cloud resources.\n\n All ACLs that you used with the App Engine client library remain in\n effect for your existing buckets after you migrate to the Cloud Client Library,\n and you can continue to use ACLs if needed.\n\n If uniform bucket-level access meets your needs, we recommend you use this\n simpler system for any new buckets you create. While you can convert existing\n buckets to use uniform bucket-level access, this may require significant\n changes to how your app secures access to its storage objects.\n\nCode samples:\n\n- Basic storage operations\n [using the App Engine APIs](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/appengine/standard/storage/appengine-client/main.py)\n\n- Basic storage operations\n [using the Cloud client library for Cloud Storage](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/appengine/standard/migration/storage/main.py)\n\nBefore you start migrating\n--------------------------\n\nIf you have not done so already, set up your\n[Python development environment](/python/docs/setup) to use a Python version\nthat is compatible with Google Cloud, and install testing tools for creating\nisolated Python environments.\n\n### Understanding Cloud Storage permissions\n\nBy default, your app's [auto-created default service account](/iam/docs/service-accounts#default)\nhas read and write privileges to the buckets in your project, and it has\nfull rights to the objects it creates, both before and after migration.\n\nIf you used a different service account or user account to secure access to\nyour Cloud Storage buckets and objects, be sure you continue to use the\nsame accounts and [authentication techniques](/docs/authentication#service-accounts) before and after migration.\n\nOverview of the migration process\n---------------------------------\n\nTo migrate your Python app to use the Cloud Client Library for Cloud Storage\ninstead of the App Engine client library:\n\n1. [Install](#install) the Cloud Client Library for Cloud Storage.\n\n2. [Update](#update) your code to use the Cloud Client Library.\n\n3. [Test](#testing) your updates.\n\n4. [Deploy](#deploying) your app to App Engine.\n\nInstalling the Cloud Client Library for Cloud Storage\n-----------------------------------------------------\n\nTo make the Cloud Client Library for Cloud Storage available to your app\nwhen it runs in App Engine:\n\n1. Update the `app.yaml` file:\n\n 1. If you use Cloud Client Libraries, add the latest versions of `grpcio` and `setuptools` libraries.\n 2. Add the `ssl` library since this is required by Cloud Storage.\n\n The following is an example `app.yaml` file: \n\n runtime: python27\n threadsafe: yes\n api_version: 1\n\n libraries:\n - name: grpcio\n version: 1.0.0\n - name: setuptools\n version: 36.6.0\n - name: ssl\n version: latest\n\n Some client libraries don't need the SSL library. If you don't include the\n SSL library for a client library that needs it, you'll see an SSL error\n in the Logs Explorer when your app receives a request.\n2. Update the `requirements.txt` file by adding the Cloud Client Libraries\n for Cloud Storage to your list of dependencies:\n\n google-cloud-storage==1.24.1\n\n We recommend you use the 1.24.1 version of the Cloud Storage client\n library since it supports Python 2.7 apps.\n\n Then run `pip install -t lib -r requirements.txt` to update the list of\n available libraries for your app.\n3. For Python 2 apps, if your app is using built-in or copied libraries, you\n must specify those paths in the `appengine_config.py` file:\n\n import pkg_resources\n from google.appengine.ext import vendor\n\n # Set PATH to your libraries folder.\n PATH = 'lib'\n # Add libraries installed in the PATH folder.\n vendor.add(PATH)\n # Add libraries to pkg_resources working set to find the distribution.\n pkg_resources.working_set.add_entry(PATH)\n\n The `appengine_config.py` file in the preceding example assumes that the\n the `lib` folder is located in the current working directory. If you can't\n guarantee that `lib` will always be in the current working directory,\n specify the full path to the `lib` folder. For example: \n\n ```python\n import os\n path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')\n ```\n\nUpdating your code to use the Cloud Client Library\n--------------------------------------------------\n\n### Creating a Cloud Storage Client\n\nTo use the Cloud Client Library for Cloud Storage, create a [`Client`\nobject](/python/docs/reference/storage/latest/google.cloud.storage.client.Client). The client contains credentials and other\ndata needed to connect to Cloud Storage. For example: \n\n from google.cloud import https://cloud.google.com/python/docs/reference/storage/latest/\n\n client = https://cloud.google.com/python/docs/reference/storage/latest/.https://cloud.google.com/python/docs/reference/storage/latest/google.cloud.storage.client.Client.html()\n\nIn the [default authorization scenario described previously](#authorization),\nthe Cloud Storage client contains credentials from App Engine's\ndefault service account, which is authorized to interact with your project's\nbuckets and objects. If you aren't working in this default scenario, see\n[Application Default Credentials (ADC)](/docs/authentication/application-default-credentials)\nfor information on how to provide credentials.\n\n### Using Cloud Client Library methods\n\nThe following table summarizes which methods from the Cloud Client Library\nto use when implementing specific Cloud Storage features.\n| **Note:** See the [list of code samples](https://github.com/GoogleCloudPlatform/python-docs-samples/tree/master/storage/cloud-client) and the [reference documentation](/python/docs/reference/storage/latest/google.cloud.storage.client.Client) for the Cloud Client Library.\n\nTesting your updates\n--------------------\n\nYou can test your updates to your app in a local environment, but all\nCloud Storage requests must be sent over the internet to an actual\nCloud Storage bucket. Neither App Engine nor Cloud Storage\nprovides a Cloud Storage emulator.\n\nFor more information about testing Python 2 apps, see [Using the local\ndevelopment server](/appengine/docs/legacy/standard/python/tools/using-local-server).\n\nFor more information about testing Python 3 apps, see [Testing and deploying\nyour application](/appengine/docs/standard/testing-and-deploying-your-app).\n\nDeploying your app\n------------------\n\nOnce you are ready to deploy your app, you should:\n\n1. [Test the app on\n App Engine](/appengine/docs/standard/testing-and-deploying-your-app#testing-on-app-engine).\n\n2. If the app runs without errors, [use traffic\n splitting](/appengine/docs/standard/splitting-traffic) to slowly\n ramp up traffic for your updated app. Monitor the app closely for any\n issues before routing more traffic to the updated app."]]
