From 27a3d578703840ab9bcece4b201c0d8a36013fd3 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Mon, 27 Apr 2015 10:22:11 -0400 Subject: [PATCH] add authorization guide + links to Google docs fixes #483 fixes #479 --- docs/authorization.md | 52 +++++++++++++++++++ docs/index.html | 1 + .../authorization/authorization.html | 19 +++++++ .../components/authorization/authorization.js | 15 ++++++ docs/site/components/docs/docs.html | 48 +++++------------ docs/site/components/subpage/subpage.html | 5 ++ docs/site/css/main.css | 7 +++ docs/site/home.js | 1 + lib/bigquery/index.js | 19 +------ lib/datastore/dataset.js | 12 ++--- lib/datastore/index.js | 20 ++----- lib/index.js | 41 +-------------- lib/pubsub/index.js | 25 +-------- lib/storage/index.js | 19 ++----- 14 files changed, 134 insertions(+), 150 deletions(-) create mode 100644 docs/authorization.md create mode 100644 docs/site/components/authorization/authorization.html create mode 100644 docs/site/components/authorization/authorization.js diff --git a/docs/authorization.md b/docs/authorization.md new file mode 100644 index 00000000000..bbb93da1505 --- /dev/null +++ b/docs/authorization.md @@ -0,0 +1,52 @@ +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 +var config = { + projectId: 'grape-spaceship-123' +}; + +var gcloud = require('gcloud')(config); +``` + +## Elsewhere + +If you are not running this client on Google Compute Engine, you need a Google Developers service account. To create a service account: + +1. Visit the [Google Developers Console][dev-console]. +2. Create a new project or click on an existing project. +3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services): + * Google Cloud Datastore API + * Google Cloud Storage + * Google Cloud Storage JSON API +4. Navigate to **APIs & auth** > **Credentials** and then: + * 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 +var config = { + projectId: 'grape-spaceship-123', + keyFilename: '/path/to/keyfile.json' +}; + +var gcloud = require('gcloud')(config); +``` + +### The `config` object + +A `config` object requires the following properties: + +1. `projectId` + +2. One of the following: + 1. `config.credentials` object containing `client_email` and `private_key` properties. + 2. `config.keyFilename` path to a .json, .pem, or .p12 key file. + 3. `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a full path to your key file. + +**Note**: When using a .pem or .p12 key file, `config.email` is also required. + +[dev-console]: https://console.developers.google.com/project +[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using diff --git a/docs/index.html b/docs/index.html index 9b132a88448..ee051906ad6 100755 --- a/docs/index.html +++ b/docs/index.html @@ -36,6 +36,7 @@ + diff --git a/docs/site/components/authorization/authorization.html b/docs/site/components/authorization/authorization.html new file mode 100644 index 00000000000..a494ccf1c77 --- /dev/null +++ b/docs/site/components/authorization/authorization.html @@ -0,0 +1,19 @@ + + +
+ +
diff --git a/docs/site/components/authorization/authorization.js b/docs/site/components/authorization/authorization.js new file mode 100644 index 00000000000..2a108ffa0d7 --- /dev/null +++ b/docs/site/components/authorization/authorization.js @@ -0,0 +1,15 @@ +angular + .module('gcloud.authorization', ['ngRoute', 'gcloud.subpage', 'btford.markdown']) + .config(function($routeProvider) { + 'use strict'; + + $routeProvider.when('/authorization', { + controller: 'AuthorizationCtrl', + templateUrl: 'site/components/authorization/authorization.html' + }); + }) + + .controller('AuthorizationCtrl', function($scope) { + 'use strict'; + + }); diff --git a/docs/site/components/docs/docs.html b/docs/site/components/docs/docs.html index 6e2359b9d39..6be7fb5ac4c 100644 --- a/docs/site/components/docs/docs.html +++ b/docs/site/components/docs/docs.html @@ -44,13 +44,13 @@

$ npm install --save gcloud
var gcloud = require('gcloud');

- If you are running your app on Google App Engine or Google Compute Engine, you won't need to worry about supplying connection configuration options to gcloud— we figure that out for you. + If you are running your app on Google Compute Engine, you won't need to worry about supplying connection configuration options to gcloud— we figure that out for you.

