Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(README): bunch of rewritings #149

Merged
merged 2 commits into from
Sep 2, 2014
Merged

docs(README): bunch of rewritings #149

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ff84d7
docs(README): bunch of rewritings
silvolu Aug 28, 2014
5218d9b
docs(README): fix typo and dataset snippet
silvolu Aug 29, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 36 additions & 142 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,193 +7,87 @@

This client supports the following Google Cloud services:

* [Google Cloud Datastore](https://developers.google.com/datastore/)
* [Google Cloud Datastore](https://cloud.google.com/products/cloud-datastore/)
* [Google Cloud Storage](https://cloud.google.com/products/cloud-storage/)
* [Google Cloud Pub/Sub (experimental)](https://developers.google.com/pubsub/)

Planned, but not yet available:

* [Google Compute Engine](https://developers.google.com/compute)
* [Google BigQuery](https://developers.google.com/bigquery/)

## Quickstart

```sh
$ npm install gcloud
```

## Authorization

### On Google Compute Engine

If you are running this client on Google Compute Engine, you can skip to the developer's guide. We handle authorisation for you with no configuration.
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](https://developers.google.com/compute/docs/authentication#using), you add the correct scopes for the APIs you want to access.

### 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](https://console.developers.google.com/project).
2. Create a new project or click on an existing project.
3. Enable billing if you haven't already.
4. On the "APIs & auth" tab, click APIs section and turn on the following. You may need to enable billing in order to use these services.
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
* Google Cloud Pub/Sub
5. Once API access is enabled, switch back to "APIs & auth" section on the navigation panel and switch to "Credentials" page.
6. Click on "Create new client ID" to create a new **service account**. Once the account is created, click on "Generate new JSON key" to download your private key. The downloaded file contains credentials you'll need for authorization.

You'll need the following for auth configuration:

1. Your Developers Console project's ID (e.g. bamboo-shift-455).
2. The path to the JSON key file.
4. Navigate to **APIs & auth** > **Credentials** and then:
* If you want to use a new service account, click on **Create new client ID**. 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.

### Google Cloud Datastore
## Google Cloud Datastore

[Google Cloud Datastore](https://developers.google.com/datastore/) is a fully managed, schemaless database for storing non-relational data. Cloud Datastore automatically scales with your users and supports ACID transactions, high availability of reads and writes, strong consistency for reads and ancestor queries, and eventual consistency for all other queries.

See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) for how to interact with the Datastore.

### Google Cloud Storage

Google Cloud Storage allows you to store data on Google infrastructure. Read [Google Cloud Storage API docs](https://developers.google.com/storage/) for more information.

You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on [Google Cloud Storage docs](https://developers.google.com/storage/) to create a bucket.

See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) for how to connect to the Storage API.

### Google Cloud Pub/Sub (experimental)
See the [Google Cloud Datastore docs](https://developers.google.com/datastore/docs/activate) for more details on how to activate Cloud Datastore for your project.

Google Cloud Pub/Sub is a reliable, many-to-many, asynchronous messaging
service from Google Cloud Platform. A detailed overview is available on
[Pub/Sub docs](https://developers.google.com/pubsub/overview).

Note: Google Cloud Pub/Sub API is available as a Limited Preview and the
client library we provide is currently experimental. The API and/or the
client might be changed in backward-incompatible ways.
This API is not subject to any SLA or deprecation policy. Request to be
whitelisted to use it by filling the [Limited Preview application form](https://docs.google.com/a/google.com/forms/d/1IQY4LAbISLa86uxRv2dKAzkeWOyNZda_tUn7xgVYeoE/viewform).

#### Configuration

If you're running this client on Google Compute Engine, you need to construct
a pubsub Connection with your Google Developers Console project ID.

```js
var gcloud = require('gcloud');
var conn = new gcloud.pubsub.Connection({
projectId: YOUR_PROJECT_ID
});
```

Elsewhere, construct with a project ID, service account's email, and private key downloaded from Developer's Console.
See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) to learn how to interact with the Cloud Datastore using this Client Library.

```js
var gcloud = require('gcloud');
var conn = new gcloud.pubsub.Connection({
projectId: YOUR_PROJECT_ID,
keyFilename: '/path/to/the/key.json'
});
```

#### Topics and Subscriptions

List, get, create and delete topics.

```js
// Lists topics.
conn.listTopics({
maxResults: 5
}, function(err, topics, nextQuery) {
// If there are more results, nextQuery will be non-null.
});

// Retrieve an existing topic by name.
conn.getTopic('topic1', function(err, topic) {
// Delete this topic.
topic.del(callback);
});

// Creates a new topic named topic2.
conn.createTopic('topic2', callback);
```
var datastore = gcloud.datastore;
var dataset;

List, get, create and delete subscriptions.

```js
var query = {
maxResults: 5,
filterByTopicName: 'topic1'
};

// List 5 subscriptions that are subscribed to topic1.
conn.listSubscriptions(query, function(err, subs, nextQuery) {
// if there are more results, nextQuery will be non-null.
// From Google Compute Engine
dataset = new datastore.Dataset({
projectId: 'my-project',
});

// Get a subscription named sub1.
conn.getSubscription('sub1', function(err, sub) {
// delete this subscription.
sub.del(callback);
// From elsewhere
dataset = new datastore.Dataset({
projectId: 'my-project',
keyFilename: '/path/to/keyfile.json'
});

// Create a new subsription named sub2 which listens to topic1.
conn.createSubscription({
topic: 'topic1',
name: 'sub2',
ackDeadlineSeconds: 60
}, callback);
dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {});
```

#### Publishing a message

You need to retrieve or create a topic to publish a message. You can either
publish simple string messages or a raw Pub/Sub message object.
## Google Cloud Storage

```js
conn.getTopic('topic1', function(err, topic) {
// Publish "hello world" to topic1's subscribers.
topic.publish('hello world', callback);
topic.publishMessage({
data: 'Some text here...',
label: [
{
key: 'priority',
numValue: 0
},
{
key: 'foo',
stringValue: 'bar'
}
]
}, callback);
});
```
[Google Cloud Storage](https://developers.google.com/storage/) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.

#### Listening for messages
You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on the [Google Cloud Storage docs](https://developers.google.com/storage/docs/cloud-console#_creatingbuckets) to learn how to create a bucket.

You can either pull messages one by one via a subscription, or let the client
open a long-lived request to poll them.
See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) to learn how to connect to the Cloud Storage using this Client Library.

```js
// Allow client to poll messages from sub1.
// `autoAck` automatically acknowledges the messages. (default: false)
var sub = conn.subscribe('sub1', {
autoAck: true
});

sub.on('ready', function() {
console.log('Listening for messages...');
});
var gcloud = require('gcloud');
var storage = gcloud.storage;
var bucket;

sub.on('message', function(msg) {
console.log('Message retrieved:', msg);
// From Google Compute Engine
bucket = new storage.Bucket({
bucketName: YOUR_BUCKET_NAME
});

sub.on('error', function(err) {
console.log('An error occurred:', err);
// From elsewhere
bucket = new storage.Bucket({
bucketName: YOUR_BUCKET_NAME,
keyFilename: '/path/to/the/key.json'
});

// Closes the connection and stop listening for messages.
sub.close();
bucket.write('filename', 'Hello World', function(err) {});
```

## Contributing
Expand Down