Cloud Storage용 App Engine 클라이언트 라이브러리의 함수

Cloud Storage용 App Engine 클라이언트 라이브러리는 다음과 같은 함수를 제공합니다.

Functions

  • cloudstorage.copy2()는 지정된 파일을 동일한 Cloud Storage 버킷의 지정된 새 파일 이름에 복사합니다.
  • cloudstorage.delete()는 Cloud Storage 버킷에서 지정된 객체를 삭제합니다.
  • cloudstorage.listbucket()은 Cloud Storage 버킷의 객체를 나열합니다.
  • cloudstorage.open()은 지정된 모드에 따라 읽기 또는 덮어쓰기를 위해 Cloud Storage 버킷에서 기존 객체를 열거나 새 객체를 만듭니다.
  • cloudstorage.stat()은 콘텐츠 유형, 크기, 타임스탬프, MD5 다이제스트, Cloud Storage 헤더 등 파일에 대한 메타데이터 정보를 제공합니다.

cloudstorage.open()을 호출하여 지정된 Cloud Storage 객체를 나타내는 파일과 유사한 객체를 반환하면 write() 및 close()와 같은 표준 Python 파일 함수를 사용하여 Cloud Storage 버킷에 객체를 쓰거나, read()를 사용하여 Cloud Storage 버킷에서 객체를 읽을 수 있습니다.

등급

함수

cloudstorage.copy2(src, dst, metadata=None, retry_params=None)

지정된 파일을 지정된 새 파일 이름으로 복사하며 기본적으로 메타데이터도 복사합니다. 필요한 경우 선택적 metadata 매개변수를 제공하여 복사본의 메타데이터를 덮어쓸 수 있습니다.

지정된 Cloud Storage 객체가 없으면 cloudstorage.NotFoundError가 발생하고 승인을 실패하면 cloudstorage.AuthorizationError가 발생합니다.

인수

src(필수항목)
객체의 전체 Cloud Storage 파일 이름으로 /bucket/object_name 형식입니다. 전체 파일 이름이어야 하며 구분 기호 `/`가 포함될 수 있습니다.
dst(필수항목)
객체 복사본의 전체 Cloud Storage 파일 이름으로, /bucket/object_name 형식입니다. 전체 파일 이름이어야 하며 구분 기호 `/`가 포함될 수 있습니다.
metadata=None(선택사항)
복사본에 대한 메타데이터의 사전(예: {'x-goog-meta-foo': 'bar'})입니다. 메타데이터 매개변수를 제공하면 원본 메타데이터가 새 파일로 복사되지 않습니다. 메타데이터를 제공하지 않으면(None) 모든 소스 파일 메타데이터가 복사됩니다.
retry_params=None(선택사항)
호출의 기본 시간 제한 및 재시도 설정에 적용할 변경사항을 제공하는 RetryParams 객체입니다.

예

파일을 복사하면서 새 메타데이터를 추가하고 소스 파일이 없을 때 발생하는 오류를 무시하려면 다음을 사용하세요.
import cloudstorage

try:
  cloudstorage.copy2('/my_bucket/README', '/my_bucket/README2', metadata={'x-goog-meta-zzzzz': 'zzzzz'})
except cloudstorage.NotFoundError:
  pass

맨 위로


cloudstorage.delete(filename, retry_params=None)

Cloud Storage 버킷에서 지정된 파일을 삭제합니다.

지정된 Cloud Storage 객체가 없으면 cloudstorage.NotFoundError가 발생합니다.

인수

filename (필수항목)
객체의 전체 Cloud Storage 파일 이름으로 /bucket/object_name 형식입니다. 전체 파일 이름이어야 하며 구분 기호 `/`가 포함될 수 있습니다.
retry_params=None(선택사항)
호출의 기본 시간 제한 및 재시도 설정에 적용할 변경사항을 제공하는 RetryParams 객체입니다.

예

파일을 삭제하지만 파일이 없을 때 오류를 무시하려면 다음을 사용하세요.
import cloudstorage

try:
  cloudstorage.delete(filename)
except cloudstorage.NotFoundError:
  pass

맨 위로