However, if you're running your app elsewhere, you will need to provide project details to authenticate API requests.

-// App Engine and Compute Engine +// Compute Engine var gcloud = require('gcloud'); // Elsewhere @@ -59,7 +59,7 @@

keyFilename: '/path/to/keyfile.json' });

- The full set of options which can be passed to gcloud and sub-modules are outlined here. + The full set of options which can be passed to gcloud and sub-modules are outlined here.

@@ -69,10 +69,8 @@

BigQuery Overview

The object returned from gcloud.bigquery gives you complete access to and control of your BigQuery datasets. You can work with existing ones, by using the dataset method, or create new ones with createDataset.

-
-var bigquery = gcloud.bigquery();

- Follow along with the examples below to see how to query your datasets, create tables, import data from your Cloud Storage buckets, and more. + To learn more about BigQuery, see What is BigQuery?

@@ -81,13 +79,8 @@

Datastore Overview

The gcloud.datastore object gives you some convenience methods, as well as exposes a dataset function. This will allow you to create a dataset, which is the object from which you will interact with the Google Cloud Datastore.

-
-var dataset = gcloud.datastore.dataset({ - projectId: 'project-id', - keyFilename: '/path/to/keyfile.json' -});
-

- See the Dataset documentation for examples of how to query the datastore, save entities, run a transaction, and others. +

+ To learn more about Datastore, read the Google Cloud Datastore Concepts Overview.

@@ -97,41 +90,28 @@

Pub/Sub Overview

Google Cloud Pub/Sub is in Alpha status. As a result, it might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.

- The gcloud.pubsub method will return a pubsub object, allowing you to create topics, publish messages, subscribe to topics, and more. See the Google Cloud Pub/Sub overview for more information. + The gcloud.pubsub method will return a pubsub object, allowing you to create topics, publish messages, subscribe to topics, and more.

-
-var pubsub = gcloud.pubsub({ - projectId: 'project-id', - keyFilename: '/path/to/keyfile.json' -});

- See the examples below, which demonstrate everything from creating a topic to subscribing to messages on a topic. + To learn more about Pub/Sub, see the Google Cloud Pub/Sub overview.

Storage Overview

- The gcloud.storage object contains a bucket function, which is how you will interact with your Google Cloud Storage bucket. See the guide on Google Cloud Storage to create a bucket. + The gcloud.storage object contains a bucket function, which is how you will interact with your Google Cloud Storage bucket.

-
-var bucket = gcloud.storage().bucket('my-bucket');
-

ACLs

- Google Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share files with other users and allow other users to access your buckets and files. + To learn more about Cloud Storage, see the Google Cloud Storage overview.

+ +

ACLs

- Convenience methods are provided to perform common operations, such as the following. + Google Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share files with other users and allow other users to access your buckets and files.

-
-// Allow a user to read files from a bucket. -bucket.acl.readers.addUser('email@example.com', function(err, aclObject) {}); - -// Revoke file ownership permissions from a group. -var myFile = bucket.file('my-file.txt'); -myFile.acl.owners.deleteGroup('group-id', function(err, aclObject) {});

- See examples below for more on how to access your bucket to upload a file, read its files, create signed URLs, and more. + To learn more about ACLs, read this overview on Access Control.

diff --git a/docs/site/components/subpage/subpage.html b/docs/site/components/subpage/subpage.html index 60d68bd7d65..745fff9243d 100644 --- a/docs/site/components/subpage/subpage.html +++ b/docs/site/components/subpage/subpage.html @@ -56,6 +56,11 @@

