Adding Service Account support to the GoogleAds Library

Author: Nicholas Chen

ChangeLog

@@ -1,3 +1,22 @@
+3.0.0 - 1/5/2015
+* Three new dependencies have been added: httplib2, oauth2client, and pysocks.
+* One dependency has been removed: oauthlib
+* BREAKING CHANGE: Python3 versions < 3.3 are no longer supported.
+* BREAKING CHANGE: The https_proxy argument for the GoogleRefreshTokenClient has
+  been deprecated. It has been replaced by proxy_info, which is an optional
+  argument taking an httplib2.ProxyInfo instance.
+* PYTHON2 ONLY: You may now authorize with Service Accounts using the new
+  GoogleServiceAccountClient. As of this release, it will only work with
+  Python2.
+* Added new Service Account authorization examples for AdWords, DFA, and DFP.
+* The googleads.yaml file has been refactored to reflect the changes to proxy
+  support.
+* WARNING: As of this release, you must set disable_ssl_certificate_validation
+  to False when using Python3.
+* Added new examples for DFP Sales Manager: PremiumRateService, BaseRateService,
+  ExchangeRateService, RateCardService, WorkflowRequestService, ProductService,
+  ProductTemplateService.
+
 2.3.0 - 12/05/2014
 * Removed v201402 support.
 * The return_money_in_micros argument has been removed from the AdWords

examples/adwords/adwords_appengine_demo/ChangeLog

@@ -1,2 +1,6 @@
+1.0.1 - 1/5/2015
+- Updated dependencies listed in README, for the changes introduced in googleads
+  3.0.0.
+
 1.0.0:
 - Initial release of the demo.

examples/adwords/adwords_appengine_demo/README

@@ -60,30 +60,33 @@ prepared your OAuth2 Credentials via the Google Developers Console.
 6. Copy the httplib2 package from your Python installation's dist-packages
    directory into this project.
 
-7. Copy the oauthlib package from your Python installation's dist-packages
+7. Copy the oauth2client package from your Python installation's dist-packages
    directory into this project.
 
 8. Copy the pytz package from your Python installation's dist-packages
    directory into this project.
 
-9. Copy the suds package from your Python installation's dist-packages
+9. Copy socks.py from the PySocks tarball found in your Python installation's
+   dist-packages directory into this project.
+
+10. Copy the suds package from your Python installation's dist-packages
    directory into this project.
 
