1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
# 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/main/).
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 (
"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/main/examples/urlshortener.go)
in the [examples directory](https://github.com/google/google-api-go-client/tree/main/examples/).
(the examples use some functions in `main.go` in the same directory)
## Error Handling
Most errors returned by the `Do` methods of these clients will be of type
[`googleapi.Error`](https://godoc.org/google.golang.org/api/googleapi#Error).
Use a type assertion to obtain the HTTP status code and other properties of the
error:
```go
url, err := svc.Url.Get(shortURL).Do()
if err != nil {
if e, ok := err.(*googleapi.Error); ok && e.Code == http.StatusNotFound {
...
}
}
```
|
