0
# Google Cloud Storage
1
2
Google Cloud Storage is an object storage service for storing and retrieving files of any size. It provides durable, secure, and scalable storage with global accessibility and rich metadata support.
3
4
## Capabilities
5
6
### Client Operations
7
8
High-level client for managing Google Cloud Storage operations including bucket management and configuration.
9
10
```python { .api }
11
class Client:
12
def __init__(self, project=None, credentials=None, http=None):
13
"""
14
Initialize Storage client.
15
16
Parameters:
17
- project (str): Google Cloud project ID
18
- credentials: OAuth2 credentials object
19
- http: Optional HTTP client
20
"""
21
22
def get_bucket(self, bucket_name):
23
"""
24
Get bucket instance, raises NotFound if doesn't exist.
25
26
Parameters:
27
- bucket_name (str): Name of bucket
28
29
Returns:
30
Bucket: Bucket instance
31
32
Raises:
33
NotFound: If bucket doesn't exist
34
"""
35
36
def lookup_bucket(self, bucket_name):
37
"""
38
Get bucket instance, returns None if doesn't exist.
39
40
Parameters:
41
- bucket_name (str): Name of bucket
42
43
Returns:
44
Bucket or None: Bucket instance or None
45
"""
46
47
def create_bucket(self, bucket_name):
48
"""
49
Create new bucket.
50
51
Parameters:
52
- bucket_name (str): Name for new bucket
53
54
Returns:
55
Bucket: Created bucket instance
56
"""
57
58
def list_buckets(self, max_results=None, page_token=None, prefix=None,
59
projection='noAcl', fields=None):
60
"""
61
List buckets in project.
62
63
Parameters:
64
- max_results (int): Maximum results per page
65
- page_token (str): Pagination token
66
- prefix (str): Filter by name prefix
67
- projection (str): Projection type ('full', 'noAcl')
68
- fields (str): Fields to return
69
70
Returns:
71
Iterator: Bucket listing iterator
72
"""
73
```
74
75
### Bucket Operations
76
77
Bucket management including blob operations, access control, and configuration settings.
78
79
```python { .api }
80
class Bucket:
81
def __init__(self, client, name=None):
82
"""
83
Initialize bucket.
84
85
Parameters:
86
- client (Client): Storage client
87
- name (str): Bucket name
88
"""
89
90
def exists(self, client=None):
91
"""
92
Check if bucket exists.
93
94
Parameters:
95
- client (Client): Optional client override
96
97
Returns:
98
bool: True if bucket exists
99
"""
100
101
def create(self, client=None):
102
"""
103
Create bucket.
104
105
Parameters:
106
- client (Client): Optional client override
107
"""
108
109
def delete(self, force=False, client=None):
110
"""
111
Delete bucket.
112
113
Parameters:
114
- force (bool): Delete even if bucket contains objects
115
- client (Client): Optional client override
116
"""
117
118
def get_blob(self, blob_name, client=None):
119
"""
120
Get blob instance.
121
122
Parameters:
123
- blob_name (str): Name of blob
124
- client (Client): Optional client override
125
126
Returns:
127
Blob: Blob instance
128
"""
129
130
def list_blobs(self, max_results=None, page_token=None, prefix=None,
131
delimiter=None, versions=None, projection='noAcl', fields=None, client=None):
132
"""
133
List blobs in bucket.
134
135
Parameters:
136
- max_results (int): Maximum results per page
137
- page_token (str): Pagination token
138
- prefix (str): Filter by name prefix
139
- delimiter (str): Delimiter for hierarchical listing
140
- versions (bool): Include all object versions
141
- projection (str): Projection type ('full', 'noAcl')
142
- fields (str): Fields to return
143
- client (Client): Optional client override
144
145
Returns:
146
Iterator: Blob listing iterator
147
"""
148
149
def delete_blob(self, blob_name, client=None):
150
"""
151
Delete single blob.
152
153
Parameters:
154
- blob_name (str): Name of blob to delete
155
- client (Client): Optional client override
156
"""
157
158
def delete_blobs(self, blobs, on_error=None, client=None):
159
"""
160
Delete multiple blobs.
161
162
Parameters:
163
- blobs (list): List of blobs or blob names
164
- on_error (callable): Optional error handler
165
- client (Client): Optional client override
166
"""
167
168
def copy_blob(self, blob, destination_bucket, new_name=None, client=None):
169
"""
170
Copy blob to another bucket.
171
172
Parameters:
173
- blob (Blob): Source blob
174
- destination_bucket (Bucket): Destination bucket
175
- new_name (str): Optional new name
176
- client (Client): Optional client override
177
178
Returns:
179
Blob: Copied blob instance
180
"""
181
182
def upload_file(self, filename, blob_name=None, client=None):
183
"""
184
Upload file to bucket.
185
186
Parameters:
187
- filename (str): Local file path
188
- blob_name (str): Optional blob name (defaults to filename)
189
- client (Client): Optional client override
190
191
Returns:
192
Blob: Uploaded blob instance
193
"""
194
195
def upload_file_object(self, file_obj, blob_name=None, client=None):
196
"""
197
Upload file-like object to bucket.
198
199
Parameters:
200
- file_obj: File-like object to upload
201
- blob_name (str): Optional blob name
202
- client (Client): Optional client override
203
204
Returns:
205
Blob: Uploaded blob instance
206
"""
207
208
def make_public(self, recursive=False, future=False, client=None):
209
"""
210
Make bucket public.
211
212
Parameters:
213
- recursive (bool): Apply to all objects
214
- future (bool): Apply to future objects
215
- client (Client): Optional client override
216
"""
217
218
def configure_website(self, main_page_suffix=None, not_found_page=None):
219
"""
220
Configure bucket for static website hosting.
221
222
Parameters:
223
- main_page_suffix (str): Main page filename
224
- not_found_page (str): 404 error page filename
225
"""
226
227
def disable_website(self):
228
"""
229
Disable website configuration.
230
"""
231
232
def enable_logging(self, bucket_name, object_prefix=''):
233
"""
234
Enable access logging.
235
236
Parameters:
237
- bucket_name (str): Destination bucket for logs
238
- object_prefix (str): Log object prefix
239
"""
240
241
def disable_logging(self):
242
"""
243
Disable access logging.
244
"""
245
246
@property
247
def name(self):
248
"""
249
Bucket name.
250
251
Returns:
252
str: Bucket name
253
"""
254
255
@property
256
def versioning_enabled(self):
257
"""
258
Whether versioning is enabled.
259
260
Returns:
261
bool: Versioning status
262
"""
263
264
@versioning_enabled.setter
265
def versioning_enabled(self, value):
266
"""
267
Set versioning status.
268
269
Parameters:
270
- value (bool): Enable/disable versioning
271
"""
272
```
273
274
### Blob Operations
275
276
Object-level operations for uploading, downloading, and managing individual files in Cloud Storage.
277
278
```python { .api }
279
class Blob:
280
def __init__(self, name, bucket, chunk_size=None):
281
"""
282
Initialize blob.
283
284
Parameters:
285
- name (str): Blob name
286
- bucket (Bucket): Parent bucket
287
- chunk_size (int): Optional chunk size for transfers
288
"""
289
290
def exists(self, client=None):
291
"""
292
Check if blob exists.
293
294
Parameters:
295
- client (Client): Optional client override
296
297
Returns:
298
bool: True if blob exists
299
"""
300
301
def rename(self, new_name, client=None):
302
"""
303
Rename blob.
304
305
Parameters:
306
- new_name (str): New blob name
307
- client (Client): Optional client override
308
"""
309
310
def delete(self, client=None):
311
"""
312
Delete blob.
313
314
Parameters:
315
- client (Client): Optional client override
316
"""
317
318
def download_to_file(self, file_obj, client=None):
319
"""
320
Download blob to file-like object.
321
322
Parameters:
323
- file_obj: File-like object to write to
324
- client (Client): Optional client override
325
"""
326
327
def download_to_filename(self, filename, client=None):
328
"""
329
Download blob to local file.
330
331
Parameters:
332
- filename (str): Local file path
333
- client (Client): Optional client override
334
"""
335
336
def download_as_string(self, client=None):
337
"""
338
Download blob content as string.
339
340
Parameters:
341
- client (Client): Optional client override
342
343
Returns:
344
str: Blob content
345
"""
346
347
def upload_from_file(self, file_obj, rewind=False, size=None, content_type=None,
348
num_retries=6, client=None):
349
"""
350
Upload from file-like object.
351
352
Parameters:
353
- file_obj: File-like object to upload
354
- rewind (bool): Rewind file before reading
355
- size (int): Object size hint
356
- content_type (str): MIME content type
357
- num_retries (int): Number of retry attempts
358
- client (Client): Optional client override
359
"""
360
361
def upload_from_filename(self, filename, content_type=None, client=None):
362
"""
363
Upload from local file.
364
365
Parameters:
366
- filename (str): Local file path
367
- content_type (str): MIME content type
368
- client (Client): Optional client override
369
"""
370
371
def upload_from_string(self, data, content_type='text/plain', client=None):
372
"""
373
Upload from string data.
374
375
Parameters:
376
- data (str): String data to upload
377
- content_type (str): MIME content type
378
- client (Client): Optional client override
379
"""
380
381
def make_public(self, client=None):
382
"""
383
Make blob publicly accessible.
384
385
Parameters:
386
- client (Client): Optional client override
387
"""
388
389
def generate_signed_url(self, expiration, method='GET', content_type=None,
390
content_md5=None, response_disposition=None,
391
response_type=None, generation=None, headers=None):
392
"""
393
Generate signed URL for temporary access.
394
395
Parameters:
396
- expiration (datetime): URL expiration time
397
- method (str): HTTP method ('GET', 'POST', 'PUT', 'DELETE')
398
- content_type (str): Expected content type
399
- content_md5 (str): Expected MD5 hash
400
- response_disposition (str): Response Content-Disposition header
401
- response_type (str): Response Content-Type header
402
- generation (int): Object generation number
403
- headers (dict): Additional headers to sign
404
405
Returns:
406
str: Signed URL
407
"""
408
409
@property
410
def name(self):
411
"""
412
Blob name.
413
414
Returns:
415
str: Blob name
416
"""
417
418
@property
419
def bucket(self):
420
"""
421
Parent bucket.
422
423
Returns:
424
Bucket: Parent bucket
425
"""
426
427
@property
428
def size(self):
429
"""
430
Blob size in bytes.
431
432
Returns:
433
int: Size in bytes
434
"""
435
436
@property
437
def public_url(self):
438
"""
439
Public URL for blob.
440
441
Returns:
442
str: Public URL
443
"""
444
445
@property
446
def metadata(self):
447
"""
448
Custom metadata dictionary.
449
450
Returns:
451
dict: Metadata key-value pairs
452
"""
453
454
@metadata.setter
455
def metadata(self, value):
456
"""
457
Set custom metadata.
458
459
Parameters:
460
- value (dict): Metadata key-value pairs
461
"""
462
463
@property
464
def chunk_size(self):
465
"""
466
Upload/download chunk size.
467
468
Returns:
469
int: Chunk size in bytes
470
"""
471
472
@chunk_size.setter
473
def chunk_size(self, value):
474
"""
475
Set chunk size for transfers.
476
477
Parameters:
478
- value (int): Chunk size in bytes
479
"""
480
```
481
482
### Batch Operations
483
484
Batch operations for efficient grouping of multiple storage operations.
485
486
```python { .api }
487
class Batch:
488
def __init__(self, client):
489
"""
490
Initialize batch.
491
492
Parameters:
493
- client (Client): Storage client
494
"""
495
496
def __enter__(self):
497
"""
498
Enter context manager.
499
500
Returns:
501
Batch: Self
502
"""
503
504
def __exit__(self, exc_type, exc_val, exc_tb):
505
"""
506
Exit context manager and execute batch.
507
"""
508
```
509
510
## Usage Examples
511
512
### Basic Bucket and Blob Operations
513
514
```python
515
from gcloud import storage
516
517
# Initialize client
518
client = storage.Client(project='my-project')
519
520
# Create bucket
521
bucket = client.create_bucket('my-bucket')
522
523
# Upload file
524
blob = bucket.blob('path/to/file.txt')
525
blob.upload_from_string('Hello, Cloud Storage!')
526
527
# Download file
528
content = blob.download_as_string()
529
print(content) # Hello, Cloud Storage!
530
531
# List blobs
532
for blob in bucket.list_blobs():
533
print(f"{blob.name}: {blob.size} bytes")
534
```
535
536
### File Operations
537
538
```python
539
# Upload local file
540
blob = bucket.blob('documents/report.pdf')
541
blob.upload_from_filename('/local/path/report.pdf')
542
543
# Download to local file
544
blob.download_to_filename('/local/path/downloaded_report.pdf')
545
546
# Upload from file object
547
with open('/local/path/data.csv', 'rb') as file_obj:
548
blob = bucket.blob('data/data.csv')
549
blob.upload_from_file(file_obj)
550
```
551
552
### Access Control and Metadata
553
554
```python
555
# Make blob public
556
blob.make_public()
557
print(blob.public_url)
558
559
# Set custom metadata
560
blob.metadata = {
561
'author': 'Alice Smith',
562
'department': 'Engineering'
563
}
564
565
# Generate signed URL for temporary access
566
from datetime import datetime, timedelta
567
expiration = datetime.utcnow() + timedelta(hours=1)
568
signed_url = blob.generate_signed_url(expiration, method='GET')
569
```
570
571
### Bucket Configuration
572
573
```python
574
# Enable versioning
575
bucket.versioning_enabled = True
576
577
# Configure for static website
578
bucket.configure_website(
579
main_page_suffix='index.html',
580
not_found_page='404.html'
581
)
582
583
# Enable access logging
584
bucket.enable_logging('my-logs-bucket', 'access-logs/')
585
```