]>
Commit | Line | Data |
---|---|---|
107c1cdb ND |
1 | // Copyright 2016 Google LLC |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 | // you may not use this file except in compliance with the License. | |
5 | // You may obtain a copy of the License at | |
6 | // | |
7 | // http://www.apache.org/licenses/LICENSE-2.0 | |
8 | // | |
9 | // Unless required by applicable law or agreed to in writing, software | |
10 | // distributed under the License is distributed on an "AS IS" BASIS, | |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 | // See the License for the specific language governing permissions and | |
13 | // limitations under the License. | |
14 | ||
15 | /* | |
16 | Package storage provides an easy way to work with Google Cloud Storage. | |
17 | Google Cloud Storage stores data in named objects, which are grouped into buckets. | |
18 | ||
19 | More information about Google Cloud Storage is available at | |
20 | https://cloud.google.com/storage/docs. | |
21 | ||
22 | See https://godoc.org/cloud.google.com/go for authentication, timeouts, | |
23 | connection pooling and similar aspects of this package. | |
24 | ||
25 | All of the methods of this package use exponential backoff to retry calls that fail | |
26 | with certain errors, as described in | |
27 | https://cloud.google.com/storage/docs/exponential-backoff. Retrying continues | |
28 | indefinitely unless the controlling context is canceled or the client is closed. See | |
29 | context.WithTimeout and context.WithCancel. | |
30 | ||
31 | ||
32 | Creating a Client | |
33 | ||
34 | To start working with this package, create a client: | |
35 | ||
36 | ctx := context.Background() | |
37 | client, err := storage.NewClient(ctx) | |
38 | if err != nil { | |
39 | // TODO: Handle error. | |
40 | } | |
41 | ||
42 | The client will use your default application credentials. | |
43 | ||
44 | If you only wish to access public data, you can create | |
45 | an unauthenticated client with | |
46 | ||
47 | client, err := storage.NewClient(ctx, option.WithoutAuthentication()) | |
48 | ||
49 | Buckets | |
50 | ||
51 | A Google Cloud Storage bucket is a collection of objects. To work with a | |
52 | bucket, make a bucket handle: | |
53 | ||
54 | bkt := client.Bucket(bucketName) | |
55 | ||
56 | A handle is a reference to a bucket. You can have a handle even if the | |
57 | bucket doesn't exist yet. To create a bucket in Google Cloud Storage, | |
58 | call Create on the handle: | |
59 | ||
60 | if err := bkt.Create(ctx, projectID, nil); err != nil { | |
61 | // TODO: Handle error. | |
62 | } | |
63 | ||
64 | Note that although buckets are associated with projects, bucket names are | |
65 | global across all projects. | |
66 | ||
67 | Each bucket has associated metadata, represented in this package by | |
68 | BucketAttrs. The third argument to BucketHandle.Create allows you to set | |
69 | the initial BucketAttrs of a bucket. To retrieve a bucket's attributes, use | |
70 | Attrs: | |
71 | ||
72 | attrs, err := bkt.Attrs(ctx) | |
73 | if err != nil { | |
74 | // TODO: Handle error. | |
75 | } | |
76 | fmt.Printf("bucket %s, created at %s, is located in %s with storage class %s\n", | |
77 | attrs.Name, attrs.Created, attrs.Location, attrs.StorageClass) | |
78 | ||
79 | Objects | |
80 | ||
81 | An object holds arbitrary data as a sequence of bytes, like a file. You | |
82 | refer to objects using a handle, just as with buckets, but unlike buckets | |
83 | you don't explicitly create an object. Instead, the first time you write | |
84 | to an object it will be created. You can use the standard Go io.Reader | |
85 | and io.Writer interfaces to read and write object data: | |
86 | ||
87 | obj := bkt.Object("data") | |
88 | // Write something to obj. | |
89 | // w implements io.Writer. | |
90 | w := obj.NewWriter(ctx) | |
91 | // Write some text to obj. This will either create the object or overwrite whatever is there already. | |
92 | if _, err := fmt.Fprintf(w, "This object contains text.\n"); err != nil { | |
93 | // TODO: Handle error. | |
94 | } | |
95 | // Close, just like writing a file. | |
96 | if err := w.Close(); err != nil { | |
97 | // TODO: Handle error. | |
98 | } | |
99 | ||
100 | // Read it back. | |
101 | r, err := obj.NewReader(ctx) | |
102 | if err != nil { | |
103 | // TODO: Handle error. | |
104 | } | |
105 | defer r.Close() | |
106 | if _, err := io.Copy(os.Stdout, r); err != nil { | |
107 | // TODO: Handle error. | |
108 | } | |
109 | // Prints "This object contains text." | |
110 | ||
111 | Objects also have attributes, which you can fetch with Attrs: | |
112 | ||
113 | objAttrs, err := obj.Attrs(ctx) | |
114 | if err != nil { | |
115 | // TODO: Handle error. | |
116 | } | |
117 | fmt.Printf("object %s has size %d and can be read using %s\n", | |
118 | objAttrs.Name, objAttrs.Size, objAttrs.MediaLink) | |
119 | ||
120 | ACLs | |
121 | ||
122 | Both objects and buckets have ACLs (Access Control Lists). An ACL is a list of | |
123 | ACLRules, each of which specifies the role of a user, group or project. ACLs | |
124 | are suitable for fine-grained control, but you may prefer using IAM to control | |
125 | access at the project level (see | |
126 | https://cloud.google.com/storage/docs/access-control/iam). | |
127 | ||
128 | To list the ACLs of a bucket or object, obtain an ACLHandle and call its List method: | |
129 | ||
130 | acls, err := obj.ACL().List(ctx) | |
131 | if err != nil { | |
132 | // TODO: Handle error. | |
133 | } | |
134 | for _, rule := range acls { | |
135 | fmt.Printf("%s has role %s\n", rule.Entity, rule.Role) | |
136 | } | |
137 | ||
138 | You can also set and delete ACLs. | |
139 | ||
140 | Conditions | |
141 | ||
142 | Every object has a generation and a metageneration. The generation changes | |
143 | whenever the content changes, and the metageneration changes whenever the | |
144 | metadata changes. Conditions let you check these values before an operation; | |
145 | the operation only executes if the conditions match. You can use conditions to | |
146 | prevent race conditions in read-modify-write operations. | |
147 | ||
148 | For example, say you've read an object's metadata into objAttrs. Now | |
149 | you want to write to that object, but only if its contents haven't changed | |
150 | since you read it. Here is how to express that: | |
151 | ||
152 | w = obj.If(storage.Conditions{GenerationMatch: objAttrs.Generation}).NewWriter(ctx) | |
153 | // Proceed with writing as above. | |
154 | ||
155 | Signed URLs | |
156 | ||
157 | You can obtain a URL that lets anyone read or write an object for a limited time. | |
158 | You don't need to create a client to do this. See the documentation of | |
159 | SignedURL for details. | |
160 | ||
161 | url, err := storage.SignedURL(bucketName, "shared-object", opts) | |
162 | if err != nil { | |
163 | // TODO: Handle error. | |
164 | } | |
165 | fmt.Println(url) | |
166 | ||
167 | Errors | |
168 | ||
169 | Errors returned by this client are often of the type [`googleapi.Error`](https://godoc.org/google.golang.org/api/googleapi#Error). | |
170 | These errors can be introspected for more information by type asserting to the richer `googleapi.Error` type. For example: | |
171 | ||
172 | if e, ok := err.(*googleapi.Error); ok { | |
173 | if e.Code == 409 { ... } | |
174 | } | |
175 | */ | |
176 | package storage // import "cloud.google.com/go/storage" |