Documentation +
  • + + Authorization + +
  • FAQ diff --git a/docs/site/css/main.css b/docs/site/css/main.css index fdaaefdd2ce..0337db8d969 100755 --- a/docs/site/css/main.css +++ b/docs/site/css/main.css @@ -725,6 +725,13 @@ ul { cursor: pointer; } +.js { + display: block; + padding: .5em; + color: #333; + background: #F8F8F8; +} + /* Page Title */ diff --git a/docs/site/home.js b/docs/site/home.js index 42e0e87510f..1697b102346 100644 --- a/docs/site/home.js +++ b/docs/site/home.js @@ -1,6 +1,7 @@ angular .module('gcloud', [ 'ngRoute', + 'gcloud.authorization', 'gcloud.docs', 'gcloud.faq', 'gcloud.troubleshooting', diff --git a/lib/bigquery/index.js b/lib/bigquery/index.js index 515a44afa56..67a3c25d85b 100644 --- a/lib/bigquery/index.js +++ b/lib/bigquery/index.js @@ -66,21 +66,13 @@ var SCOPES = ['https://www.googleapis.com/auth/bigquery']; * The examples below will demonstrate the different usage patterns your app may * need to support to retrieve a BigQuery object. * - * The full set of options that can be passed to BigQuery are - * [outlined here](#/docs/?method=gcloud). - * * @alias module:bigquery * @constructor * - * @param {object=} options - Configuration object. + * @param {object} options - [Configuration object](#/docs/?method=gcloud). * * @example - * var gcloud = require('gcloud'); - * - * //- - * // Providing configuration details up-front. - * //- - * var myProject = gcloud({ + * var gcloud = require('gcloud')({ * keyFilename: '/path/to/keyfile.json', * projectId: 'my-project' * }); @@ -88,13 +80,6 @@ var SCOPES = ['https://www.googleapis.com/auth/bigquery']; * var bigquery = myProject.bigquery(); * * //- - * // Overriding default configuration details. - * //- - * var bigquery = myProject.bigquery({ - * keyFilename: '/path/to/another/keyfile.json' - * }); - * - * //- * // In the following examples from this page and the other modules (Dataset, * // Table, etc.), we are going to be using a dataset from * // data.gov (http://goo.gl/f2SXcb) of higher education institutions. diff --git a/lib/datastore/dataset.js b/lib/datastore/dataset.js index 62173f961e5..ca2923997d3 100644 --- a/lib/datastore/dataset.js +++ b/lib/datastore/dataset.js @@ -66,16 +66,11 @@ var SCOPES = [ * Interact with a dataset from the * [Google Cloud Datastore](https://developers.google.com/datastore/). * - * The full set of options that can be passed to this method are - * [outlined here](#/docs/?method=gcloud). - * * @constructor * @alias module:datastore/dataset * @mixes module:datastore/request * - * @param {object=} options - Configuration object. - * @param {string=} options.projectId - Dataset ID. This is your project ID from - * the Google Developers Console. + * @param {object=} options - [Configuration object](#/docs/?method=gcloud). * @param {string=} options.apiEndpoint - Override the default API endpoint used * to reach Datastore. This is useful for connecting to your local Datastore * server (usually "http://localhost:8080"). @@ -94,6 +89,11 @@ var SCOPES = [ * projectId: 'my-project', * apiEndpoint: 'http://localhost:8080' * }); + * + * //- + * // The `process.env.DATASTORE_HOST` environment variable is also recognized. + * // If set, you may omit the `apiEndpoint` option. + * //- */ function Dataset(options) { if (!(this instanceof Dataset)) { diff --git a/lib/datastore/index.js b/lib/datastore/index.js index 26c7d6a8c59..887331b7938 100644 --- a/lib/datastore/index.js +++ b/lib/datastore/index.js @@ -62,28 +62,18 @@ var Dataset = require('./dataset'); * @alias module:datastore * @constructor * - * @example - * var gcloud = require('gcloud'); + * @param {object} options - [Configuration object](#/docs/?method=gcloud). * - * //- - * // Providing configuration details up-front. - * //- - * var myProject = gcloud({ + * @example + * var gcloud = require('gcloud')({ * keyFilename: '/path/to/keyfile.json', * projectId: 'my-project' * }); * * var dataset = gcloud.dataset(); - * - * //- - * // Overriding default configuration details. - * //- - * var dataset = myProject.datastore.dataset({ - * keyFilename: '/path/to/another/keyfile.json' - * }); */ -function Datastore(config) { - this.config = config || {}; +function Datastore(options) { + this.config = options || {}; } /*! Developer Documentation diff --git a/lib/index.js b/lib/index.js index fd1df902601..534544f4bd0 100644 --- a/lib/index.js +++ b/lib/index.js @@ -58,45 +58,8 @@ var util = require('./common/util.js'); * 2. Provide them at the time of instantiation of sub-modules, e.g. a Datastore * dataset, a Cloud Storage bucket, etc. * - * If you are using Google App Engine or Google Compute Engine, your connection - * details are handled for you. You won't have to worry about specifying these, - * however you may find it advantageous to provide a `projectId` at - * instantiation. - * - * To specify the configuration details up-front, invoke the gcloud module, - * passing in an object. The properties defined on this object will be persisted - * to the instantiation of every sub-module. It's important to note that you can - * override any of these defaults when you invoke a sub-module later. - * - * You can invoke this module as many times as your project warrants. Each time, - * your provided configuration will remain isolated to the returned gcloud - * module. - * - * To authenticate API requests, - * [google-auth-library](https://github.com/google/google-auth-library-nodejs) - * is used to detect the environment your project is running in. Use the - * following guide to determine the appropriate configuration. - * - *

    Google Compute Engine

    - * - * - No configuration necessary! - * - *

    Google App Engine Production

    - * - * - No configuration necessary! - * - *

    Other

    - - * - Provide `config.projectId` - * - Use one of the following: - * - `config.credentials` object containing `client_email` and `private_key` - * properties. - * - `config.keyFilename` path to a .json, .pem, or .p12 key file. - * - `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a full path - * to your key file. - * - * **Note**: When using a .pem or .p12 key file, `config.email` is also - * required. + * See our [Authorization Guide](#/authorization) for how to obtain the + * necessary credentials for connecting to your project. * * @alias module:gcloud * @constructor diff --git a/lib/pubsub/index.js b/lib/pubsub/index.js index e26cfa9e58c..0f15df8e8e5 100644 --- a/lib/pubsub/index.js +++ b/lib/pubsub/index.js @@ -64,39 +64,18 @@ var SCOPES = [ * subject to any SLA or deprecation policy. Request to be whitelisted to use * it by filling the [Limited Preview application form](http://goo.gl/sO0wTu). * - * The full set of options that can be passed to this method are - * [outlined here](#/docs/?method=gcloud). - * * @constructor * @alias module:pubsub * - * @param {object=} options - Configuration object. - * @param {string=} options.projectId - Google Developers Console Project ID. - * @param {string=} options.keyFilename - Full path to the JSON key downloaded - * from the Google Developers Console. Alternatively, you may provide a - * `credentials` object. - * @param {object=} options.credentials - Credentials object, used in place of - * a `keyFilename`. + * @param {object} options - [Configuration object](#/docs/?method=gcloud). * * @example - * var gcloud = require('gcloud'); - * - * //- - * // Providing configuration details up-front. - * //- - * var myProject = gcloud({ + * var gcloud = require('gcloud')({ * keyFilename: '/path/to/keyfile.json', * projectId: 'my-project' * }); * * var pubsub = gcloud.pubsub(); - * - * //- - * // Overriding default configuration details. - * //- - * var pubsub = myProject.pubsub({ - * keyFilename: '/path/to/another/keyfile.json' - * }); */ function PubSub(options) { options = options || {}; diff --git a/lib/storage/index.js b/lib/storage/index.js index 092e777e5a9..80e36bccd83 100644 --- a/lib/storage/index.js +++ b/lib/storage/index.js @@ -63,31 +63,18 @@ var STORAGE_BASE_URL = 'https://www.googleapis.com/storage/v1/b'; * The examples below will demonstrate the different usage patterns your app may * need to connect to `gcloud` and access your bucket. * - * The full set of options that can be passed to this method are - * [outlined here](#/docs/?method=gcloud). - * * @alias module:storage * @constructor * - * @example - * var gcloud = require('gcloud'); + * @param {object} options - [Configuration object](#/docs/?method=gcloud). * - * //- - * // Providing configuration details up-front. - * //- - * var myProject = gcloud({ + * @example + * var gcloud = require('gcloud')({ * keyFilename: '/path/to/keyfile.json', * projectId: 'my-project' * }); * * var storage = myProject.storage(); - * - * //- - * // Overriding default configuration details. - * //- - * var storage = myProject.storage({ - * keyFilename: '/path/to/another/keyfile.json' - * }); */ function Storage(options) { if (!(this instanceof Storage)) {