google ads api —— token

参考：

OAuth2 Authentication

Common Errors

Make Your First API Call

FAQ

Best Practices

Rate Limits

Developer Token Reset

 

 

 

Developer token

The developer token identifies your app to the AdWords API. Only approved tokens can connect to the API for production Google Ads accounts; pending tokens can connect only to test accounts. Once your token is approved, you can use the same token for requests against all your Google Ads accounts, even if they're not linked to the manager account associated with the developer token.

You can retrieve your developer token by signing in to your manager account then going to the AdWords API Center page (Tool icon > SETUP > API Center).

See Managing Accounts for more details.

 

Offline access

It's common for an AdWords API client app to request offline access. For example, your app may want to run batch jobs when your user is not physically online browsing your website.

To request offline access for a web application type, make sure you set the access_type parameter to offline. You can find additional information in Google's OAuth2 guide.

For installed application type, offline access is enabled by default - you don't have to explicitly request it.

HTTP request header

The HTTP header in every request to the AdWords API server must include the access token in this form:

 

Authorization: Bearer THE_ACCESS_TOKEN

For example:

 

POST … HTTP/1.1
Host: …
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
Content-Type: text/xml;charset=UTF-8
Content-Length: …

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
  …
</soap:Envelope>

Access and refresh token

In most cases, you need to store the refresh token securely for future use. To learn more about how to request access and refresh tokens, read the guide corresponding to your application type:

• Installed application (recommended)
• Web application with a web flow

Access token expiration

An access token has an expiration time (based on the expires_in value) after which the token is no longer valid. You can use the refresh token to refresh an expired access token. By default, our client libraries automatically refresh expired access tokens.

Authenticating multiple accounts

A credential generated for an Google Ads manager account can be used to access all its child accounts. Thus, for users with a single manager account hierarchy, it's usually sufficient to generate a credential for the top-level manager account, thereby authorizing the app for all the Google Ads accounts beneath it.

In other cases, your app must access Google Ads accounts that are not related to one another in any manager account hierarchy. In this case, you should generate and maintain different credentials for different accounts, such as for each Google Ads client account you access, or each top-level manager account in the independent hierarchies you access.

You can follow the same strategies for multithreaded and multiprocess / distributed apps with minor modification. When using a shared data store, credentials must be indexed by the account identifier customerId to ensure credentials are associated with the right account. Additionally, the refresh job should keep all credentials refreshed. If a new account is linked, the refresh job may need to be triggered.

Finally, in multithreaded apps, you should only share the credential object across threads that are operating on the account with which the credential object is associated.

Server pool

Each server or process in the pool retrieves the latest credential from the data store before making a request. As long as the refresh job is running successfully, the credential will be valid. But if the refresh job or data store fails, you should have a fallback mechanism.

If a server or process cannot get a credential from the data store, or if the credential is expired, the server should refresh its own credentials to allow the app to continue working with the API until the problem is resolved.

In processes with multiple threads, you should use the same sharing strategy described above to share the credential across threads.

Data store

A central data store can be used to share the credential between processes and servers.

You can make use of an existing data store or deploy one specific to the sharing of credentials between servers. Solutions include caching servers (such as Memcached or Infinispan), or NoSQL data stores (such as MongoDB).

The data store must provide a reliable interface to all the servers making requests to the API. It should be optimized for fast reading operations, since the server or process will read the current credential more frequently than the refresh job will update it.

Keep in mind that credentials must be stored securely.

When storing the credential, you should store the calculated expiry_time (now + expires_in) and refresh_token alongside the access_token. The expiry_time is calculated as the time of the access_token refresh request plus the expires_in time.

Refresh job

The refresh job periodically refreshes the credential and stores it in the data store. The job shouldn't wait until the current credential expires before initiating a refresh: Doing so would open a window when the app is stalled for lack of a valid credential.

A better alternative is to force the refresh periodically, each time replacing the credential in the data store with the new one. The refresh job should run well before the current credential expires to allow some time in case of a transient failure. Every 15 minutes is a good starting point.

Multiprocess or distributed apps

In multiprocess or distributed apps, sharing the credential requires you to persist it. To ensure multiple processes or servers don't attempt to refresh the credential at the same time (resulting in excessive refresh requests), we advise proactively refreshing the credential in a central place and sharing it across processes/servers.

For example, a separate job or service can be responsible for periodically refreshing the credential, and proactively pushing it to the data store for use by the pool of servers.

The diagram shows the credential refresh job running periodically and writing the credential's properties to the data store. Each server then retrieves the credential before making a request to the API.

Multithreaded apps

In multithreaded apps, the credential should be shared between threads. Refreshing of the credential should be performed synchronously to avoid a race condition.

The diagram shows a runtime with threads drawing from a pool of sessions (or users) to make requests to the AdWords API. Note that each session should use the same credential object. On each API request, the thread obtains a session (or user). If the credential requires an access token refresh, it must be done synchronously—that is, the credential object must be thread-safe—to avoid a race condition.