-10. Create an App Engine application in the
+11. Create an App Engine application in the
    [Google App Engine Console](https://appengine.google.com/).
 
-11. Go to this project's app.yaml, and enter in your application name for the
+12. Go to this project's app.yaml, and enter in your application name for the
    "application" field.
 
-12. You can now deploy this project by running the following command:
+13. You can now deploy this project by running the following command:
 
     `python $APPENGINE_SDK_DIR/appcfg --oauth2 update .`
 
-12. When you go to your App for the first time, you will need to log in and
+14. When you go to your App for the first time, you will need to log in and
     provide OAuth2 and AdWords API credentials. You can use credentials
     generated via the generate_refresh_token.py example.
 
-13. With all information entered, you can now use the UI to view and modify
+15. With all information entered, you can now use the UI to view and modify
     your account details.
 
 
@@ -97,7 +100,8 @@ Submit bug reports or feature requests to our
 
 * [Python v2.7](https://www.python.org/downloads/)
 * [httplib2 v0.9+](https://pypi.python.org/pypi/httplib2)
-* [oauthlib v0.6.3+](https://pypi.python.org/pypi/oauthlib)
+* [oauth2client v1.4.5+](https://pypi.python.org/pypi/oauth2client/)
+* [pysocks v1.5.0+](https://pypi.python.org/pypi/PySocks/)
 * [pytz 2014.7+](https://pypi.python.org/pypi/pytz)
 * [suds-jurko 0.6+](https://pypi.python.org/pypi/suds-jurko)
 * [App Engine SDK v1.9.11+](https://developers.google.com/appengine/downloads)

examples/adwords/authentication/create_adwords_client_with_service_account.py

@@ -0,0 +1,51 @@
+#!/usr/bin/python
+#
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Initializes an AdWordsClient via impersonation using a Service Account."""
+
+__author__ = 'Mark Saniscalchi'
+
+from googleads import adwords
+from googleads import oauth2
+
+# OAuth 2.0 credential information. In a real application, you'd probably be
+# pulling these values from a credential storage.
+SERVICE_ACCOUNT_EMAIL = 'INSERT_SERVICE_ACCOUNT_EMAIL_HERE'
+KEY_FILE = 'INSERT_PATH_TO_KEY_FILE'
+SERVICE_ACCOUNT_USER = 'INSERT_IMPERSONATED_EMAIL_HERE'
+
+# AdWords API information.
+DEVELOPER_TOKEN = 'INSERT_DEVELOPER_TOKEN_HERE'
+USER_AGENT = 'INSERT_USER_AGENT_HERE'
+CLIENT_CUSTOMER_ID = 'INSERT_CLIENT_CUSTOMER_ID_HERE'
+
+
+def main(service_account_email, key_file, service_account_user,
+         developer_token, user_agent, client_customer_id):
+  oauth2_client = oauth2.GoogleServiceAccountClient(
+      oauth2.GetAPIScope('adwords'), service_account_email, key_file,
+      sub=service_account_user)
+
+  adwords_client = adwords.AdWordsClient(
+      developer_token, oauth2_client, user_agent, client_customer_id)
+
+  customer = adwords_client.GetService('CustomerService').get()
+  print 'You are logged in as customer: %s' % customer['customerId']
+
+
+if __name__ == '__main__':
+  main(SERVICE_ACCOUNT_EMAIL, KEY_FILE, SERVICE_ACCOUNT_USER,
+       DEVELOPER_TOKEN, USER_AGENT, CLIENT_CUSTOMER_ID)

examples/adwords/authentication/generate_refresh_token.py

@@ -16,61 +16,46 @@
 
 """Generates refresh token for AdWords using the Installed Application flow."""
 
-__author__ = 'Joseph DiLallo'
+__author__ = 'Mark Saniscalchi'
 
 import sys
-import urllib2
 
-from oauthlib import oauth2
+from oauth2client import client
 
 # Your OAuth 2.0 Client ID and Secret. If you do not have an ID and Secret yet,
 # please go to https://console.developers.google.com and create a set.
 CLIENT_ID = 'INSERT_CLIENT_ID_HERE'
 CLIENT_SECRET = 'INSERT_CLIENT_SECRET_HERE'
 
-# You may optionally provide an HTTPS proxy.
-HTTPS_PROXY = None
-
 # The AdWords API OAuth 2.0 scope.
 SCOPE = u'https://www.googleapis.com/auth/adwords'
-# This callback URL will allow you to copy the token from the success screen.
-CALLBACK_URL = 'urn:ietf:wg:oauth:2.0:oob'
-# The HTTP headers needed on OAuth 2.0 refresh requests.
-OAUTH2_REFRESH_HEADERS = {'content-type':
-                          'application/x-www-form-urlencoded'}
-# The web address for generating new OAuth 2.0 credentials at Google.
-GOOGLE_OAUTH2_AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/auth'
-GOOGLE_OAUTH2_GEN_ENDPOINT = 'https://accounts.google.com/o/oauth2/token'
 
 
 def main():
-  oauthlib_client = oauth2.WebApplicationClient(CLIENT_ID)
-
-  authorize_url = oauthlib_client.prepare_request_uri(
-      GOOGLE_OAUTH2_AUTH_ENDPOINT, redirect_uri=CALLBACK_URL, scope=SCOPE)
-  print ('Log in to your AdWords account and open the following URL: \n%s\n' %
-         authorize_url)
+  """Retrieve and display the access and refresh token."""
+  flow = client.OAuth2WebServerFlow(
+      client_id=CLIENT_ID,
+      client_secret=CLIENT_SECRET,
+      scope=[SCOPE],
+      user_agent='Ads Python Client Library',
+      redirect_uri='urn:ietf:wg:oauth:2.0:oob')
+
+  authorize_url = flow.step1_get_authorize_url()
+
+  print ('Log into the Google Account you use to access your AdWords account'
+         'and go to the following URL: \n%s\n' % (authorize_url))
   print 'After approving the token enter the verification code (if specified).'
   code = raw_input('Code: ').strip()
 
-  post_body = oauthlib_client.prepare_request_body(
-      client_secret=CLIENT_SECRET, code=code, redirect_uri=CALLBACK_URL)
-  if sys.version_info[0] == 3:
-    post_body = bytes(post_body, 'utf8')
-  request = urllib2.Request(GOOGLE_OAUTH2_GEN_ENDPOINT, post_body,
-                            OAUTH2_REFRESH_HEADERS)
-  if HTTPS_PROXY:
-    request.set_proxy(HTTPS_PROXY, 'https')
-  raw_response = urllib2.urlopen(request).read().decode()
-  oauth2_credentials = oauthlib_client.parse_request_body_response(raw_response)
-
-  print ('Your access token is %s and your refresh token is %s'
-         % (oauth2_credentials['access_token'],
-            oauth2_credentials['refresh_token']))
-  print ('You can cache these credentials into a yaml file with the '
-         'following keys:\nadwords:\n  client_id: %s\n  client_secret: %s\n'
-         '  refresh_token: %s\n'
-         % (CLIENT_ID, CLIENT_SECRET, oauth2_credentials['refresh_token']))
+  try:
+    credential = flow.step2_exchange(code)
+  except client.FlowExchangeError, e:
+    print 'Authentication has failed: %s' % e
+    sys.exit(1)
+  else:
+    print ('OAuth 2.0 authorization successful!\n\n'
+           'Your access token is:\n %s\n\nYour refresh token is:\n %s'
+           % (credential.access_token, credential.refresh_token))
 
 
 if __name__ == '__main__':

examples/dfa/authentication/create_dfa_client_with_service_account.py

@@ -0,0 +1,54 @@
+#!/usr/bin/python
+#
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Initializes a DfaClient via impersonation using a Service Account."""
+
+__author__ = 'Mark Saniscalchi'
+
+from googleads import dfa
+from googleads import oauth2
+
+# OAuth 2.0 credential information. In a real application, you'd probably be
+# pulling these values from a credential storage.
+SERVICE_ACCOUNT_EMAIL = 'INSERT_SERVICE_ACCOUNT_EMAIL_HERE'
+KEY_FILE = 'INSERT_PATH_TO_KEY_FILE'
+SERVICE_ACCOUNT_USER = 'INSERT_IMPERSONATED_EMAIL_HERE'
+
+# DFA API information.
+USER_PROFILE_NAME = 'INSERT_USER_PROFILE_NAME_HERE'
+APPLICATION_NAME = 'INSERT_APPLICATION_NAME_HERE'
+
+
+def main(service_account_email, key_file, service_account_user,
+         user_profile_name, application_name):
+  oauth2_client = oauth2.GoogleServiceAccountClient(
+      oauth2.GetAPIScope('dfa'), service_account_email, key_file,
+      sub=service_account_user)
+
+  dfa_client = dfa.DfaClient(user_profile_name, oauth2_client, application_name)
+
+  campaign_service = dfa_client.GetService(
+      'campaign', server='https://advertisersapitest.doubleclick.net')
+  results = campaign_service.getCampaignsByCriteria({})
+  if results['records']:
+    for campaign in results['records']:
+      print ('Campaign with name \'%s\' and ID \'%s\' was found.'
+             % (campaign['name'], campaign['id']))
+
+
+if __name__ == '__main__':
+  main(SERVICE_ACCOUNT_EMAIL, KEY_FILE, SERVICE_ACCOUNT_USER, USER_PROFILE_NAME,
+       APPLICATION_NAME)

examples/dfa/authentication/generate_refresh_token.py

@@ -16,61 +16,46 @@
 
 """Generates a refresh token for use with DFA."""
 
-__author__ = 'Joseph DiLallo'
+__author__ = 'Mark Saniscalchi'
 
 import sys
-import urllib2
 
-from oauthlib import oauth2
+from oauth2client import client
 
 # Your OAuth 2.0 Client ID and Secret. If you do not have an ID and Secret yet,
 # please go to https://console.developers.google.com and create a set.
 CLIENT_ID = 'INSERT_CLIENT_ID_HERE'
 CLIENT_SECRET = 'INSERT_CLIENT_SECRET_HERE'
 
-# You may optionally provide an HTTPS proxy.
-HTTPS_PROXY = None
-
 # The DFA API OAuth 2.0 scope.
 SCOPE = u'https://www.googleapis.com/auth/dfatrafficking'
-# This callback URL will allow you to copy the token from the success screen.
-CALLBACK_URL = 'urn:ietf:wg:oauth:2.0:oob'
-# The HTTP headers needed on OAuth 2.0 refresh requests.
-OAUTH2_REFRESH_HEADERS = {'content-type':
-                          'application/x-www-form-urlencoded'}
-# The web address for generating new OAuth 2.0 credentials at Google.
-GOOGLE_OAUTH2_AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/auth'
-GOOGLE_OAUTH2_GEN_ENDPOINT = 'https://accounts.google.com/o/oauth2/token'
 
 
 def main():
-  oauthlib_client = oauth2.WebApplicationClient(CLIENT_ID)
-
-  authorize_url = oauthlib_client.prepare_request_uri(
-      GOOGLE_OAUTH2_AUTH_ENDPOINT, redirect_uri=CALLBACK_URL, scope=SCOPE)
-  print ('Log in to your DFA account and open the following URL: \n%s\n' %
-         authorize_url)
+  """Retrieve and display the access and refresh token."""
+  flow = client.OAuth2WebServerFlow(
+      client_id=CLIENT_ID,
+      client_secret=CLIENT_SECRET,
+      scope=[SCOPE],
+      user_agent='Ads Python Client Library',
+      redirect_uri='urn:ietf:wg:oauth:2.0:oob')
+
+  authorize_url = flow.step1_get_authorize_url()
+
+  print ('Log into the Google Account you use to access your DFA account'
+         'and go to the following URL: \n%s\n' % (authorize_url))
   print 'After approving the token enter the verification code (if specified).'
   code = raw_input('Code: ').strip()
 
-  post_body = oauthlib_client.prepare_request_body(
-      client_secret=CLIENT_SECRET, code=code, redirect_uri=CALLBACK_URL)
-  if sys.version_info[0] == 3:
-    post_body = bytes(post_body, 'utf8')
-  request = urllib2.Request(GOOGLE_OAUTH2_GEN_ENDPOINT, post_body,
-                            OAUTH2_REFRESH_HEADERS)
-  if HTTPS_PROXY:
-    request.set_proxy(HTTPS_PROXY, 'https')
-  raw_response = urllib2.urlopen(request).read().decode()
-  oauth2_credentials = oauthlib_client.parse_request_body_response(raw_response)
-
-  print ('Your access token is %s and your refresh token is %s'
-         % (oauth2_credentials['access_token'],
-            oauth2_credentials['refresh_token']))
-  print ('You can cache these credentials into a yaml file with the '
-         'following keys:\ndfa:\n  client_id: %s\n  client_secret: %s\n'
-         '  refresh_token: %s\n'
-         % (CLIENT_ID, CLIENT_SECRET, oauth2_credentials['refresh_token']))
+  try:
+    credential = flow.step2_exchange(code)
+  except client.FlowExchangeError, e:
+    print 'Authentication has failed: %s' % e
+    sys.exit(1)
+  else:
+    print ('OAuth 2.0 authorization successful!\n\n'
+           'Your access token is:\n %s\n\nYour refresh token is:\n %s'
+           % (credential.access_token, credential.refresh_token))
 
 
 if __name__ == '__main__':