Remote API for Go

The App Engine SDK for Go includes a remote_api package that lets you transparently access App Engine services from any Go application. For example, you can use the Remote API to access Cloud Datastore from an app running on your local machine or from another one of your App Engine apps.

To view the contents of the remote_api package, see the remote_api package reference.

Enabling Remote API

First, add the remote_api url handler to your app.yaml. For example:

- url: /_ah/remote_api
  script: _go_app

This maps the URL /_ah/remote_api to your Go app. Access to this URL is restricted to administrators for the application by the Remote API handler.

Then you import the remote_api package in one of your project's packages by adding the following line to any of your .go source files:

import _ "google.golang.org/appengine/remote_api"

During program initialization, the remote_api package registers a handler for the /_ah/remote_api path. The underscore in the import declaration means "import this package, but we won't use it directly." Without the underscore, you would receive an "imported but not used" error message on compilation.

Finally, you deploy the update to App Engine. For example:

gcloud app deploy app.yaml

Using the Remote API in a Local Client

The Remote API can be used to write local applications that use App Engine services and access datastore. It is important to note that using the Remote API will incur quota usage on the application you are accessing.

Before beginning, make sure the Remote API is enabled in your App Engine application. The local application can use the Remote API by creating a context with remote_api.NewRemoteContext, and using that in place of the regular App Engine context in all API calls.

// Copyright 2011 Google Inc. All rights reserved.
// Use of this source code is governed by the Apache 2.0
// license that can be found in the LICENSE file.

package main

import (
	"log"
	"time"

	"golang.org/x/net/context"
	"golang.org/x/oauth2/google"

	"google.golang.org/appengine/datastore"
	"google.golang.org/appengine/remote_api"
)

func main() {
	const host = "<your-app-id>.appspot.com"

	ctx := context.Background()

	hc, err := google.DefaultClient(ctx,
		"https://www.googleapis.com/auth/appengine.apis",
		"https://www.googleapis.com/auth/userinfo.email",
		"https://www.googleapis.com/auth/cloud-platform",
	)
	if err != nil {
		log.Fatal(err)
	}

	remoteCtx, err := remote_api.NewRemoteContext(host, hc)
	if err != nil {
		log.Fatal(err)
	}

	q := datastore.NewQuery("Greeting").
		Filter("Date >=", time.Now().AddDate(0, 0, -7))

	log.Println(q.Count(remoteCtx))
}

To run this code, you need to fetch these packages:

$ go get -u google.golang.org/appengine/...
$ go get -u golang.org/x/oauth2/...

You need to provide the hostname of your server and a http.Client in the call to NewRemoteContext. The provided http.Client is responsible for passing the required authetication information in each request.

In the sample above, the DefaultClient from the golang.org/x/oauth2/google package provides OAuth 2 credentials via Application Default Credentials.

Send feedback about...

App Engine standard environment for Go