Accessing App Engine with Remote API

The Remote API library allows any Python client to access services available to App Engine applications.

For example, if your App Engine application uses Google Cloud Datastore or Google Cloud Storage, a Python client could access those storage resources using the Remote API.

You can use the Remote API to access your application's data store from an app running on your local machine, or from a local interactive Remote API shell. The Remote API interacts with real services, so this access does use quota and billable resources.

The App Engine SDK for Python includes the Remote API library.

Enabling Remote API access in your app

The easiest way to enable the Remote API for your application is to use the builtins directive in the app.yaml file for your app, which specifies the default URL /_ah/remote_api/. However, you can instead use the url directive in that same file to specify some other URL.

runtime: python27
api_version: 1
threadsafe: true

builtins:
- remote_api: on

- url: /some-URL/*
  script: google.appengine.ext.remote_api.handler.application

Make sure you deploy your application to App Engine after making this change.

Using the Remote API shell

The Python SDK includes a Remote API shell, which allows you to invoke Python commands on App Engine services used by your application. You don't need to supply any additional authentication, because this automatically uses the same credentials you used to upload the app to App Engine.

To start the Remote API shell:

1. Invoke the following command from a terminal window on your local machine:

    [GAE-SDK-INSTALL-DIRECTORY]/remote_api_shell.py -s [YOUR-PROJECT-ID].appspot.com
   

   Replace [GAE-SDK-INSTALL-DIRECTORY] with the path to the App Engine SDK for Python, and [YOUR-PROJECT-ID] with your project ID.

2. In the interactive shell that is displayed, invoke the Python commands you want to run. For example, if your application uses Cloud Datastore, you could invoke the following ndb query to fetch 10 records:

    >>> from google.appengine.ext import ndb
    >>>
    >>> # Fetch 10 keys from the datastore
    >>> ndb.Query().fetch(10, keys_only=True)
   

Using the Remote API in a local client

You can also use the Remote API in local applications to access services used by your app running in App Engine.

To use the Remote API in a local application:

1. Enable the remote API.

2. Export the PYTHONPATH environment variable for your Python directory, for example:

    export PYTHONPATH=/usr/somedir/v3/bin/python2.7
   

   Replace that path with the actual values for your python location.

3. Add your App Engine SDK for Python location to PYTHONPATH:

    export GAE_SDK_ROOT="/usr/local/home/mydir/google_appengine"
    export PYTHONPATH=${GAE_SDK_ROOT}:${PYTHONPATH}
   

   Replace the SDK path shown above with your actual path to the App Engine SDK.

4. In your client code, import dev_appserver and call dev_appserver.fix_sys_path() to ensure all of the App Engine SDK modules import correctly:

   appengine/standard/remote_api/client.py

   View on GitHub

   try:
       import dev_appserver
       dev_appserver.fix_sys_path()

5. Add the following remote_api_stub code to your application, making sure you pass it your project ID in your code:

   appengine/standard/remote_api/client.py

   View on GitHub

   remote_api_stub.ConfigureRemoteApiForOAuth(
       '{}.appspot.com'.format(project_id),
       '/_ah/remote_api')

   If you don't use the default URL /_ah/remote_api for the Remote API, you'll have to change the code above to reflect the URL you are using. For the definition and documentation for remote_api_stub.ConfigureRemoteApiForOAuth, see the SDK file [GAE-SDK-INSTALL-DIRECTORY]/google/appengine/ext/remote_api/remote_api_stub.py.

6. Add any needed App Engine imports and Python code to access the desired App Engine services. The following sample code accesses the project's data store:

   appengine/standard/remote_api/client.py

   View on GitHub

   import argparse
   
   try:
       import dev_appserver
       dev_appserver.fix_sys_path()
   except ImportError:
       print('Please make sure the App Engine SDK is in your PYTHONPATH.')
       raise
   
   from google.appengine.ext import ndb
   from google.appengine.ext.remote_api import remote_api_stub
   
   
   def main(project_id):
       remote_api_stub.ConfigureRemoteApiForOAuth(
           '{}.appspot.com'.format(project_id),
           '/_ah/remote_api')
   
       # List the first 10 keys in the datastore.
       keys = ndb.Query().fetch(10, keys_only=True)
   
       for key in keys:
           print(key)
   
   
   if __name__ == '__main__':
       parser = argparse.ArgumentParser(
           description=__doc__,
           formatter_class=argparse.RawDescriptionHelpFormatter)
       parser.add_argument('project_id', help='Your Project ID.')
   
       args = parser.parse_args()
   
       main(args.project_id)

7. With your application deployed to App Engine, start your Remote API client:

    python your-client.py YOUR-PROJECT-ID
   

   Replacing your-client.py with your client module, and YOUR-PROJECT-ID with your project ID. This assumes your client accepts project ID as the command-line input, following the client.py code sample.