mirror of
https://github.com/fnproject/fn.git
synced 2022-10-28 21:29:17 +03:00
9eaf824398
* add jaeger support, link hot container & req span * adds jaeger support now with FN_JAEGER_URL, there's a simple tutorial in the operating/metrics.md file now and it's pretty easy to get up and running. * links a hot request span to a hot container span. when we change this to sample at a lower ratio we'll need to finagle the hot container span to always sample or something, otherwise we'll hide that info. at least, since we're sampling at 100% for now if this is flipped on, can see freeze/unfreeze etc. if they hit. this is useful for debugging. note that zipkin's exporter does not follow the link at all, hence jaeger... and they're backed by the Cloud Empire now (CNCF) so we'll probably use it anyway. * vendor: add thrift for jaeger
131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# Getting Started with the Google APIs for Go
|
|
|
|
## Getting Started
|
|
|
|
This is a quick walk-through of how to get started with the Google APIs for Go.
|
|
|
|
## Background
|
|
|
|
The first thing to understand is that the Google API libraries are auto-generated for
|
|
each language, including Go, so they may not feel like 100% natural for any language.
|
|
The Go versions are pretty natural, but please forgive any small non-idiomatic things.
|
|
(Suggestions welcome, though!)
|
|
|
|
## Installing
|
|
|
|
Pick an API and a version of that API to install.
|
|
You can find the complete list by looking at the
|
|
[directories here](https://github.com/google/google-api-go-client/tree/master/).
|
|
|
|
For example, let's install the
|
|
[urlshortener's version 1 API](https://godoc.org/google.golang.org/api/urlshortener/v1):
|
|
|
|
```
|
|
$ go get -u google.golang.org/api/urlshortener/v1
|
|
```
|
|
|
|
Now it's ready for use in your code.
|
|
|
|
## Using
|
|
|
|
Once you've installed a library, you import it like this:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"golang.org/x/net/context"
|
|
"golang.org/x/oauth2"
|
|
"golang.org/x/oauth2/google"
|
|
"google.golang.org/api/urlshortener/v1"
|
|
)
|
|
```
|
|
|
|
The package name, if you don't override it on your import line, is the name of the
|
|
API without the version number. In the case above, just `urlshortener`.
|
|
|
|
## Instantiating
|
|
|
|
Each API has a `New` function taking an `*http.Client` and returning an API-specific `*Service`.
|
|
|
|
You create the service like:
|
|
|
|
```go
|
|
svc, err := urlshortener.New(httpClient)
|
|
```
|
|
|
|
## OAuth HTTP Client
|
|
|
|
The HTTP client you pass in to the service must be one that automatically adds
|
|
Google-supported Authorization information to the requests.
|
|
|
|
There are several ways to do authentication. They will all involve the package
|
|
[golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2) in some way.
|
|
|
|
### 3-legged OAuth
|
|
|
|
For 3-legged OAuth (your application redirecting a user through a website to get a
|
|
token giving your application access to that user's resources), you will need to
|
|
create an oauth2.Config,
|
|
|
|
|
|
```go
|
|
var config = &oauth2.Config{
|
|
ClientID: "", // from https://console.developers.google.com/project/<your-project-id>/apiui/credential
|
|
ClientSecret: "", // from https://console.developers.google.com/project/<your-project-id>/apiui/credential
|
|
Endpoint: google.Endpoint,
|
|
Scopes: []string{urlshortener.UrlshortenerScope},
|
|
}
|
|
```
|
|
|
|
... and then use the AuthCodeURL, Exchange, and Client methods on it.
|
|
For an example, see: https://godoc.org/golang.org/x/oauth2#example-Config
|
|
|
|
For the redirect URL, see
|
|
https://developers.google.com/identity/protocols/OAuth2InstalledApp#choosingredirecturi
|
|
|
|
### Service Accounts
|
|
|
|
To use a Google service account, or the GCE metadata service, see
|
|
the [golang.org/x/oauth2/google](https://godoc.org/golang.org/x/oauth2/google) package.
|
|
In particular, see [google.DefaultClient](https://godoc.org/golang.org/x/oauth2/google#DefaultClient).
|
|
|
|
### Using API Keys
|
|
|
|
Some APIs require passing API keys from your application.
|
|
To do this, you can use
|
|
[transport.APIKey](https://godoc.org/google.golang.org/api/googleapi/transport#APIKey):
|
|
|
|
```go
|
|
ctx := context.WithValue(context.Background(), oauth2.HTTPClient, &http.Client{
|
|
Transport: &transport.APIKey{Key: developerKey},
|
|
})
|
|
oauthConfig := &oauth2.Config{ .... }
|
|
var token *oauth2.Token = .... // via cache, or oauthConfig.Exchange
|
|
httpClient := oauthConfig.Client(ctx, token)
|
|
svc, err := urlshortener.New(httpClient)
|
|
...
|
|
```
|
|
|
|
## Using the Service
|
|
|
|
Each service contains zero or more methods and zero or more sub-services.
|
|
The sub-services related to a specific type of "Resource".
|
|
|
|
Those sub-services then contain their own methods.
|
|
|
|
For instance, the urlshortener API has just the "Url" sub-service:
|
|
|
|
```go
|
|
url, err := svc.Url.Get(shortURL).Do()
|
|
if err != nil {
|
|
...
|
|
}
|
|
fmt.Printf("The URL %s goes to %s\n", shortURL, url.LongUrl)
|
|
```
|
|
|
|
For a more complete example, see
|
|
[urlshortener.go](https://github.com/google/google-api-go-client/tree/master/examples/urlshortener.go)
|
|
in the [examples directory](https://github.com/google/google-api-go-client/tree/master/examples/).
|
|
(the examples use some functions in `main.go` in the same directory)
|