Merge pull request #391 from ryanseys/rs--readme

Improve authorization in README

README.md

@@ -32,10 +32,22 @@ $ npm install --save gcloud
 
 ## Authorization
 
+With `gcloud-node` it's incredibly easy to get authorized and start using Google's APIs. You can set your credentials on a global basis as well as on a per-API basis. See each individual API section below to see how you can auth on a per-API-basis. This is useful if you want to use different accounts for different Google Cloud services.
+
 ### On Google Compute Engine
 
 If you are running this client on Google Compute Engine, we handle authorization for you with no configuration. You just need to make sure that when you [set up the GCE instance][gce-how-to], you add the correct scopes for the APIs you want to access.
 
+``` js
+// Authorizing on a global basis.
+var projectId = process.env.GCLOUD_PROJECT_ID; // E.g. 'grape-spaceship-123'
+var gcloud = require('gcloud')({
+  projectId: projectId
+});
+
+// ...you're good to go! See the next section to get started using the APIs.
+```
+
 ### Elsewhere
 
 If you are not running this client on Google Compute Engine, you need a Google Developers service account. To create a service account:
@@ -50,6 +62,20 @@ If you are not running this client on Google Compute Engine, you need a Google D
   * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests.
   * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file.
 
+``` js
+// Authorizing on a global basis.
+var projectId = process.env.GCLOUD_PROJECT_ID; // E.g. 'grape-spaceship-123'
+
+var gcloud = require('gcloud')({
+  projectId: projectId,
+  keyFilename: '/path/to/keyfile.json'
+});
+
+// ...you're good to go! See the next section to get started using the APIs.
+```
+
+You can also set auth on a per-API-instance basis. The examples below show you how.
+
 ## Google BigQuery
 
 Analyze Big Data in the cloud with [Google BigQuery][cloud-bigquery] ([docs][cloud-bigquery-docs]) . Run fast, SQL-like queries against multi-terabyte datasets in seconds. Scalable and easy to use, BigQuery gives you real-time insights about your data.
@@ -60,6 +86,9 @@ See the [gcloud-node BigQuery API documentation][gcloud-bigquery-docs] to learn
 var gcloud = require('gcloud');
 var bigquery;
 
+// Authorizing on a per-API-basis. You don't need to do this if you
+// auth on a global basis (see Authorization section above).
+
 // From Google Compute Engine:
 bigquery = gcloud.bigquery({
   projectId: 'my-project'
@@ -102,6 +131,9 @@ See the [gcloud-node Datastore API documentation][gcloud-datastore-docs] to lear
 var gcloud = require('gcloud');
 var dataset;
 
+// Authorizing on a per-API-basis. You don't need to do this if you
+// auth on a global basis (see Authorization section above).
+
 // From Google Compute Engine:
 dataset = gcloud.datastore.dataset({
   projectId: 'my-project'
@@ -129,6 +161,9 @@ var fs = require('fs');
 var gcloud = require('gcloud');
 var storage;
 
+// Authorizing on a per-API-basis. You don't need to do this if you
+// auth on a global basis (see Authorization section above).
+
 // From Google Compute Engine:
 storage = gcloud.storage({
   projectId: 'my-project'
@@ -165,6 +200,9 @@ See the [gcloud-node Pub/Sub API documentation][gcloud-pubsub-docs] to learn how
 var gcloud = require('gcloud');
 var pubsub;
 
+// Authorizing on a per-API-basis. You don't need to do this if you
+// auth on a global basis (see Authorization section above).
+
 // From Google Compute Engine:
 pubsub = gcloud.pubsub();