|
3 | 3 | - uid: cloud.google.com/go/storage |
4 | 4 | name: cloud.google.com/go/storage |
5 | 5 | id: storage |
6 | | - summary: "<p>\nPackage storage provides an easy way to work with Google Cloud Storage.\nGoogle |
7 | | - Cloud Storage stores data in named objects, which are grouped into buckets.\n</p>\n<p>\nMore |
8 | | - information about Google Cloud Storage is available at\n<a href=\"https://cloud.google.com/storage/docs\">https://cloud.google.com/storage/docs</a>.\n</p>\n<p>\nSee |
9 | | - <a href=\"https://godoc.org/cloud.google.com/go\">https://godoc.org/cloud.google.com/go</a> |
10 | | - for authentication, timeouts,\nconnection pooling and similar aspects of this |
11 | | - package.\n</p>\n<p>\nAll of the methods of this package use exponential backoff |
12 | | - to retry calls that fail\nwith certain errors, as described in\n<a href=\"https://cloud.google.com/storage/docs/exponential-backoff\">https://cloud.google.com/storage/docs/exponential-backoff</a>. |
13 | | - Retrying continues\nindefinitely unless the controlling context is canceled or |
14 | | - the client is closed. See\ncontext.WithTimeout and context.WithCancel.\n</p>\n<h3 |
15 | | - id=\"hdr-Creating_a_Client\">Creating a Client</h3>\n<p>\nTo start working with |
16 | | - this package, create a client:\n</p>\n<pre>ctx := context.Background()\nclient, |
17 | | - err := storage.NewClient(ctx)\nif err != nil {\n // TODO: Handle error.\n}\n</pre>\n<p>\nThe |
18 | | - client will use your default application credentials. Clients should be\nreused |
19 | | - instead of created as needed. The methods of Client are safe for\nconcurrent use |
20 | | - by multiple goroutines.\n</p>\n<p>\nIf you only wish to access public data, you |
21 | | - can create\nan unauthenticated client with\n</p>\n<pre>client, err := storage.NewClient(ctx, |
22 | | - option.WithoutAuthentication())\n</pre>\n<h3 id=\"hdr-Buckets\">Buckets</h3>\n<p>\nA |
| 6 | + summary: "<p>Package storage provides an easy way to work with Google Cloud Storage.\nGoogle |
| 7 | + Cloud Storage stores data in named objects, which are grouped into buckets.</p>\n<p>More |
| 8 | + information about Google Cloud Storage is available at\nhttps://cloud.google.com/storage/docs.</p>\n<p>See |
| 9 | + https://godoc.org/cloud.google.com/go for authentication, timeouts,\nconnection |
| 10 | + pooling and similar aspects of this package.</p>\n<p>All of the methods of this |
| 11 | + package use exponential backoff to retry calls that fail\nwith certain errors, |
| 12 | + as described in\nhttps://cloud.google.com/storage/docs/exponential-backoff. Retrying |
| 13 | + continues\nindefinitely unless the controlling context is canceled or the client |
| 14 | + is closed. See\ncontext.WithTimeout and context.WithCancel.</p>\n<h3>Creating |
| 15 | + a Client</h3>\n<p>To start working with this package, create a client:</p>\n<pre><code>ctx |
| 16 | + := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil |
| 17 | + {\n // TODO: Handle error.\n}\n</code></pre>\n<p>The client will use your default |
| 18 | + application credentials. Clients should be\nreused instead of created as needed. |
| 19 | + The methods of Client are safe for\nconcurrent use by multiple goroutines.</p>\n<p>If |
| 20 | + you only wish to access public data, you can create\nan unauthenticated client |
| 21 | + with</p>\n<pre><code>client, err := storage.NewClient(ctx, option.WithoutAuthentication())\n</code></pre>\n<h3>Buckets</h3>\n<p>A |
23 | 22 | Google Cloud Storage bucket is a collection of objects. To work with a\nbucket, |
24 | | - make a bucket handle:\n</p>\n<pre>bkt := client.Bucket(bucketName)\n</pre>\n<p>\nA |
25 | | - handle is a reference to a bucket. You can have a handle even if the\nbucket doesn't |
26 | | - exist yet. To create a bucket in Google Cloud Storage,\ncall Create on the handle:\n</p>\n<pre>if |
27 | | - err := bkt.Create(ctx, projectID, nil); err != nil {\n // TODO: Handle error.\n}\n</pre>\n<p>\nNote |
| 23 | + make a bucket handle:</p>\n<pre><code>bkt := client.Bucket(bucketName)\n</code></pre>\n<p>A |
| 24 | + handle is a reference to a bucket. You can have a handle even if the\nbucket doesn't |
| 25 | + exist yet. To create a bucket in Google Cloud Storage,\ncall Create on the handle:</p>\n<pre><code>if |
| 26 | + err := bkt.Create(ctx, projectID, nil); err != nil {\n // TODO: Handle error.\n}\n</code></pre>\n<p>Note |
28 | 27 | that although buckets are associated with projects, bucket names are\nglobal across |
29 | | - all projects.\n</p>\n<p>\nEach bucket has associated metadata, represented in |
30 | | - this package by\nBucketAttrs. The third argument to BucketHandle.Create allows |
31 | | - you to set\nthe initial BucketAttrs of a bucket. To retrieve a bucket's attributes, |
32 | | - use\nAttrs:\n</p>\n<pre>attrs, err := bkt.Attrs(ctx)\nif err != nil {\n // |
33 | | - TODO: Handle error.\n}\nfmt.Printf("bucket %s, created at %s, is located in |
34 | | - %s with storage class %s\\n",\n attrs.Name, attrs.Created, attrs.Location, |
35 | | - attrs.StorageClass)\n</pre>\n<h3 id=\"hdr-Objects\">Objects</h3>\n<p>\nAn object |
36 | | - holds arbitrary data as a sequence of bytes, like a file. You\nrefer to objects |
37 | | - using a handle, just as with buckets, but unlike buckets\nyou don't explicitly |
38 | | - create an object. Instead, the first time you write\nto an object it will be created. |
39 | | - You can use the standard Go io.Reader\nand io.Writer interfaces to read and write |
40 | | - object data:\n</p>\n<pre>obj := bkt.Object("data")\n// Write something |
41 | | - to obj.\n// w implements io.Writer.\nw := obj.NewWriter(ctx)\n// Write some text |
42 | | - to obj. This will either create the object or overwrite whatever is there already.\nif |
43 | | - _, err := fmt.Fprintf(w, "This object contains text.\\n"); err != nil |
44 | | - {\n // TODO: Handle error.\n}\n// Close, just like writing a file.\nif err |
45 | | - := w.Close(); err != nil {\n // TODO: Handle error.\n}\n\n// Read it back.\nr, |
46 | | - err := obj.NewReader(ctx)\nif err != nil {\n // TODO: Handle error.\n}\ndefer |
47 | | - r.Close()\nif _, err := io.Copy(os.Stdout, r); err != nil {\n // TODO: Handle |
48 | | - error.\n}\n// Prints "This object contains text."\n</pre>\n<p>\nObjects |
49 | | - also have attributes, which you can fetch with Attrs:\n</p>\n<pre>objAttrs, err |
50 | | - := obj.Attrs(ctx)\nif err != nil {\n // TODO: Handle error.\n}\nfmt.Printf("object |
51 | | - %s has size %d and can be read using %s\\n",\n objAttrs.Name, objAttrs.Size, |
52 | | - objAttrs.MediaLink)\n</pre>\n<h3 id=\"hdr-Listing_objects\">Listing objects</h3>\n<p>\nListing |
53 | | - objects in a bucket is done with the Bucket.Objects method:\n</p>\n<pre>query |
54 | | - := &storage.Query{Prefix: ""}\n\nvar names []string\nit := bkt.Objects(ctx, |
| 28 | + all projects.</p>\n<p>Each bucket has associated metadata, represented in this |
| 29 | + package by\nBucketAttrs. The third argument to BucketHandle.Create allows you |
| 30 | + to set\nthe initial BucketAttrs of a bucket. To retrieve a bucket's attributes, |
| 31 | + use\nAttrs:</p>\n<pre><code>attrs, err := bkt.Attrs(ctx)\nif err != nil {\n // |
| 32 | + TODO: Handle error.\n}\nfmt.Printf("bucket %s, created at %s, is located |
| 33 | + in %s with storage class %s\\n",\n attrs.Name, attrs.Created, attrs.Location, |
| 34 | + attrs.StorageClass)\n</code></pre>\n<h3>Objects</h3>\n<p>An object holds arbitrary |
| 35 | + data as a sequence of bytes, like a file. You\nrefer to objects using a handle, |
| 36 | + just as with buckets, but unlike buckets\nyou don't explicitly create an object. |
| 37 | + Instead, the first time you write\nto an object it will be created. You can use |
| 38 | + the standard Go io.Reader\nand io.Writer interfaces to read and write object data:</p>\n<pre><code>obj |
| 39 | + := bkt.Object("data")\n// Write something to obj.\n// w implements io.Writer.\nw |
| 40 | + := obj.NewWriter(ctx)\n// Write some text to obj. This will either create the |
| 41 | + object or overwrite whatever is there already.\nif _, err := fmt.Fprintf(w, "This |
| 42 | + object contains text.\\n"); err != nil {\n // TODO: Handle error.\n}\n// |
| 43 | + Close, just like writing a file.\nif err := w.Close(); err != nil {\n // TODO: |
| 44 | + Handle error.\n}\n\n// Read it back.\nr, err := obj.NewReader(ctx)\nif err != |
| 45 | + nil {\n // TODO: Handle error.\n}\ndefer r.Close()\nif _, err := io.Copy(os.Stdout, |
| 46 | + r); err != nil {\n // TODO: Handle error.\n}\n// Prints "This object contains |
| 47 | + text."\n</code></pre>\n<p>Objects also have attributes, which you can fetch |
| 48 | + with Attrs:</p>\n<pre><code>objAttrs, err := obj.Attrs(ctx)\nif err != nil {\n |
| 49 | + \ // TODO: Handle error.\n}\nfmt.Printf("object %s has size %d and can |
| 50 | + be read using %s\\n",\n objAttrs.Name, objAttrs.Size, objAttrs.MediaLink)\n</code></pre>\n<h3>Listing |
| 51 | + objects</h3>\n<p>Listing objects in a bucket is done with the Bucket.Objects method:</p>\n<pre><code>query |
| 52 | + := &storage.Query{Prefix: ""}\n\nvar names []string\nit := bkt.Objects(ctx, |
55 | 53 | query)\nfor {\n attrs, err := it.Next()\n if err == iterator.Done {\n break\n |
56 | 54 | \ }\n if err != nil {\n log.Fatal(err)\n }\n names = append(names, |
57 | | - attrs.Name)\n}\n</pre>\n<p>\nIf only a subset of object attributes is needed when |
58 | | - listing, specifying this\nsubset using Query.SetAttrSelection may speed up the |
59 | | - listing process:\n</p>\n<pre>query := &storage.Query{Prefix: ""}\nquery.SetAttrSelection([]string{"Name"})\n\n// |
60 | | - ... as before\n</pre>\n<h3 id=\"hdr-ACLs\">ACLs</h3>\n<p>\nBoth objects and buckets |
61 | | - have ACLs (Access Control Lists). An ACL is a list of\nACLRules, each of which |
62 | | - specifies the role of a user, group or project. ACLs\nare suitable for fine-grained |
63 | | - control, but you may prefer using IAM to control\naccess at the project level |
64 | | - (see\n<a href=\"https://cloud.google.com/storage/docs/access-control/iam\">https://cloud.google.com/storage/docs/access-control/iam</a>).\n</p>\n<p>\nTo |
65 | | - list the ACLs of a bucket or object, obtain an ACLHandle and call its List method:\n</p>\n<pre>acls, |
| 55 | + attrs.Name)\n}\n</code></pre>\n<p>If only a subset of object attributes is needed |
| 56 | + when listing, specifying this\nsubset using Query.SetAttrSelection may speed up |
| 57 | + the listing process:</p>\n<pre><code>query := &storage.Query{Prefix: ""}\nquery.SetAttrSelection([]string{"Name"})\n\n// |
| 58 | + ... as before\n</code></pre>\n<h3>ACLs</h3>\n<p>Both objects and buckets have |
| 59 | + ACLs (Access Control Lists). An ACL is a list of\nACLRules, each of which specifies |
| 60 | + the role of a user, group or project. ACLs\nare suitable for fine-grained control, |
| 61 | + but you may prefer using IAM to control\naccess at the project level (see\nhttps://cloud.google.com/storage/docs/access-control/iam).</p>\n<p>To |
| 62 | + list the ACLs of a bucket or object, obtain an ACLHandle and call its List method:</p>\n<pre><code>acls, |
66 | 63 | err := obj.ACL().List(ctx)\nif err != nil {\n // TODO: Handle error.\n}\nfor |
67 | | - _, rule := range acls {\n fmt.Printf("%s has role %s\\n", rule.Entity, |
68 | | - rule.Role)\n}\n</pre>\n<p>\nYou can also set and delete ACLs.\n</p>\n<h3 id=\"hdr-Conditions\">Conditions</h3>\n<p>\nEvery |
| 64 | + _, rule := range acls {\n fmt.Printf("%s has role %s\\n", rule.Entity, |
| 65 | + rule.Role)\n}\n</code></pre>\n<p>You can also set and delete ACLs.</p>\n<h3>Conditions</h3>\n<p>Every |
69 | 66 | object has a generation and a metageneration. The generation changes\nwhenever |
70 | 67 | the content changes, and the metageneration changes whenever the\nmetadata changes. |
71 | 68 | Conditions let you check these values before an operation;\nthe operation only |
72 | 69 | executes if the conditions match. You can use conditions to\nprevent race conditions |
73 | | - in read-modify-write operations.\n</p>\n<p>\nFor example, say you've read |
74 | | - an object's metadata into objAttrs. Now\nyou want to write to that object, |
75 | | - but only if its contents haven't changed\nsince you read it. Here is how to |
76 | | - express that:\n</p>\n<pre>w = obj.If(storage.Conditions{GenerationMatch: objAttrs.Generation}).NewWriter(ctx)\n// |
77 | | - Proceed with writing as above.\n</pre>\n<h3 id=\"hdr-Signed_URLs\">Signed URLs</h3>\n<p>\nYou |
78 | | - can obtain a URL that lets anyone read or write an object for a limited time.\nYou |
79 | | - don't need to create a client to do this. See the documentation of\nSignedURL |
80 | | - for details.\n</p>\n<pre>url, err := storage.SignedURL(bucketName, "shared-object", |
81 | | - opts)\nif err != nil {\n // TODO: Handle error.\n}\nfmt.Println(url)\n</pre>\n<h3 |
82 | | - id=\"hdr-Post_Policy_V4_Signed_Request\">Post Policy V4 Signed Request</h3>\n<p>\nA |
83 | | - type of signed request that allows uploads through HTML forms directly to Cloud |
84 | | - Storage with\ntemporary permission. Conditions can be applied to restrict how |
85 | | - the HTML form is used and exercised\nby a user.\n</p>\n<p>\nFor more information, |
86 | | - please see <a href=\"https://cloud.google.com/storage/docs/xml-api/post-object\">https://cloud.google.com/storage/docs/xml-api/post-object</a> |
87 | | - as well\nas the documentation of GenerateSignedPostPolicyV4.\n</p>\n<pre>pv4, |
| 70 | + in read-modify-write operations.</p>\n<p>For example, say you've read an object's |
| 71 | + metadata into objAttrs. Now\nyou want to write to that object, but only if its |
| 72 | + contents haven't changed\nsince you read it. Here is how to express that:</p>\n<pre><code>w |
| 73 | + = obj.If(storage.Conditions{GenerationMatch: objAttrs.Generation}).NewWriter(ctx)\n// |
| 74 | + Proceed with writing as above.\n</code></pre>\n<h3>Signed URLs</h3>\n<p>You can |
| 75 | + obtain a URL that lets anyone read or write an object for a limited time.\nYou |
| 76 | + don't need to create a client to do this. See the documentation of\nSignedURL |
| 77 | + for details.</p>\n<pre><code>url, err := storage.SignedURL(bucketName, "shared-object", |
| 78 | + opts)\nif err != nil {\n // TODO: Handle error.\n}\nfmt.Println(url)\n</code></pre>\n<h3>Post |
| 79 | + Policy V4 Signed Request</h3>\n<p>A type of signed request that allows uploads |
| 80 | + through HTML forms directly to Cloud Storage with\ntemporary permission. Conditions |
| 81 | + can be applied to restrict how the HTML form is used and exercised\nby a user.</p>\n<p>For |
| 82 | + more information, please see https://cloud.google.com/storage/docs/xml-api/post-object |
| 83 | + as well\nas the documentation of GenerateSignedPostPolicyV4.</p>\n<pre><code>pv4, |
88 | 84 | err := storage.GenerateSignedPostPolicyV4(bucketName, objectName, opts)\nif err |
89 | | - != nil {\n // TODO: Handle error.\n}\nfmt.Printf("URL: %s\\nFields; %v\\n", |
90 | | - pv4.URL, pv4.Fields)\n</pre>\n<h3 id=\"hdr-Errors\">Errors</h3>\n<p>\nErrors returned |
91 | | - by this client are often of the type [`googleapi.Error`](<a href=\"https://godoc.org/google.golang.org/api/googleapi#Error\">https://godoc.org/google.golang.org/api/googleapi#Error</a>).\nThese |
| 85 | + != nil {\n // TODO: Handle error.\n}\nfmt.Printf("URL: %s\\nFields; %v\\n", |
| 86 | + pv4.URL, pv4.Fields)\n</code></pre>\n<h3>Errors</h3>\n<p>Errors returned by this |
| 87 | + client are often of the type <a href=\"https://godoc.org/google.golang.org/api/googleapi#Error\"><code>googleapi.Error</code></a>.\nThese |
92 | 88 | errors can be introspected for more information by type asserting to the richer |
93 | | - `googleapi.Error` type. For example:\n</p>\n<pre>if e, ok := err.(*googleapi.Error); |
94 | | - ok {\n\t if e.Code == 409 { ... }\n}\n</pre>\n" |
| 89 | + <code>googleapi.Error</code> type. For example:</p>\n<pre><code>if e, ok := err.(*googleapi.Error); |
| 90 | + ok {\n\t if e.Code == 409 { ... }\n}\n</code></pre>\n" |
95 | 91 | type: package |
96 | 92 | langs: |
97 | 93 | - go |
|
0 commit comments