vendor/cloud.google.com/go/storage/doc.go

   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"