3 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/google-cloud-go.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/google-cloud-go)
4 [![GoDoc](https://godoc.org/cloud.google.com/go?status.svg)](https://godoc.org/cloud.google.com/go)
7 import "cloud.google.com/go"
10 Go packages for Google Cloud Platform services.
12 To install the packages on your system,
15 $ go get -u cloud.google.com/go/...
18 **NOTE:** These packages are under development, and may occasionally make
19 backwards-incompatible changes.
21 **NOTE:** Github repo is a mirror of [https://code.googlesource.com/gocloud](https://code.googlesource.com/gocloud).
27 More changes to BigQuery:
29 * The `ValueList` type was removed. It is no longer necessary. Instead of
41 * Previously, repeatedly calling `RowIterator.Next` on the same `[]Value` or
42 `ValueList` would append to the slice. Now each call resets the size to zero first.
44 * Schema inference will infer the SQL type BYTES for a struct field of
45 type []byte. Previously it inferred STRING.
47 * The types `uint`, `uint64` and `uintptr` are no longer supported in schema
48 inference. BigQuery's integer type is INT64, and those types may hold values
49 that are not correctly represented in a 64-bit signed integer.
51 * The SQL types DATE, TIME and DATETIME are now supported. They correspond to
52 the `Date`, `Time` and `DateTime` types in the new `cloud.google.com/go/civil`
57 Change to BigQuery: values from INTEGER columns will now be returned as int64,
58 not int. This will avoid errors arising from large values on 32-bit systems.
62 New datastore feature: datastore now encodes your nested Go structs as Entity values,
63 instead of a flattened list of the embedded struct's fields.
64 This means that you may now have twice-nested slices, eg.
73 See [the announcement](https://groups.google.com/forum/#!topic/google-api-go-announce/79jtrdeuJAg) for
78 Breaking changes to datastore: contexts no longer hold namespaces; instead you
79 must set a key's namespace explicitly. Also, key functions have been changed
82 * The WithNamespace function has been removed. To specify a namespace in a Query, use the Query.Namespace method:
84 q := datastore.NewQuery("Kind").Namespace("ns")
87 * All the fields of Key are exported. That means you can construct any Key with a struct literal:
89 k := &Key{Kind: "Kind", ID: 37, Namespace: "ns"}
92 * As a result of the above, the Key methods Kind, ID, d.Name, Parent, SetParent and Namespace have been removed.
94 * `NewIncompleteKey` has been removed, replaced by `IncompleteKey`. Replace
96 NewIncompleteKey(ctx, kind, parent)
100 IncompleteKey(kind, parent)
102 and if you do use namespaces, make sure you set the namespace on the returned key.
104 * `NewKey` has been removed, replaced by `NameKey` and `IDKey`. Replace
106 NewKey(ctx, kind, name, 0, parent)
107 NewKey(ctx, kind, "", id, parent)
111 NameKey(kind, name, parent)
112 IDKey(kind, id, parent)
114 and if you do use namespaces, make sure you set the namespace on the returned key.
116 * The `Done` variable has been removed. Replace `datastore.Done` with `iterator.Done`, from the package `google.golang.org/api/iterator`.
118 * The `Client.Close` method will have a return type of error. It will return the result of closing the underlying gRPC connection.
120 See [the announcement](https://groups.google.com/forum/#!topic/google-api-go-announce/hqXtM_4Ix-0) for
125 Breaking change to bigquery: `NewGCSReference` is now a function,
126 not a method on `Client`.
128 New bigquery feature: `Table.LoaderFrom` now accepts a `ReaderSource`, enabling
129 loading data into a table from a file or any `io.Reader`.
133 Breaking change to pubsub: removed `pubsub.Done`.
135 Use `iterator.Done` instead, where `iterator` is the package
136 `google.golang.org/api/iterator`.
139 [Older news](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/master/old-news.md)
143 Google API | Status | Package
144 -------------------------------|--------------|-----------------------------------------------------------
145 [Datastore][cloud-datastore] | beta | [`cloud.google.com/go/datastore`][cloud-datastore-ref]
146 [Storage][cloud-storage] | beta | [`cloud.google.com/go/storage`][cloud-storage-ref]
147 [Bigtable][cloud-bigtable] | beta | [`cloud.google.com/go/bigtable`][cloud-bigtable-ref]
148 [BigQuery][cloud-bigquery] | beta | [`cloud.google.com/go/bigquery`][cloud-bigquery-ref]
149 [Logging][cloud-logging] | beta | [`cloud.google.com/go/logging`][cloud-logging-ref]
150 [Pub/Sub][cloud-pubsub] | experimental | [`cloud.google.com/go/pubsub`][cloud-pubsub-ref]
151 [Vision][cloud-vision] | experimental | [`cloud.google.com/go/vision`][cloud-vision-ref]
152 [Language][cloud-language] | experimental | [`cloud.google.com/go/language/apiv1beta1`][cloud-language-ref]
153 [Speech][cloud-speech] | experimental | [`cloud.google.com/go/speech/apiv1beta`][cloud-speech-ref]
156 > **Experimental status**: the API is still being actively developed. As a
157 > result, it might change in backward-incompatible ways and is not recommended
158 > for production use.
160 > **Beta status**: the API is largely complete, but still has outstanding
161 > features and bugs to be addressed. There may be minor backwards-incompatible
162 > changes where necessary.
164 > **Stable status**: the API is mature and ready for production use. We will
165 > continue addressing bugs and feature requests.
167 Documentation and examples are available at
168 https://godoc.org/cloud.google.com/go
171 [google-api-go-announce group](https://groups.google.com/forum/#!forum/google-api-go-announce)
172 for updates on these packages.
174 ## Go Versions Supported
176 We support the two most recent major versions of Go. If Google App Engine uses
177 an older version, we support that as well. You can see which versions are
178 currently supported by looking at the lines following `go:` in
179 [`.travis.yml`](.travis.yml).
183 By default, each API will use [Google Application Default Credentials][default-creds]
184 for authorization credentials used in calling the API endpoints. This will allow your
185 application to run in many environments without requiring explicit configuration.
188 [JSON key file](https://cloud.google.com/iam/docs/managing-service-account-keys),
190 [`option.WithServiceAccountFile`](https://godoc.org/google.golang.org/api/option#WithServiceAccountFile)
191 to the `NewClient` function of the desired package. For example:
194 client, err := storage.NewClient(ctx, option.WithServiceAccountFile("path/to/keyfile.json"))
197 You can exert more control over authorization by using the
198 [`golang.org/x/oauth2`](https://godoc.org/golang.org/x/oauth2) package to
199 create an `oauth2.TokenSource`. Then pass
200 [`option.WithTokenSource`](https://godoc.org/google.golang.org/api/option#WithTokenSource)
201 to the `NewClient` function:
204 client, err := storage.NewClient(ctx, option.WithTokenSource(tokenSource))
207 ## Cloud Datastore [![GoDoc](https://godoc.org/cloud.google.com/go/datastore?status.svg)](https://godoc.org/cloud.google.com/go/datastore)
209 - [About Cloud Datastore][cloud-datastore]
210 - [Activating the API for your project][cloud-datastore-activation]
211 - [API documentation][cloud-datastore-docs]
212 - [Go client documentation](https://godoc.org/cloud.google.com/go/datastore)
213 - [Complete sample program](https://github.com/GoogleCloudPlatform/golang-samples/tree/master/datastore/tasks)
217 First create a `datastore.Client` to use throughout your application:
220 client, err := datastore.NewClient(ctx, "my-project-id")
226 Then use that client to interact with the API:
231 Body string `datastore:",noindex"`
232 PublishedAt time.Time
234 keys := []*datastore.Key{
235 datastore.NewKey(ctx, "Post", "post1", 0, nil),
236 datastore.NewKey(ctx, "Post", "post2", 0, nil),
239 {Title: "Post 1", Body: "...", PublishedAt: time.Now()},
240 {Title: "Post 2", Body: "...", PublishedAt: time.Now()},
242 if _, err := client.PutMulti(ctx, keys, posts); err != nil {
247 ## Cloud Storage [![GoDoc](https://godoc.org/cloud.google.com/go/storage?status.svg)](https://godoc.org/cloud.google.com/go/storage)
249 - [About Cloud Storage][cloud-storage]
250 - [API documentation][cloud-storage-docs]
251 - [Go client documentation](https://godoc.org/cloud.google.com/go/storage)
252 - [Complete sample programs](https://github.com/GoogleCloudPlatform/golang-samples/tree/master/storage)
256 First create a `storage.Client` to use throughout your application:
259 client, err := storage.NewClient(ctx)
266 // Read the object1 from bucket.
267 rc, err := client.Bucket("bucket").Object("object1").NewReader(ctx)
272 body, err := ioutil.ReadAll(rc)
278 ## Cloud Pub/Sub [![GoDoc](https://godoc.org/cloud.google.com/go/pubsub?status.svg)](https://godoc.org/cloud.google.com/go/pubsub)
280 - [About Cloud Pubsub][cloud-pubsub]
281 - [API documentation][cloud-pubsub-docs]
282 - [Go client documentation](https://godoc.org/cloud.google.com/go/pubsub)
283 - [Complete sample programs](https://github.com/GoogleCloudPlatform/golang-samples/tree/master/pubsub)
287 First create a `pubsub.Client` to use throughout your application:
290 client, err := pubsub.NewClient(ctx, "project-id")
297 // Publish "hello world" on topic1.
298 topic := client.Topic("topic1")
299 msgIDs, err := topic.Publish(ctx, &pubsub.Message{
300 Data: []byte("hello world"),
306 // Create an iterator to pull messages via subscription1.
307 it, err := client.Subscription("subscription1").Pull(ctx)
313 // Consume N messages from the iterator.
314 for i := 0; i < N; i++ {
315 msg, err := it.Next()
316 if err == iterator.Done {
320 log.Fatalf("Failed to retrieve message: %v", err)
323 fmt.Printf("Message %d: %s\n", i, msg.Data)
324 msg.Done(true) // Acknowledge that we've consumed the message.
328 ## Cloud BigQuery [![GoDoc](https://godoc.org/cloud.google.com/go/bigquery?status.svg)](https://godoc.org/cloud.google.com/go/bigquery)
330 - [About Cloud BigQuery][cloud-bigquery]
331 - [API documentation][cloud-bigquery-docs]
332 - [Go client documentation][cloud-bigquery-ref]
333 - [Complete sample programs](https://github.com/GoogleCloudPlatform/golang-samples/tree/master/bigquery)
337 First create a `bigquery.Client` to use throughout your application:
339 c, err := bigquery.NewClient(ctx, "my-project-ID")
341 // TODO: Handle error.
344 Then use that client to interact with the API:
346 // Construct a query.
348 SELECT year, SUM(number)
349 FROM [bigquery-public-data:usa_names.usa_1910_2013]
350 WHERE name = "William"
354 // Execute the query.
355 it, err := q.Read(ctx)
357 // TODO: Handle error.
359 // Iterate through the results.
361 var values bigquery.ValueList
362 err := it.Next(&values)
363 if err == iterator.Done {
367 // TODO: Handle error.
374 ## Stackdriver Logging [![GoDoc](https://godoc.org/cloud.google.com/go/logging?status.svg)](https://godoc.org/cloud.google.com/go/logging)
376 - [About Stackdriver Logging][cloud-logging]
377 - [API documentation][cloud-logging-docs]
378 - [Go client documentation][cloud-logging-ref]
379 - [Complete sample programs](https://github.com/GoogleCloudPlatform/golang-samples/tree/master/logging)
383 First create a `logging.Client` to use throughout your application:
386 ctx := context.Background()
387 client, err := logging.NewClient(ctx, "my-project")
389 // TODO: Handle error.
392 Usually, you'll want to add log entries to a buffer to be periodically flushed
393 (automatically and asynchronously) to the Stackdriver Logging service.
395 logger := client.Logger("my-log")
396 logger.Log(logging.Entry{Payload: "something happened!"})
398 Close your client before your program exits, to flush any buffered log entries.
402 // TODO: Handle error.
408 Contributions are welcome. Please, see the
409 [CONTRIBUTING](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/master/CONTRIBUTING.md)
410 document for details. We're using Gerrit for our code reviews. Please don't open pull
411 requests against this repo, new pull requests will be automatically closed.
413 Please note that this project is released with a Contributor Code of Conduct.
414 By participating in this project you agree to abide by its terms.
415 See [Contributor Code of Conduct](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/master/CONTRIBUTING.md#contributor-code-of-conduct)
416 for more information.
418 [cloud-datastore]: https://cloud.google.com/datastore/
419 [cloud-datastore-ref]: https://godoc.org/cloud.google.com/go/datastore
420 [cloud-datastore-docs]: https://cloud.google.com/datastore/docs
421 [cloud-datastore-activation]: https://cloud.google.com/datastore/docs/activate
423 [cloud-pubsub]: https://cloud.google.com/pubsub/
424 [cloud-pubsub-ref]: https://godoc.org/cloud.google.com/go/pubsub
425 [cloud-pubsub-docs]: https://cloud.google.com/pubsub/docs
427 [cloud-storage]: https://cloud.google.com/storage/
428 [cloud-storage-ref]: https://godoc.org/cloud.google.com/go/storage
429 [cloud-storage-docs]: https://cloud.google.com/storage/docs
430 [cloud-storage-create-bucket]: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
432 [cloud-bigtable]: https://cloud.google.com/bigtable/
433 [cloud-bigtable-ref]: https://godoc.org/cloud.google.com/go/bigtable
435 [cloud-bigquery]: https://cloud.google.com/bigquery/
436 [cloud-bigquery-docs]: https://cloud.google.com/bigquery/docs
437 [cloud-bigquery-ref]: https://godoc.org/cloud.google.com/go/bigquery
439 [cloud-logging]: https://cloud.google.com/logging/
440 [cloud-logging-docs]: https://cloud.google.com/logging/docs
441 [cloud-logging-ref]: https://godoc.org/cloud.google.com/go/logging
443 [cloud-vision]: https://cloud.google.com/vision/
444 [cloud-vision-ref]: https://godoc.org/cloud.google.com/go/vision
446 [cloud-language]: https://cloud.google.com/natural-language
447 [cloud-language-ref]: https://godoc.org/cloud.google.com/go/language/apiv1beta1
449 [cloud-speech]: https://cloud.google.com/speech
450 [cloud-speech-ref]: https://godoc.org/cloud.google.com/go/speech/apiv1beta1
452 [default-creds]: https://developers.google.com/identity/protocols/application-default-credentials