The client libraries make sharing a credential across threads straightforward. Each client library has a session (or user) object with a credential that it reuses throughout its lifetime. To share the credential across threads, simply construct each session using the same credential. In all client libraries, the credential is a thread-safe object that refreshes itself synchronously when its access token expires.

For example, in the Java client library, you would create a Credential as a singleton and share it across all sessions.

Credential sharing strategies

Sharing credentials across your API requests improves performance and avoids excessive overhead that can result in rate limit errors.

Your credential sharing strategy depends on your app's design:

• Multithreaded apps share a thread-safe credential.
• Multiprocess or distributed apps share a credential via a shared data store.

In multithreaded apps, you should supply each thread's session with the same credential.

In multiprocess or distributed apps, you must implement some infrastructure to share the credential across processes. You should also ensure that threads aren't blocked, and that race conditions aren't present in your implementation.

An app that is both multiprocess / distributed and multithreaded within each process should use both strategies.

These strategies are described below for authenticating a single Google Ads account, such as the top-level manager account in your hierarchy.

Adapting these strategies to authenticate for multiple Google Ads accounts is described after.

Optimizing OAuth2 requests

If your app doesn't share credentials across servers, processes, and threads, it may be sending an excessive number of requests to Google. This can cause our servers to enforce rate limits on your app, resulting in performance degradation.

This section explains how to optimize OAuth2 credential management so your app can efficiently interact with the AdWords API.

What do I need to get started using the AdWords API after signup?

All you need to get started is an approved developer token. You can acquire it after you register for the AdWords API.

After you sign up, your developer token will be sent to your account email address. Once approved, this token will be activated and you'll be able to access the API by including it in your request headers. You can find the token on your manager account's AdWords API Center page.

Can I start using the API as soon as I sign up?

After you provide your developer information, you'll be assigned a developer token, but you'll need to wait until your token has been approved before accessing the API. The AdWords API Review team will contact you within one week of your application. In the meantime, you may apply for a Test Account in order to begin developing and testing your application.

What are common reasons why a developer token would not be approved?

The AdWords API Terms & Conditions include detailed guidelines for appropriate use of the AdWords API. You must agree to these terms during the set-up step. If you have used, or intend to use, the API in ways inconsistent with these terms, your tokens will not be approved. If you are developing an external tool—one in which your clients will access—your tool must implement our Required Minimum Functionality.

Read more about signing up for the AdWords API.

What are the different access levels for the AdWords API?

There are two levels of AdWords API access:

1. Basic
2. Standard

The access levels pertain to number of daily operations only; there are still token-level rate limits to prevent excessive stress on our systems and to guarantee good performance for all our API users. All users are still required to comply with Google Ads terms, AdWords API terms, and the required minimum functionality, where applicable. There will be no charges for AdWords API usage for either basic or standard access.

Basic access: This is the default access level for all approved developer tokens. Basic access allows developers to execute up to 10,000 operations and 1,000 report downloads per day.

Standard access: This is the access level for those needing more usage capacity. Standard access requires developers to provide additional details and keep these details current with Google.

What are some of the common reasons standard access approval may be delayed or not granted?

Some of the common reasons for delayed approvals are:

• Incomplete details provided on the standard access application
• Inaccurate contact details in the manager account that is associated with the AdWords API developer token
• Not responding to follow-up questions and clarifications by the AdWords API support team
• Using the API in ways inconsistent with the AdWords API terms and conditions
• Not implementing the Required Minimum Functionality
• Current AdWords API usage is very low and does not yet justify standard access

With API usage being free, do we still need to provide billing details when applying for the AdWords API token?

We no longer require billing information during signup. Details like contact info are still needed. There are no charges for compliant API usage under either basic or standard access.

What do I need to do if I'm a current AdWords API user?

As an AdWords API user, please accept the updated Terms and Conditions to continue to use the AdWords API.

• If you are a third party developing an API tool for a client who owns that software, and you don't have the authority to accept on your clients' behalf, please ask your clients to sign in to their accounts to review and accept the updated terms.
• You'll receive an email with instructions on how to review and accept the new terms. Please note that if you don't accept the terms within 45 days of receiving this email, we'll consider you to have accepted the terms based on your continued use of your developer token.

Where do I find the new Terms and Conditions and how do I accept them?

In addition to instructions sent to you by email, you'll also see a red alert bar at the top of the manager account associated with your AdWords API developer token containing a link to the new Terms and Conditions. To accept the new terms, just follow the prompts.

You can also review the new Terms and Conditions. To review our previous terms and conditions, see below.

What's changed?

The updated Terms and Conditions are designed to be a more concise and better organized way for you to understand what's required of you as a user of the AdWords API. As with any legal document, you might consider consulting an attorney if you have legal questions. Here are some general pointers about the new terms:

• Accepting the new terms does not change any of your bids, budgets, or other campaign settings. As always, you'll continue to control your settings in the Campaign tab of your account.
• You'll also see links to a new AdWords API Policy Center, which the new terms require you to follow.
• Keep in mind that if you decline the new terms, your developer token will be terminated.

