vendor/cloud.google.com/go/README.md

   1 # Google Cloud for Go
   2
   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)
   5
   6 ``` go
   7 import "cloud.google.com/go"
   8 ```
   9
  10 Go packages for Google Cloud Platform services.
  11
  12 To install the packages on your system,
  13
  14 ```
  15 $ go get -u cloud.google.com/go/...
  16 ```
  17
  18 **NOTE:** These packages are under development, and may occasionally make
  19 backwards-incompatible changes.
  20
  21 **NOTE:** Github repo is a mirror of [https://code.googlesource.com/gocloud](https://code.googlesource.com/gocloud).
  22
  23 ## News
  24
  25 _December 5, 2016_
  26
  27 More changes to BigQuery:
  28
  29 * The `ValueList` type was removed. It is no longer necessary. Instead of
  30    ```go
  31    var v ValueList
  32    ... it.Next(&v) ..
  33    ```
  34    use
  35
  36    ```go
  37    var v []Value
  38    ... it.Next(&v) ...
  39    ```
  40
  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.
  43
  44 * Schema inference will infer the SQL type BYTES for a struct field of
  45   type []byte. Previously it inferred STRING.
  46
  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.
  50
  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`
  53   package.
  54
  55 _November 17, 2016_
  56
  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.
  59
  60 _November 8, 2016_
  61
  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.
  65 ```go
  66 type State struct {
  67   Cities  []struct{
  68     Populations []int
  69   }
  70 }
  71 ```
  72
  73 See [the announcement](https://groups.google.com/forum/#!topic/google-api-go-announce/79jtrdeuJAg) for
  74 more details.
  75
  76 _November 8, 2016_
  77
  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
  80 and renamed.
  81
  82 * The WithNamespace function has been removed. To specify a namespace in a Query, use the Query.Namespace method:
  83   ```go
  84   q := datastore.NewQuery("Kind").Namespace("ns")
  85   ```
  86
  87 * All the fields of Key are exported. That means you can construct any Key with a struct literal:
  88   ```go
  89   k := &Key{Kind: "Kind",  ID: 37, Namespace: "ns"}
  90   ```
  91
  92 * As a result of the above, the Key methods Kind, ID, d.Name, Parent, SetParent and Namespace have been removed.
  93
  94 * `NewIncompleteKey` has been removed, replaced by `IncompleteKey`. Replace
  95   ```go
  96   NewIncompleteKey(ctx, kind, parent)
  97   ```
  98   with
  99   ```go
 100   IncompleteKey(kind, parent)
 101   ```
 102   and if you do use namespaces, make sure you set the namespace on the returned key.
 103
 104 * `NewKey` has been removed, replaced by `NameKey` and `IDKey`. Replace
 105   ```go
 106   NewKey(ctx, kind, name, 0, parent)
 107   NewKey(ctx, kind, "", id, parent)
 108   ```
 109   with
 110   ```go
 111   NameKey(kind, name, parent)
 112   IDKey(kind, id, parent)
 113   ```
 114   and if you do use namespaces, make sure you set the namespace on the returned key.
 115
 116 * The `Done` variable has been removed. Replace `datastore.Done` with `iterator.Done`, from the package `google.golang.org/api/iterator`.
 117
 118 * The `Client.Close` method will have a return type of error. It will return the result of closing the underlying gRPC connection.
 119
 120 See [the announcement](https://groups.google.com/forum/#!topic/google-api-go-announce/hqXtM_4Ix-0) for
 121 more details.
 122
 123 _October 27, 2016_
 124
 125 Breaking change to bigquery: `NewGCSReference` is now a function,
 126 not a method on `Client`.
 127
 128 New bigquery feature: `Table.LoaderFrom` now accepts a `ReaderSource`, enabling
 129 loading data into a table from a file or any `io.Reader`.
 130
 131 _October 21, 2016_
 132
 133 Breaking change to pubsub: removed `pubsub.Done`.
 134
 135 Use `iterator.Done` instead, where `iterator` is the package
 136 `google.golang.org/api/iterator`.
 137
 138
 139 [Older news](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/master/old-news.md)
 140
 141 ## Supported APIs
 142
 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]
 154
 155
 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.
 159 >
 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.
 163 >
 164 > **Stable status**: the API is mature and ready for production use. We will
 165 > continue addressing bugs and feature requests.
 166
 167 Documentation and examples are available at
 168 https://godoc.org/cloud.google.com/go
 169
 170 Visit or join the
 171 [google-api-go-announce group](https://groups.google.com/forum/#!forum/google-api-go-announce)
 172 for updates on these packages.
 173
 174 ## Go Versions Supported
 175
 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).
 180
 181 ## Authorization
 182
 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.
 186
 187 To authorize using a
 188 [JSON key file](https://cloud.google.com/iam/docs/managing-service-account-keys),
 189 pass
 190 [`option.WithServiceAccountFile`](https://godoc.org/google.golang.org/api/option#WithServiceAccountFile)
 191 to the `NewClient` function of the desired package. For example:
 192
 193 ```go
 194 client, err := storage.NewClient(ctx, option.WithServiceAccountFile("path/to/keyfile.json"))
 195 ```
 196
 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:
 202 ```go
 203 tokenSource := ...
 204 client, err := storage.NewClient(ctx, option.WithTokenSource(tokenSource))
 205 ```
 206
 207 ## Cloud Datastore [![GoDoc](https://godoc.org/cloud.google.com/go/datastore?status.svg)](https://godoc.org/cloud.google.com/go/datastore)
 208
 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)
 214
 215 ### Example Usage
 216
 217 First create a `datastore.Client` to use throughout your application:
 218
 219 ```go
 220 client, err := datastore.NewClient(ctx, "my-project-id")
 221 if err != nil {
 222         log.Fatal(err)
 223 }
 224 ```
 225
 226 Then use that client to interact with the API:
 227
 228 ```go
 229 type Post struct {
 230         Title       string
 231         Body        string `datastore:",noindex"`
 232         PublishedAt time.Time
 233 }
 234 keys := []*datastore.Key{
 235         datastore.NewKey(ctx, "Post", "post1", 0, nil),
 236         datastore.NewKey(ctx, "Post", "post2", 0, nil),
 237 }
 238 posts := []*Post{
 239         {Title: "Post 1", Body: "...", PublishedAt: time.Now()},
 240         {Title: "Post 2", Body: "...", PublishedAt: time.Now()},
 241 }
 242 if _, err := client.PutMulti(ctx, keys, posts); err != nil {
 243         log.Fatal(err)
 244 }
 245 ```
 246
 247 ## Cloud Storage [![GoDoc](https://godoc.org/cloud.google.com/go/storage?status.svg)](https://godoc.org/cloud.google.com/go/storage)
 248
 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)
 253
 254 ### Example Usage
 255
 256 First create a `storage.Client` to use throughout your application:
 257
 258 ```go
 259 client, err := storage.NewClient(ctx)
 260 if err != nil {
 261         log.Fatal(err)
 262 }
 263 ```
 264
 265 ```go
 266 // Read the object1 from bucket.
 267 rc, err := client.Bucket("bucket").Object("object1").NewReader(ctx)
 268 if err != nil {
 269         log.Fatal(err)
 270 }
 271 defer rc.Close()
 272 body, err := ioutil.ReadAll(rc)
 273 if err != nil {
 274         log.Fatal(err)
 275 }
 276 ```
 277
 278 ## Cloud Pub/Sub [![GoDoc](https://godoc.org/cloud.google.com/go/pubsub?status.svg)](https://godoc.org/cloud.google.com/go/pubsub)
 279
 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)
 284
 285 ### Example Usage
 286
 287 First create a `pubsub.Client` to use throughout your application:
 288
 289 ```go
 290 client, err := pubsub.NewClient(ctx, "project-id")
 291 if err != nil {
 292         log.Fatal(err)
 293 }
 294 ```
 295
 296 ```go
 297 // Publish "hello world" on topic1.
 298 topic := client.Topic("topic1")
 299 msgIDs, err := topic.Publish(ctx, &pubsub.Message{
 300         Data: []byte("hello world"),
 301 })
 302 if err != nil {
 303         log.Fatal(err)
 304 }
 305
 306 // Create an iterator to pull messages via subscription1.
 307 it, err := client.Subscription("subscription1").Pull(ctx)
 308 if err != nil {
 309         log.Println(err)
 310 }
 311 defer it.Stop()
 312
 313 // Consume N messages from the iterator.
 314 for i := 0; i < N; i++ {
 315         msg, err := it.Next()
 316         if err == iterator.Done {
 317                 break
 318         }
 319         if err != nil {
 320                 log.Fatalf("Failed to retrieve message: %v", err)
 321         }
 322
 323         fmt.Printf("Message %d: %s\n", i, msg.Data)
 324         msg.Done(true) // Acknowledge that we've consumed the message.
 325 }
 326 ```
 327
 328 ## Cloud BigQuery [![GoDoc](https://godoc.org/cloud.google.com/go/bigquery?status.svg)](https://godoc.org/cloud.google.com/go/bigquery)
 329
 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)
 334
 335 ### Example Usage
 336
 337 First create a `bigquery.Client` to use throughout your application:
 338 ```go
 339 c, err := bigquery.NewClient(ctx, "my-project-ID")
 340 if err != nil {
 341     // TODO: Handle error.
 342 }
 343 ```
 344 Then use that client to interact with the API:
 345 ```go
 346 // Construct a query.
 347 q := c.Query(`
 348     SELECT year, SUM(number)
 349     FROM [bigquery-public-data:usa_names.usa_1910_2013]
 350     WHERE name = "William"
 351     GROUP BY year
 352     ORDER BY year
 353 `)
 354 // Execute the query.
 355 it, err := q.Read(ctx)
 356 if err != nil {
 357     // TODO: Handle error.
 358 }
 359 // Iterate through the results.
 360 for {
 361     var values bigquery.ValueList
 362     err := it.Next(&values)
 363     if err == iterator.Done {
 364         break
 365     }
 366     if err != nil {
 367         // TODO: Handle error.
 368     }
 369     fmt.Println(values)
 370 }
 371 ```
 372
 373
 374 ## Stackdriver Logging [![GoDoc](https://godoc.org/cloud.google.com/go/logging?status.svg)](https://godoc.org/cloud.google.com/go/logging)
 375
 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)
 380
 381 ### Example Usage
 382
 383 First create a `logging.Client` to use throughout your application:
 384
 385 ```go
 386 ctx := context.Background()
 387 client, err := logging.NewClient(ctx, "my-project")
 388 if err != nil {
 389     // TODO: Handle error.
 390 }
 391 ```
 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.
 394 ```go
 395 logger := client.Logger("my-log")
 396 logger.Log(logging.Entry{Payload: "something happened!"})
 397 ```
 398 Close your client before your program exits, to flush any buffered log entries.
 399 ```go
 400 err = client.Close()
 401 if err != nil {
 402     // TODO: Handle error.
 403 }
 404 ```
 405
 406 ## Contributing
 407
 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.
 412
 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.
 417
 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
 422
 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
 426
 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
 431
 432 [cloud-bigtable]: https://cloud.google.com/bigtable/
 433 [cloud-bigtable-ref]: https://godoc.org/cloud.google.com/go/bigtable
 434
 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
 438
 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
 442
 443 [cloud-vision]: https://cloud.google.com/vision/
 444 [cloud-vision-ref]: https://godoc.org/cloud.google.com/go/vision
 445
 446 [cloud-language]: https://cloud.google.com/natural-language
 447 [cloud-language-ref]: https://godoc.org/cloud.google.com/go/language/apiv1beta1
 448
 449 [cloud-speech]: https://cloud.google.com/speech
 450 [cloud-speech-ref]: https://godoc.org/cloud.google.com/go/speech/apiv1beta1
 451
 452 [default-creds]: https://developers.google.com/identity/protocols/application-default-credentials