Skip to content

Commit 984f6a9

Browse files
bshafferbshaffer
authored
adds service account, OAuth, general usage, and proxying to README (#972)
1 parent feab52d commit 984f6a9

File tree

2 files changed

+202
-3
lines changed

2 files changed

+202
-3
lines changed

‎README.md‎

Lines changed: 189 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
The Google API Client Library enables you to work with Google APIs such as Google+, Drive, or YouTube on your server.
77

88
## Beta ##
9-
This library is in Beta. We're comfortable enough with the stability and features of the library that we want you to build real production applications on it. We will make an effort to support the public and protected surface of the library and maintain backwards compatibility in the future. While we are still in Beta, we reserve the right to make incompatible changes. If we do remove some functionality (typically because better functionality exists or if the feature proved infeasible), our intention is to deprecate and provide ample time for developers to update their code.
9+
This library is in Beta. We're comfortable enough with the stability and features of the library that we want you to build real production applications on it. We will make an effort to support the public and protected surface of the library and maintain backwards compatibility in the future. While we are still in Beta, we reserve the right to make incompatible changes.
1010

1111
## Requirements ##
1212
* [PHP 5.4.0 or higher](http://www.php.net/)
@@ -49,8 +49,8 @@ require_once '/path/to/google-api-php-client/vendor/autoload.php';
4949

5050
For additional installation and setup instructions, see [the documentation](https://developers.google.com/api-client-library/php/start/installation).
5151

52-
## Basic Example ##
53-
See the examples/ directory for examples of the key client features. You can
52+
## Examples ##
53+
See the [`examples/`](examples) directory for examples of the key client features. You can
5454
view them in your browser by running the php built-in web server.
5555

5656
```
@@ -60,6 +60,8 @@ $ php -S localhost:8000 -t examples/
6060
And then browsing to the host and port you specified
6161
(in the above example, `http://localhost:8000`).
6262

63+
### Basic Example ###
64+
6365
```php
6466
// include your composer dependencies
6567
require_once 'vendor/autoload.php';
@@ -77,6 +79,171 @@ foreach ($results as $item) {
7779
}
7880
```
7981

82+
### Authentication with OAuth ###
83+
84+
> An example of this can be seen in [`examples/simple-file-upload.php`](examples/simple-file-upload.php).
85+
86+
**NOTE:** If you are using Google App Engine or Google Compute Engine, you can skip steps 1-3, as Application Default Credentials are included automatically when `useApplicationDefaultCredentials` is called.
87+
88+
1. Follow the instructions to [Create Web Application Credentials](https://developers.google.com/api-client-library/php/auth/web-app#creatingcred)
89+
1. Download the JSON credentials
90+
1. Set the path to these credentials using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
91+
92+
```php
93+
putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
94+
```
95+
96+
1. Tell the Google client to use your service account credentials to authenticate:
97+
98+
```php
99+
$client = new Google_Client();
100+
$client->useApplicationDefaultCredentials();
101+
```
102+
103+
1. If you have delegated domain-wide access to the service account and you want to impersonate a user account, specify the email address of the user account using the method setSubject:
104+
105+
```php
106+
$ client->setSubject($user_to_impersonate);
107+
```
108+
109+
### Authentication with Service Accounts ###
110+
111+
> An example of this can be seen in [`examples/service-account.php`](examples/service-account.php).
112+
113+
1. Follow the instructions to [Create a Service Account](https://developers.google.com/api-client-library/php/auth/service-accounts#creatinganaccount)
114+
1. Download the JSON credentials
115+
1. Set the path to these credentials using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
116+
117+
```php
118+
putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
119+
```
120+
121+
1. Tell the Google client to use your service account credentials to authenticate:
122+
123+
```php
124+
$client = new Google_Client();
125+
$client->useApplicationDefaultCredentials();
126+
```
127+
128+
1. Set the scopes required for the API you are going to call
129+
130+
```php
131+
$client->addScope(Google_Service_Drive::DRIVE);
132+
```
133+
134+
1. If you have delegated domain-wide access to the service account and you want to impersonate a user account, specify the email address of the user account using the method setSubject:
135+
136+
```php
137+
$client->setSubject($user_to_impersonate);
138+
```
139+
140+
### Making Requests ###
141+
142+
The classes used to call the API in [google-api-php-client-services](https://github.com/Google/google-api-php-client-services) are autogenerated. They map directly to the JSON requests and responses found in the [APIs Explorer](https://developers.google.com/apis-explorer/#p/).
143+
144+
A JSON request to the [Datastore API](https://developers.google.com/apis-explorer/#p/datastore/v1beta3/datastore.projects.runQuery) would look like this:
145+
146+
```json
147+
POST https://datastore.googleapis.com/v1beta3/projects/YOUR_PROJECT_ID:runQuery?key=YOUR_API_KEY
148+
149+
{
150+
"query": {
151+
"kind": [{
152+
"name": "Book"
153+
}],
154+
"order": [{
155+
"property": {
156+
"name": "title"
157+
},
158+
"direction": "descending"
159+
}],
160+
"limit": 10
161+
}
162+
}
163+
```
164+
165+
Using this library, the same call would look something like this:
166+
167+
```php
168+
// create the datastore service class
169+
$datastore = new Google_Service_Datastore($client)
170+
171+
// build the query - this maps directly to the JSON
172+
$query = new Google_Service_Datastore_Query([
173+
'kind' => [
174+
[
175+
'name' => 'Book',
176+
],
177+
],
178+
'order' => [
179+
'property' => [
180+
'name' => 'title',
181+
],
182+
'direction' => 'descending',
183+
],
184+
'limit' => 10,
185+
]);
186+
187+
// build the request and response
188+
$request = new Google_Service_Datastore_RunQueryRequest(['query' => $query]);
189+
$response = $datastore->projects->runQuery('YOUR_DATASET_ID', $request);
190+
```
191+
192+
However, as each property of the JSON API has a corresponding generated class, the above code could also be written lile this:
193+
194+
```php
195+
// create the datastore service class
196+
$datastore = new Google_Service_Datastore($client)
197+
198+
// build the query
199+
$request = new Google_Service_Datastore_RunQueryRequest();
200+
$query = new Google_Service_Datastore_Query();
201+
// - set the order
202+
$order = new Google_Service_Datastore_PropertyOrder();
203+
$order->setDirection('descending');
204+
$property = new Google_Service_Datastore_PropertyReference();
205+
$property->setName('title');
206+
$order->setProperty($property);
207+
$query->setOrder([$order]);
208+
// - set the kinds
209+
$kind = new Google_Service_Datastore_KindExpression();
210+
$kind->setName('Book');
211+
$query->setKinds([$kind]);
212+
// - set the limit
213+
$query->setLimit(10);
214+
215+
// add the query to the request and make the request
216+
$request->setQuery($query);
217+
$response = $datastore->projects->runQuery('YOUR_DATASET_ID', $request);
218+
```
219+
220+
The method used is a matter of preference, but *it will be very difficult to use this library without first understanding the JSON syntax for the API*, so it is recommended to look at the [APIs Explorer](https://developers.google.com/apis-explorer/#p/) before using any of the services here.
221+
222+
### Making HTTP Requests Directly ###
223+
224+
If Google Authentication is desired for external applications, or a Google API is not available yet in this library, HTTP requests can be made directly.
225+
226+
The `authorize` method returns an authorized [Guzzle Client](http://docs.guzzlephp.org/), so any request made using the client will contain the corresponding authorization.
227+
228+
```php
229+
// create the Google client
230+
$client = new Google_Client();
231+
232+
/**
233+
* Set your method for authentication. Depending on the API, This could be
234+
* directly with an access token, API key, or (recommended) using
235+
* Application Default Credentials.
236+
*/
237+
$client->useApplicationDefaultCredentials();
238+
$client->addScope(Google_Service_Plus::PLUS_ME);
239+
240+
// returns a Guzzle HTTP Client
241+
$httpClient = $client->authorize();
242+
243+
// make an HTTP request
244+
$response = $httpClient->get('https://www.googleapis.com/plus/v1/people/me');
245+
```
246+
80247
### Caching ###
81248

82249
It is recommended to use another caching library to improve performance. This can be done by passing a [PSR-6](http://www.php-fig.org/psr/psr-6/) compatible library to the client:
@@ -104,6 +271,25 @@ $tokenCallback = function ($cacheKey, $accessToken) use ($logger) {
104271
$client->setTokenCallback($tokenCallback);
105272
```
106273

274+
### Debugging Your HTTP Request using Charles ###
275+
276+
It is often very useful to debug your API calls by viewing the raw HTTP request. This library supports the use of [Charles Web Proxy](https://www.charlesproxy.com/documentation/getting-started/). Download and run Charles, and then capture all HTTP traffic through Charles with the following code:
277+
278+
```php
279+
// FOR DEBUGGING ONLY
280+
$httpClient = new GuzzleHttp\Client([
281+
'proxy' => 'localhost:8888', // by default, Charles runs on localhost port 8888
282+
'verify' => false, // otherwise HTTPS requests will fail.
283+
]);
284+
285+
$client = new Google_Client();
286+
$client->setHttpClient($httpClient);
287+
```
288+
289+
Now all calls made by this library will appear in the Charles UI.
290+
291+
One additional step is required in Charles to view SSL requests. Go to **Charles > Proxy > SSL Proxying Settings** and add the domain you'd like captured. In the case of the Google APIs, this is usually `*.googleapis.com`.
292+
107293
### Service Specific Examples ###
108294

109295
YouTube: https://github.com/youtube/api-samples/tree/master/php

‎examples/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Examples for Google APIs Client Library for PHP #
2+
3+
## How to run the examples ##
4+
5+
1. Following the [Installation Instructions](../README.md#installation)
6+
1. Run the PHP built-in web server. Supply the `-t` option to point to this directory:
7+
8+
```
9+
$ php -S localhost:8000 -t examples/
10+
```
11+
12+
1. Point your browser to the host and port you specified, i.e `http://localhost:8000`.
13+

0 commit comments

Comments
 (0)