adds service account, OAuth, general usage, and proxying to README (#972

)
googleapis · Jun 24, 2016 · 984f6a9 · 984f6a9
1 parent feab52d
commit 984f6a9
Show file tree

Hide file tree

Showing 2 changed files with 202 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 The Google API Client Library enables you to work with Google APIs such as Google+, Drive, or YouTube on your server.
 
 ## Beta ##
-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.
+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.
 
 ## Requirements ##
 * [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';
 
 For additional installation and setup instructions, see [the documentation](https://developers.google.com/api-client-library/php/start/installation).
 
-## Basic Example ##
-See the examples/ directory for examples of the key client features. You can
+## Examples ##
+See the [`examples/`](examples) directory for examples of the key client features. You can
 view them in your browser by running the php built-in web server.
 
 ```
@@ -60,6 +60,8 @@ $ php -S localhost:8000 -t examples/
 And then browsing to the host and port you specified
 (in the above example, `http://localhost:8000`).
 
+### Basic Example ###
+
 ```php
 // include your composer dependencies
 require_once 'vendor/autoload.php';
@@ -77,6 +79,171 @@ foreach ($results as $item) {
 }
 ```
 
+### Authentication with OAuth ###
+
+> An example of this can be seen in [`examples/simple-file-upload.php`](examples/simple-file-upload.php).
+
+**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.
+
+1. Follow the instructions to [Create Web Application Credentials](https://developers.google.com/api-client-library/php/auth/web-app#creatingcred)
+1. Download the JSON credentials
+1. Set the path to these credentials using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
+
+    ```php
+    putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
+    ```
+
+1. Tell the Google client to use your service account credentials to authenticate:
+
+    ```php
+    $client = new Google_Client();
+    $client->useApplicationDefaultCredentials();
+    ```
+
+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:
+
+    ```php
+    $   client->setSubject($user_to_impersonate);
+    ```
+
+### Authentication with Service Accounts ###
+
+> An example of this can be seen in [`examples/service-account.php`](examples/service-account.php).
+
+1. Follow the instructions to [Create a Service Account](https://developers.google.com/api-client-library/php/auth/service-accounts#creatinganaccount)
+1. Download the JSON credentials
+1. Set the path to these credentials using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
+
+    ```php
+    putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
+    ```
+
+1. Tell the Google client to use your service account credentials to authenticate:
+
+    ```php
+    $client = new Google_Client();
+    $client->useApplicationDefaultCredentials();
+    ```
+
+1. Set the scopes required for the API you are going to call
+
+    ```php
+    $client->addScope(Google_Service_Drive::DRIVE);
+    ```
+
+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:
+
+    ```php
+    $client->setSubject($user_to_impersonate);
+    ```
+
+### Making Requests ###
+
+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/).
+
+A JSON request to the [Datastore API](https://developers.google.com/apis-explorer/#p/datastore/v1beta3/datastore.projects.runQuery) would look like this:
+
+```json
+POST https://datastore.googleapis.com/v1beta3/projects/YOUR_PROJECT_ID:runQuery?key=YOUR_API_KEY
+
+{
+    "query": {
+        "kind": [{
+            "name": "Book"
+        }],
+        "order": [{
+            "property": {
+                "name": "title"
+            },
+            "direction": "descending"
+        }],
+        "limit": 10
+    }
+}
+```
+
+Using this library, the same call would look something like this:
+
+```php
+// create the datastore service class
+$datastore = new Google_Service_Datastore($client)
+
+// build the query - this maps directly to the JSON
+$query = new Google_Service_Datastore_Query([
+    'kind' => [
+        [
+            'name' => 'Book',
+        ],
+    ],
+    'order' => [
+        'property' => [
+            'name' => 'title',
+        ],
+        'direction' => 'descending',
+    ],
+    'limit' => 10,
+]);
+
+// build the request and response
+$request = new Google_Service_Datastore_RunQueryRequest(['query' => $query]);
+$response = $datastore->projects->runQuery('YOUR_DATASET_ID', $request);
+```
+
+However, as each property of the JSON API has a corresponding generated class, the above code could also be written lile this:
+
+```php
+// create the datastore service class
+$datastore = new Google_Service_Datastore($client)
+
+// build the query
+$request = new Google_Service_Datastore_RunQueryRequest();
+$query = new Google_Service_Datastore_Query();
+//   - set the order
+$order = new Google_Service_Datastore_PropertyOrder();
+$order->setDirection('descending');
+$property = new Google_Service_Datastore_PropertyReference();
+$property->setName('title');
+$order->setProperty($property);
+$query->setOrder([$order]);
+//   - set the kinds
+$kind = new Google_Service_Datastore_KindExpression();
+$kind->setName('Book');
+$query->setKinds([$kind]);
+//   - set the limit
+$query->setLimit(10);
+
+// add the query to the request and make the request
+$request->setQuery($query);
+$response = $datastore->projects->runQuery('YOUR_DATASET_ID', $request);
+```
+
+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.
+
+### Making HTTP Requests Directly ###
+
+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.
+
+The `authorize` method returns an authorized [Guzzle Client](http://docs.guzzlephp.org/), so any request made using the client will contain the corresponding authorization.
+
+```php
+// create the Google client
+$client = new Google_Client();
+
+/**
+ * Set your method for authentication. Depending on the API, This could be
+ * directly with an access token, API key, or (recommended) using
+ * Application Default Credentials.
+ */
+$client->useApplicationDefaultCredentials();
+$client->addScope(Google_Service_Plus::PLUS_ME);
+
+// returns a Guzzle HTTP Client
+$httpClient = $client->authorize();
+
+// make an HTTP request
+$response = $httpClient->get('https://www.googleapis.com/plus/v1/people/me');
+```
+
 ### Caching ###
 
 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) {
 $client->setTokenCallback($tokenCallback);
 ```
 
+### Debugging Your HTTP Request using Charles ###
+
+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:
+
+```php
+// FOR DEBUGGING ONLY
+$httpClient = new GuzzleHttp\Client([
+    'proxy' => 'localhost:8888', // by default, Charles runs on localhost port 8888
+    'verify' => false, // otherwise HTTPS requests will fail.
+]);
+
+$client = new Google_Client();
+$client->setHttpClient($httpClient);
+```
+
+Now all calls made by this library will appear in the Charles UI.
+
+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`.
+
 ### Service Specific Examples ###
 
 YouTube: https://github.com/youtube/api-samples/tree/master/php

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,13 @@
+# Examples for Google APIs Client Library for PHP #
+
+## How to run the examples ##
+
+1. Following the [Installation Instructions](../README.md#installation)
+1. Run the PHP built-in web server. Supply the `-t` option to point to this directory:
+
+    ```
+    $ php -S localhost:8000 -t examples/
+    ```
+
+1. Point your browser to the host and port you specified, i.e `http://localhost:8000`.
+