Quickstart and Basic Usage

Authorizing server to server communications with Google’s APIs should be easy. This library attempts to streamline this process. Here we will describe all the steps needed to Authorize yourself with Google’s services and make requests to the API, without going through a three-party oauth flow.

Creating an AuthorizedService object

To use the GClient Service Account library, you must first have a service account set up through Google’s Developer Console. Before continuing with this quickstart guide, follow Google’s documentation on Creating a Service Account

While creating a service account take note of the following:

  1. The Project-id the service account is associated with
  2. The email for the service account
  3. The private key for the service account

Once you have created a service account, creating an AuthorizedService object is as simple as

from service_account_auth import AuthorizedService

with open('path/to/private/key', 'rb') as f:
    private_key = f.read()

ga_service = AuthorizedService(
    project_id='myproject-id-888'
    service_name='analytics'
    service_version='v3'
    email='my_service_account_email@developer.gserviceaccount.com'
    key=private_key
)

In the example above, we create an AuthorizedService object for Google Analytics. Obviously, the values for project_id, email, and key would need to be replaced. Once this object, ga_service is created, all the functionality of the Google Analytics Python API can be accessed through the ga_service.service attribute. This service attribute is authenticated with Google, with the authorizations associated with the service account.

Storing the credentials

It is generally bad practice to store sensitive information in code. For this reason, the GClient Service Account Auth supports accessing sensitive information from environment variables. Instead of passing the email and key into AuthorizedService directly, this information can be stored in environment variables.

If you store the service account email in the environment variable GCLIENT_SERVICE_ACCOUNT_EMAIL, and a path to the private key in the environment variable GCLIENT_KEY_LOCATION, then this library will automatically fetch the appropriate information, without you having to include the email and key arguments for AuthorizedService.

If this information is stored in environment variables, creating an authorized service is as simple as

Using the instance to access an API

Once you have an AuthorizedService object, you can make calls using the python interface defined by Google’s apiclient library through the service attribute of your AuthorizedService object. For example, the Google Analytics API provides a number of methods, one of which is the data method, which we will show an example of calling below

from service_account_auth import AuthorizedService

ga_service = AuthorizedService(
    'myproject-id-888', 'analytics', 'v3'
)

data = ga_service.service.data().ga().get(
    ids='ga:88888888',
    dimensions='ga:browser',
    metrics='ga:pageviews',
    start_date='2015-01-19',
    end_date='2015-01-20'
 ).execute()

The example above gets data on the number of pageviews by browser made to our site tracked by google analytics.

Knowing what methods to call does require some knowledge of what methods are available. For Google Analytics in particular it would be useful to use an external library to simplify the interface.

Use with other libraries

The GA Grab library can be used to make querying Google Analytics much easier.

Supported Services

Google provides python client libraries for many of its APIs. This library can create authorized service objects for the following APIs:

BigQuery
Created with AuthorizedService('proj-id', 'bigquery', 'v2').
Analytics Read-only
Created with AuthorizedService('proj-id', 'analytics-read', 'v3').
Analytics Read/Write
Created with AuthorizedService('proj-id', 'analytics', 'v3').

For many of those not listed here, support is as simple as providing the correct scope url for the API. Contributions are appreciated, even as simple as filing an issue. See Contributing.