The forum is regularly monitored by the AdWords API team, making it the ideal place to post API questions.

• Keep your app compliant with the AdWords API Terms and Conditions (T&C) and Required Minimum Functionality (RMF). If required, the token review and compliance team will reach out to you via your contact email. If you have questions or concerns about the T&C or RMF, you can reach out to the review team by responding to the email they sent you when reviewing your developer token application.

Reuse access tokens

Reusing the same OAuth2 access token across threads and processes reduces the overhead of periodically refreshing tokens, and reduces the likelihood that your app will be rate limited due to excessive token refreshes. Learn more about optimizing OAuth2 requests.

Distinguish error types

Below are four broad categories of errors, each of which should be handled differently. Though these categories don't encompass all possible errors, and some may fit into more than one category, they can nevertheless serve as a starting point for structuring your app's error handling. Refer to Common Errors for more details about a particular error.

1. Authentication and authorization errors

   • Authentication refers to whether your app has been given permission by a user to access Google Ads on their behalf. Authentication is managed through credentials generated by the OAuth2 flow.

   • Authorization refers to whether your app, authenticated and acting as a user, is allowed to work with the particular Google Ads data it is trying to read or write.

     The most common reason an authentication error arises from factors beyond your control is when the authenticated user revokes the permission they gave your app to act on their behalf. For example, if your app manages separate Google Ads accounts for independent clients and authenticates separately as each client when managing that client's account, a client could revoke your app's access at any time. Depending on when your access was revoked, the API may directly return an AuthenticationError.OAUTH_TOKEN_REVOKED error, or the built-in credential objects in the client libraries may throw a token revoked exception. In either case, if your app has a UI for your clients, it could ask them to relaunch the OAuth2 flow to reestablish your app's permission to act on their behalf.

     Another common reason an authorization error arises from factors beyond your control is due to changes in your manager account hierarchy. Apps working with a single manager account hierarchy usually authenticate as an administrator user of their top-level manager account, since this user has the authority to access all of the sub-accounts in the hierarchy. If a user of a sub-account removes the manager link, your app will receive an AuthorizationError.USER_PERMISSION_DENIED error when attempting to access that account. You can use ManagedCustomerService to check whether the sub-account has indeed been removed from the hierarchy.

     Another reason an authorization error can arise is when the user your app authenticated as has their access rights changed. For example, suppose another user with administrator rights on the Google Ads account changes your app's authenticated user's rights to read-only. In this case, all mutate requests will fail with an AuthorizationError.USER_HAS_READONLY_PERMISSION error.

     For either example, your app could provide directions for the user, or escalate the issue to an account manager for resolution.

Use test accounts

Test accounts are Google Ads accounts that do not actually serve ads. You can use a test account to experiment with the AdWords API and test that your app's connectivity, campaign management logic, or other processing are working as expected. Your developer token does not need to be approved to use it on a test account, so you can start developing with the AdWords API immediately after requesting a developer token, even before your app is reviewed.

Rate Limitsbookmark_border

To deliver reliable services to AdWords API users across the globe, we use a Token Bucket algorithm to meter the requests and determine the queries per second (QPS) rate. This is intended to prevent malicious or out-of-control software from overwhelming the AdWords API servers and affecting other users.

For example, if a runaway client accidentally spawned thousands of threads to make concurrent AdWords API calls, AdWords API servers will notice and return a RateExceededError requesting the calling software to slow down.

It's important to remember that rate limits can fluctuate based on different variables, including server load. Hence, we don't recommend a fixed Queries Per Second (QPS) limit. It's extremely important to understand how to handle RateExceededError, and develop your software with rate limits in mind.

This guide will dive into more details to help you understand RateExceededError, and how to avoid exceeding the rate limit.

Types of rate limits

We recognize that your AdWords API client application may sometimes exceed the limit and receive a RateExceededError due to factors not fully in your control. It's important to note that there is no penalty for doing so. RateExceededError is usually transient and automatically resolves after 30 seconds of inactivity.

There are a number of different types of rate limits that may be enforced by the server. A client application may exceed a rate limit within a manager account's developer token scope, or Google Ads account scope. Within each scope, rather than a strict QPS rate limit, rate limits are metered in terms of Requests Per Minute, Operations Per Minute, and/or other types of rate limits. This allows both steady and burst traffic to the AdWords API. Both the scope and the name of the rate limit are returned as part of RateExceededError.

Operational limit based on access level

There is only one type of rate limit that doesn't fluctuate: the operational limit based on the access level of your developer token. There are two access levels: Basic and Standard. A Basic access level account has limits of 10,000 operations per day and 1,000 report downloads per day. A newly approved developer token is assigned the Basic access level by default. If you plan to execute more than 10,000 operations or 1,000 report downloads per day, you can apply for Standard access level by completing the AdWords API Standard Access Application Form. There is no charge for either access level. Please check out the Rate Sheet to determine how operations are counted.

Other than the operational limit, all other rate limits may fluctuate. Thus, it's important to handle RateExceededError in your application.