If your large scale application does not share credentials, it may be sending an excessive number of requests to Google. This can cause our servers to enforce rate limits on your application thereby degrading its performance. This guide shows how to cope with this issue so that your application can interact with the AdWords API more efficiently.
This guide is intended for advanced users who are already familiar with using OAuth 2.0 with the AdWords API.
Strategies for sharing credentials
To avoid excessive token request errors and OAuth 2.0 overhead, you can share valid access tokens between requests. In multithreaded environments, this is done by sharing sessions. However, in multi-server / multiprocess environments, you will need to avail additional infrastructure. You will also need to ensure that threads are not blocked and that race conditions are not present in your implementation.
Effective sharing of access tokens depends on the environment your application is running in. The two main strategies for sharing an access token are:
- Sharing a thread-safe credential (for multi-threaded applications)
- Sharing the access token via a shared data store (for multi-process or multi-server applications)
Sharing credentials in a thread-safe environment
In multithreaded environments, it's important to ensure that access tokens are shared between threads. Refreshing of the access token should be performed synchronously to avoid race conditions.
This diagram shows a runtime with threads leveraging a shared pool of sessions (or users) making requests to the AdWords API. On each asynchronous request, the thread obtains the relevant session (or user). If a session (or user) requires a token refresh, this must be done synchronously to avoid race conditions.
If you're using one of our client libraries, it will attempt to reuse the
credential for the scope of the session (or user). Therefore, it's important
that you share the session (or user) between threads, rather than create a new
one in each thread. In the case of Java, create the
Credential
as a singleton and share it between sessions.
Sharing access tokens via a shared store
For multi-server environments, sharing the authorized credential requires you to
persist it. To ensure that multiple servers don't attempt to refresh the
credential at the same time (race condition), we advise proactively refreshing
and sharing the credential with all servers. It's important to include the
expiry time with the access_token to ensure only valid tokens are used.
For example, by using a separate job or service to handle authentication, we can proactively push an authorized credential to the data store for use by the pool of servers.
The diagram shows the access token refresh job running periodically and writing
the access_token properties to the data store. Each server then retrieves the
access_token for each request to the AdWords API.
Access token refresh job
The authentication job periodically refreshes the access token and stores it in the data store. It makes a forced refresh request to the AdWords API and replaces the current access token stored in the data store. The access token refresh job should run frequently enough to ensure that all server requests are successfully authenticated--every 15 minutes is a good starting point.
Storing the access token
The data store is used to share the access token between servers and the refresh job. Keep in mind that access token credentials must be stored securely. You can make use of an existing data store or deploy one specific to the sharing of access tokens between servers. Solutions include caching servers (such as Memcached or Infinispan), or NoSQL data stores (such as MongoDB). Primarily, the data store needs to provide a reliable interface to all the servers accessing the AdWords API and should be optimized for fast reading operations--favor write once, read many.
Store the calculated expiry_time (now + expires_in) and refresh_token
alongside the access_token. The expiry_time is calculated by the time of the
access_token refresh request, plus the expires_in time.
The server pool (single-threaded environments)
Each server in the pool retrieves the latest access token (from the data store) before making a request. To ensure that a server doesn't attempt to refresh the credential, make the access token read-only. Attempting to refresh the access token from the server pool can cause race conditions. Error handling of requests becomes important, in case the access token refresh job has errors.
The server pool (multi-threaded environments)
Each server in the pool needs to retrieve the access token from the data store instead of making authentication requests to the AdWords API. On the first request, a server uses the access token obtained from the data store. When the access token is about to expire, the server retrieves the latest access token from the data store instead of refreshing the access token on its own.
Authenticating multiple accounts
We recommend using a single manager account structure to access multiple accounts. However, if you need to authenticate more than just one top level manager account, read on for further guidance.
Authenticating multiple accounts builds on the existing sharing of
the credential or
sharing of the access token.
Access tokens must be indexed by the account identifier customerId to
ensure that the correct credentials are associated with an account.
Additionally, the access token refresh job should keep all access tokens
refreshed. If a new account is linked, the refresh job may need to be triggered.
