Skip to content

Commit

Permalink
docs: add some general package docs for popular questions (#867)
Browse files Browse the repository at this point in the history 
- Details on ForceSendFields.
- How to cast an error for more details.
- Update README formatting and link to package docs.
  • Loading branch information
@codyoss
codyoss committed Feb 11, 2021
1 parent e912f19 commit b681d90
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 57 deletions.
90 changes: 33 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Getting Started

```
```shell
$ go get google.golang.org/api/tasks/v1
$ go get google.golang.org/api/moderator/v1
$ go get google.golang.org/api/urlshortener/v1
Expand All @@ -15,91 +15,67 @@ and using:
package main

import (
"net/http"
"net/http"

"google.golang.org/api/urlshortener/v1"
"google.golang.org/api/urlshortener/v1"
)

func main() {
svc, err := urlshortener.New(http.DefaultClient)
// ...
ctx := context.Backgroud()
svc, err := urlshortener.NewService(ctx)
// ...
}
```

* For a longer tutorial, see the [Getting Started guide](https://github.com/google/google-api-go-client/blob/master/GettingStarted.md).
* For examples, see the [examples directory](https://github.com/google/google-api-go-client/tree/master/examples).
* For support, use the [golang-nuts](https://groups.google.com/group/golang-nuts) mailing list.
* The code review instance may be found [here](https://code-review.googlesource.com).

## Status
[![Go Reference](https://pkg.go.dev/badge/google.golang.org/api.svg)](https://pkg.go.dev/google.golang.org/api)

These are auto-generated Go libraries from the Google Discovery Service's JSON description files of the available "new style" Google APIs.

Due to the auto-generated nature of this collection of libraries, complete APIs or specific versions can appear or go away without notice.
As a result, you should always locally vendor any API(s) that your code relies upon.

These client libraries are officially supported by Google. However, the libraries are considered complete and are in maintenance mode. This means that we will address critical bugs and security issues but will not add any new features.
[![Go Reference](https://pkg.go.dev/badge/google.golang.org/api.svg)](https://pkg.go.dev/google.golang.org/api)

If you're working with Google Cloud Platform APIs such as Datastore or Pub/Sub,
consider using the
[Cloud Client Libraries for Go](https://github.com/googleapis/google-cloud-go)
instead. These are the new and
idiomatic Go libraries targeted specifically at Google Cloud Platform Services.
These are auto-generated Go libraries from the Google Discovery Service's JSON description files.

The generator itself and the code it produces are beta. Some APIs are
alpha/beta, and indicated as such in the import path (e.g.,
"google.golang.org/api/someapi/v1alpha").
Due to the auto-generated nature of this collection of libraries they may contain breaking changes from one release to
the next. The generator itself and the code it produces are considered beta for this reason.

## Application Default Credentials Example
These client libraries are officially supported by Google. However, the libraries are considered complete and are in
maintenance mode. This means that we will address critical bugs and security issues but will not add any new features.

Application Default Credentials provide a simplified way to obtain credentials
for authenticating with Google APIs.
If you're working with Google Cloud Platform APIs such as Datastore or Pub/Sub, please use the
[Cloud Client Libraries for Go](https://github.com/googleapis/google-cloud-go) instead. These are the new and idiomatic
Go libraries targeted specifically at Google Cloud Platform Services.

The Application Default Credentials authenticate as the application itself,
which make them great for working with Google Cloud APIs like Storage or
Datastore. They are the recommended form of authentication when building
applications that run on Google Compute Engine or Google App Engine.
## Authorization

Default credentials are provided by the `golang.org/x/oauth2/google` package. To use them, add the following import:
By default, each API will use [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
for authorization credentials used in calling the API endpoints. This will allow your application to run in many
environments without requiring explicit configuration.

```go
import "golang.org/x/oauth2/google"
// import "google.golang.org/api/sheets/v4"
client, err := sheets.NewService(ctx)
```

Some credentials types require you to specify scopes, and service entry points may not inject them. If you encounter this situation you may need to specify scopes as follows:
To authorize using a [JSON key file](https://cloud.google.com/iam/docs/managing-service-account-keys), pass
[`option.WithCredentialsFile`](https://pkg.go.dev/google.golang.org/api/option#WithCredentialsFile) to the `NewService`
function of the desired package. For example:

```go
import (
"context"
"golang.org/x/oauth2/google"
"google.golang.org/api/compute/v1"
)

func main() {
// Use oauth2.NoContext if there isn't a good context to pass in.
ctx := context.Background()

client, err := google.DefaultClient(ctx, compute.ComputeScope)
if err != nil {
//...
}
computeService, err := compute.New(client)
if err != nil {
//...
}
}
client, err := sheets.NewService(ctx, option.WithCredentialsFile("path/to/keyfile.json"))
```

If you need a `oauth2.TokenSource`, use the `DefaultTokenSource` function:
You can exert more control over authorization by using the [`golang.org/x/oauth2`](https://pkg.go.dev/golang.org/x/oauth2)
package to create an `oauth2.TokenSource`. Then pass [`option.WithTokenSource`](https://pkg.go.dev/google.golang.org/api/option#WithTokenSource)
to the `NewService` function:

```go
ts, err := google.DefaultTokenSource(ctx, scope1, scope2, ...)
if err != nil {
//...
}
client := oauth2.NewClient(ctx, ts)
tokenSource := ...
svc, err := sheets.NewService(ctx, option.WithTokenSource(tokenSource))
```

See also: [golang.org/x/oauth2/google](https://godoc.org/golang.org/x/oauth2/google) package documentation.
## More information

For some more information related to all of the generated clients please read through our
[package documentation](https://pkg.go.dev/google.golang.org/api#section-documentation).
23 changes: 23 additions & 0 deletions doc.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,27 @@
// To see the exact type of int that the API expects, you can inspect the API's
// discovery doc. A global catalogue pointing to the discovery doc of APIs can
// be found at https://www.googleapis.com/discovery/v1/apis.
//
//
// ForceSendFields
//
// This field can be found on all Request/Response structs in the generated
// clients. All of these types have the JSON `omitempty` field tag present on
// their fields. This means if a type is set to its default value it will not be
// marshalled. Sometimes you may actually want to send a default value, for
// instance sending an int of `0`. In this case you can override the `omitempty`
// feature by adding the field name to the `ForceSendFields` slice. See docs on
// any struct for more details.
//
//
// Inspecting errors
//
// All of the errors returned by a client's `Do` method may be cast to a
// `*googleapis.Error`. This can be useful for getting more information on an
// error while debugging.
// if _, err := svc.FooCall().Do(); err != nil {
// gErr, ok := err.(*googleapi.Error); ok {
// fmt.Println("Status code: %v", gErr.Code)
// }
// }
package api

0 comments on commit b681d90

Please sign in to comment.