cloudstorage.listbucket(path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
버킷 반복자 객체를 반환합니다. 반복자는 모든 필터와 일치하는 정렬된 객체 목록을 반환합니다. 함수는 비동기식이며 반복자가 결과를 확인하기 전에 호출되지 않으면 차단하지 않습니다.

함수는 delimiter 인수 사용 여부에 따라 두 가지 모드에서 작동합니다.

  • 일반 모드(기본값): 계층 구조의 개념 없이 버킷의 모든 파일을 나열합니다. Cloud Storage에는 실제 디렉토리 계층 구조가 없습니다.
  • 디렉터리 에뮬레이션 모드: delimiter 인수를 지정하면 경로 구분자로 사용되어 디렉터리 계층 구조를 에뮬레이션합니다.

인수

path_prefix(필수항목)
/bucket 또는 /bucket/prefix 형식의 Cloud Storage 경로(예: /bucket/foo/2001)입니다. 전체 경로가 path_prefix로 시작되는 객체만 반환됩니다.
marker=None(선택사항)
문자열이며, 또 다른 경로 프리픽스입니다. 전체 경로가 마커 이후 사전순으로 시작되는 객체만 반환됩니다. '마커'로 사용되는 파일은 반환되지 않습니다. 예를 들어 superduperfoo3.txt에서 시작하는 모든 파일을 나열하려면 superduperfoo3.txt 바로 앞의 파일을 지정합니다. 예를 들면 다음과 같습니다. 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
매개변수를 사용하는 한 가지 방법은 max_keys와 함께 사용하여 버킷 파일 이름을 '훑어보는' 것입니다.
max_keys=None(선택사항)
정수이며, 반환할 객체의 최대 수를 지정합니다. 원하는 객체 수가 있을 때 사용합니다. 그렇지 않으면 Cloud Storage 클라이언트 라이브러리가 모든 결과를 자동으로 버퍼링하고 페이지로 나눕니다. marker와 함께 사용하여 버킷의 파일 이름을 훑어볼 수 있습니다. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter=None(선택사항)
문자열이며, 디렉토리 모드를 사용 설정합니다. 디렉토리 구분자로 사용할 문자를 하나 또는 여러 개 지정할 수 있습니다.
retry_params=None(선택사항)
호출의 기본 시간 제한 및 재시도 설정에 적용할 변경사항을 제공하는 RetryParams 객체입니다.

결과 값

일치하는 파일에 대해 파일 이름 기준으로 정렬된 GCSFileStat 객체의 반복자를 반환합니다. 일반 모드에서 반환된 GCSFileStat 객체의 데이터는 다음과 같습니다.

  • filename
  • etag(파일 콘텐츠의 MD5 해시에 대한 16진수 표현)
  • st_size(헤더의 콘텐츠 길이)
  • st_ctime
  • is_dir

참고: GCSFileStat 객체의 is_dir 속성이 True이면 객체에서 유일하게 다른 속성은 filename입니다. is_dir가 False이면 GCSFileStat에 다른 모든 속성도 포함됩니다.

맨 위로


cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

읽기 모드(r)에서는 읽기에 지정된 Cloud Storage 객체를 엽니다. 쓰기 모드 w에서는 지정된 파일이 있으면 덮어쓰기에 이 파일을 엽니다(추가는 지원되지 않음). 파일이 없으면 지정된 버킷에 파일이 생성됩니다.

쓰기를 마친 경우 파일을 읽거나 Cloud Storage에 저장하려면 close 함수를 사용하여 파일을 닫습니다. close를 호출하지 않으면 오류는 아니지만 파일을 Cloud Storage에서 읽거나 지속할 수 없습니다.

발생 오류:

인수

filename (필수항목)
열려는 파일이며 /bucket/object 형식입니다. 예를 들면 /my_bucket/lyrics/southamerica/list5.txt입니다.
mode (선택사항)
문자열이며, 읽을 파일을 열려면 'r'을 지정합니다(기본값). 덮어쓸 기존 파일을 열거나 새 파일을 만들려면 'w'를 지정합니다.

content_type: (선택사항)
문자열이며, 쓰기 모드에서만 사용됩니다. 파일의 MIME 유형을 지정해야 합니다(유효한 MIME 유형을 지정할 수 있음). 값을 제공하지 않으면 Cloud Storage는 객체를 제공할 때 binary/octet-stream 유형을 기본값으로 설정합니다.
options: (선택사항)

사전이며 쓰기 모드에서만 사용됩니다. 지원되는 옵션은 x-goog-acl, x-goog-meta-, cache-control, content-disposition, content-encoding입니다.

x-goog-acl 옵션을 제공하지 않으면 Cloud Storage는 버킷의 기본 ACL을 사용합니다. x-goog-acl의 유효한 값은 x-goog-acl에 대한 Cloud Storage 문서에 나와 있습니다.

x-goog-meta- 헤더를 사용하여 맞춤 객체 메타데이터를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})
read_buffer_size: (선택사항)
정수이며, 읽기 모드에서만 사용됩니다. 값을 설정하지 않으면 기본 버퍼 크기가 사용됩니다(권장). 읽을 때 미리 가져오기 성능을 최적화하기 위해 read_buffer_size를 기준으로 읽어야 합니다.
retry_params=None(선택사항)
호출의 기본 시간 제한 및 재시도 설정에 적용할 변경사항을 제공하는 RetryParams 객체입니다.

결과값

표준 Python read, write, close 함수를 호출할 수 있는 파일과 유사한 인터페이스를 지원하는 읽기 또는 쓰기 버퍼를 반환합니다. 읽기 또는 쓰기가 끝나면 버퍼를 닫아야 합니다.

맨 위로


cloudstorage.stat(filename, retry_params=None)

파일 메타데이터가 포함된 GCSFileStat 객체를 반환합니다.

지정된 Cloud Storage 객체가 없으면 cloudstorage.NotFoundError가 발생합니다.

인수

filename (필수항목)
열려는 파일이며 /bucket/object 형식입니다. 예를 들면 /my_bucket/lyrics/southamerica/list5.txt입니다.
retry_params=None(선택사항)
호출의 기본 시간 제한 및 재시도 설정에 적용할 변경사항을 제공하는 RetryParams 객체입니다.

결과 값

파일 메타데이터가 포함된 GCSFileStat 객체를 반환합니다.

맨 위로