Google Cloud Platform
Cloud Datastore

Getting started with Google Cloud Datastore and Ruby/JSON

This page discusses how you can get started with Google Cloud Datastore using Ruby. Follow the steps in Sign Up to make sure you are ready to run this example. After activation, you will have a <dataset-id> (same identifier as your Google Cloud Platform Project ID) that you need to run the code.

Step 1: Set up your environment

Set up either a Google Compute Engine instance or your own machine for the development environment.

Set up a Compute Engine instance

Using this option, you'll create and use a Compute Engine instance to compile and run the example.

At a command prompt on your local machine, set INSTANCE_NAME to the name of the Compute Engine instance that you want to create. You'll use the INSTANCE_NAME variable for other commands.


Use the gcloud compute instances create command to create the instance, specifying the datastore and userinfo-email scopes:

gcloud compute instances create $INSTANCE_NAME --scopes datastore,userinfo-email

When the Compute Engine instance is ready, connect to it using the gcloud compute ssh command.

gcloud compute ssh $INSTANCE_NAME

Install Ruby with rubygems and rvm:

gpg --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL | bash -s stable  --ruby
source $HOME/.rvm/scripts/rvm

(For guidance on installing Ruby with rvm, see Installing RVM.)

In order to make calls to the Cloud Datastore API, you need to install the google-api-client gem. This tutorial was written using google-api-client 0.8.6.

gem install google-api-client -v 0.8.6

Install unzip:

sudo apt-get update
sudo apt-get install unzip

Now that your environment is set up, go to Step 2.

Set up your own machine

To use your own machine, ensure that your environment has Ruby with rubygems and rvm. You also need unzip. Depending on your machine configuration, you may be able to install the required software using the commands as shown above for a Compute Engine instance.

In order to make calls to the Cloud Datastore API, you need to install the google-api-client gem. This tutorial was written using google-api-client 0.8.6.

gem install google-api-client -v 0.8.6

With your environment set up, continue to Step 2.

Step 2: Get service account credentials

You need to configure a <service-account> and the <path-to-private-key-file> for the demo code to work. (Ruby support for Compute Engine service accounts is not yet implemented).

Assuming your Compute Engine instance does not have a GUI installed, you need to first download the service account credentials to your local machine and then copy the credentials to the Compute Engine instance.

You can get the service account credentials from the Credentials page in the Google Cloud Platform Console.

On your local machine (not the Compute Engine instance), use the gcloud compute copy-files command to copy the private key file from your local machine to the user home directory on your Compute Engine instance:

gcloud compute copy-files <path-to-private-key-file> <username>@$INSTANCE_NAME:~

where <username> is your Compute Engine instance user name.

On your Compute Engine instance, run the following commands (in a bash-like shell):

# configure your credentials
export DATASTORE_SERVICE_ACCOUNT=<service-account-email>
export DATASTORE_PRIVATE_KEY_FILE=<path-to-private-key-file>


  • <service-account-email> is the service account email address from the Service accounts list for your app in the Google Cloud Platform Console, in the form
  • <path-to-private-key-file> is the path and file name of the P12 private key on your machine.

Step 3: Review the demo code file

The code for the demo is in a file called adams.rb file. The comments in the sample's source explain its behavior in detail:


Step 4: Run the code

Download and unzip the latest version of the google-cloud-datastore samples:


Run the adams.rb demo with your <dataset-id> as a parameter.

ruby google-cloud-datastore-1beta2-rev1-4.0.0/ruby/demos/trivial/adams.rb <dataset-id>

The demo will prompt for the question and validate your answer.

Meaning of life?
Don't Panic!

Step 5: Delete your Compute Engine instance

If you used a Compute Engine instance for this example and no longer need it, disconnect from the Compute Engine instance:


Then delete the Compute Engine instance with the following gcloud compute instances delete command:

gcloud compute instances delete $INSTANCE_NAME

Next steps

With this example, you learned how to use the:

  • google-api-client gem to connect to the Cloud Datastore API.
  • begin_transaction method to start a transaction.
  • lookup method to retrieve entities by key from your dataset.
  • commit method to send mutations to entities in your dataset and commit the transaction.

Now, you are ready to learn more about the Key Datastore Concepts and look at the JSON API reference.