Google Ad Manager rebrand & v201808 release

CONTRIBUTING.md

@@ -13,8 +13,7 @@ Follow either of the two links above to access the appropriate CLA and instructi
 - Sign a Contributor License Agreement (see above).
 - Join the appropriate product discussion forum.
   - AdWords API: https://developers.google.com/adwords/api/community/
-  - DFP API: https://developers.google.com/doubleclick-publishers/community
-  - DFA API: https://developers.google.com/doubleclick-advertisers/reporting/community
+  - Ad Manager API: https://developers.google.com/ad-manager/community
 - Create an issue on the library issue tracker if there isn't one already. Use this issue to co-ordinate the changes with the library maintainer.
 - Fork the library, make the changes and send a [pull request](https://help.github.com/articles/using-pull-requests).
 - The library maintainer will work with you to review and apply the patch.

ChangeLog

@@ -1,3 +1,9 @@
+14.0.0 -- 08/21/18
+- DFP rebranded to Google Ad Manager.
+- Google Ad Manager v201808 release.
+- Removed support for DFP v201708.
+- Removed examples for DFP v201711.
+
 13.0.0 -- 07/25/18
 - Removed support for AdWords v201710.
 

README.md

@@ -1,5 +1,8 @@
 # The googleads Python client library
 
+**Note:** DoubleClick for Publishers was recently renamed to Google Ad Manager, and this library
+was modified to follow suit. Please see the [migration guide](https://github.com/googleads/googleads-python-lib/wiki/dfp-rebrand)
+for more details.
 
 This client library simplifies accessing Google's SOAP Ads APIs - AdWords,
 and DoubleClick for Publishers. The library provides easy ways to store your
@@ -40,19 +43,19 @@ code to help you get started integrating with our APIs.
    **If you're accessing an API using your own credentials...**
 
    * [Using AdWords](https://github.com/googleads/googleads-python-lib/wiki/API-access-using-own-credentials-(installed-application-flow))
-   * [Using DFP](https://github.com/googleads/googleads-python-lib/wiki/API-access-using-own-credentials-(server-to-server-flow))
+   * [Using Ad Manager](https://github.com/googleads/googleads-python-lib/wiki/API-access-using-own-credentials-(server-to-server-flow))
 
    **If you're accessing an API on behalf of clients...**
 
-   * [Developing a web application (AdWords or DFP)](https://github.com/googleads/googleads-python-lib/wiki/API-access-on-behalf-of-your-clients-(web-flow))
+   * [Developing a web application (AdWords or Ad Manager)](https://github.com/googleads/googleads-python-lib/wiki/API-access-on-behalf-of-your-clients-(web-flow))
 
 #### Where can I find samples?
 
-You can find code examples for the latest versions of AdWords or DFP on the
+You can find code examples for the latest versions of AdWords or Ad Manager on the
 [releases](https://github.com/googleads/googleads-python-lib/releases) page.
 
 Alternatively, you can find [AdWords](https://github.com/googleads/googleads-python-lib/tree/master/examples/adwords)
-or [DFP](https://github.com/googleads/googleads-python-lib/tree/master/examples/dfp)
+or [Ad Manager](https://github.com/googleads/googleads-python-lib/tree/master/examples/ad_manager)
 samples in the examples directory of this repository.
 
 #### Where can I find the pydocs?
@@ -73,7 +76,7 @@ contents.
 adwords_client = adwords.AdWordsClient.LoadFromStorage()
 
 # Alternatively, pass in the location of the file:
-dfp_client = dfp.DfpClient.LoadFromStorage('C:\My\Directory\googleads.yaml')
+ad_manager_client = ad_manager.AdManagerClient.LoadFromStorage('C:\My\Directory\googleads.yaml')
 ```
 
 #### How do I change the Client Customer Id at runtime?
@@ -200,7 +203,7 @@ access a local file system that may not be available in certain hosting
 environments such as App Engine.
 
 You can pass an implementation of `suds.cache.Cache` or `zeep.cache.Base` to the `AdWordsClient` or
-`DfpClient` initializer to modify the default caching behavior.
+`AdManagerClient` initializer to modify the default caching behavior.
 
 For example, configuring a different location and duration of the cache file with zeep
 ```python

examples/ad_manager/authentication/create_ad_manager_client_with_access_token.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+#
+# Copyright 2017 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 AdManagerClient using GoogleAccessTokenClient.
+
+Note that unlike clients initialized with GoogleRefreshTokenClient, those
+initialized with GoogleAccessTokenClient can't refresh.
+"""
+
+import argparse
+import datetime
+from googleads import ad_manager
+from googleads import oauth2
+import httplib2
+from oauth2client import client
+
+
+GOOGLE_OAUTH2_ENDPOINT = 'https://accounts.google.com/o/oauth2/token'
+USER_AGENT = 'INSERT_USER_AGENT_HERE'
+
+# OAuth2 credential information.
+DEFAULT_CLIENT_ID = 'INSERT_CLIENT_ID_HERE'
+DEFAULT_CLIENT_SECRET = 'INSERT_CLIENT_SECRET_HERE'
+DEFAULT_REFRESH_TOKEN = 'INSERT_REFRESH_TOKEN_HERE'
+
+# Ad Manager API information.
+DEFAULT_APPLICATION_NAME = 'INSERT_APPLICATION_NAME_HERE'
+
+parser = argparse.ArgumentParser(
+    description=('Creates an AdManagerClient using a GoogleAccessToken with an '
+                 'access token generated with the given credentials.'))
+parser.add_argument('--client_id', default=DEFAULT_CLIENT_ID,
+                    help='Client Id retrieved from the Developer\'s Console.')
+parser.add_argument('--client_secret', default=DEFAULT_CLIENT_SECRET,
+                    help='Client Secret retrieved from the Developer\'s '
+                    'Console.')
+parser.add_argument('--refresh_token', default=DEFAULT_REFRESH_TOKEN,
+                    help='The refresh token used to generate an access token.')
+parser.add_argument('--application_name', default=DEFAULT_APPLICATION_NAME,
+                    help='The application name for your Ad Manager account.')
+
+
+def main(access_token, token_expiry, application_name):
+  oauth2_client = oauth2.GoogleAccessTokenClient(access_token, token_expiry)
+
+  ad_manager_client = ad_manager.AdManagerClient(
+      oauth2_client, application_name)
+
+  networks = ad_manager_client.GetService('NetworkService').getAllNetworks()
+  for network in networks:
+    print ('Network with network code "%s" and display name "%s" was found.'
+           % (network['networkCode'], network['displayName']))
+
+
+if __name__ == '__main__':
+  args = parser.parse_args()
+
+  # Retrieve a new access token for use in this example. In a production
+  # application, you may use a credential store to share access tokens for a
+  # given user across applications.
+  oauth2credentials = client.OAuth2Credentials(
+      None, args.client_id, args.client_secret, args.refresh_token,
+      datetime.datetime(1980, 1, 1, 12), GOOGLE_OAUTH2_ENDPOINT,
+      USER_AGENT)
+
+  oauth2credentials.refresh(httplib2.Http())
+
+  main(oauth2credentials.access_token, oauth2credentials.token_expiry,
+       args.application_name)

examples/ad_manager/authentication/create_ad_manager_client_with_refresh_token.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env 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 AdManagerClient without using yaml-cached credentials.
+
+While our LoadFromStorage method provides a useful shortcut to instantiate a
+client if you regularly use just one set of credentials, production applications
+may need to swap out users. This example shows you how to create an OAuth2
+client and a AdManagerClient without relying on a yaml file.
+"""
+
+
+from googleads import ad_manager
+from googleads import oauth2
+
+# OAuth2 credential information. In a real application, you'd probably be
+# pulling these values from a credential storage.
+CLIENT_ID = 'INSERT_CLIENT_ID_HERE'
+CLIENT_SECRET = 'INSERT_CLIENT_SECRET_HERE'
+REFRESH_TOKEN = 'INSERT_REFRESH_TOKEN_HERE'
+
+# Ad Manager API information.
+APPLICATION_NAME = 'INSERT_APPLICATION_NAME_HERE'
+
+
+def main(client_id, client_secret, refresh_token, application_name):
+  oauth2_client = oauth2.GoogleRefreshTokenClient(
+      client_id, client_secret, refresh_token)
+
+  ad_manager_client = ad_manager.AdManagerClient(
+      oauth2_client, application_name)
+
+  networks = ad_manager_client.GetService('NetworkService').getAllNetworks()
+  for network in networks:
+    print ('Network with network code "%s" and display name "%s" was found.'
+           % (network['networkCode'], network['displayName']))
+
+
+if __name__ == '__main__':
+  main(CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, APPLICATION_NAME)

examples/ad_manager/authentication/create_ad_manager_client_with_service_account.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env 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 AdManagerClient using a Service Account."""
+
+
+from googleads import ad_manager
+from googleads import oauth2
+
+# OAuth2 credential information. In a real application, you'd probably be
+# pulling these values from a credential storage.
+KEY_FILE = 'INSERT_KEY_FILE_PATH'
+
+# Ad Manager API information.
+APPLICATION_NAME = 'INSERT_APPLICATION_NAME_HERE'
+
+
+def main(key_file, application_name):
+  oauth2_client = oauth2.GoogleServiceAccountClient(
+      key_file, oauth2.GetAPIScope('ad_manager'))
+
+  ad_manager_client = ad_manager.AdManagerClient(
+      oauth2_client, application_name)
+
+  networks = ad_manager_client.GetService('NetworkService').getAllNetworks()
+  for network in networks:
+    print ('Network with network code "%s" and display name "%s" was found.'
+           % (network['networkCode'], network['displayName']))
+
+
+if __name__ == '__main__':
+  main(KEY_FILE, APPLICATION_NAME)

examples/dfp/authentication/generate_refresh_token.py → examples/ad_manager/authentication/generate_refresh_token.py

@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Generates a refresh token for use with DFP."""
+"""Generates a refresh token for use with Ad Manager."""
 
 
 import argparse
@@ -28,7 +28,7 @@
 DEFAULT_CLIENT_ID = None
 DEFAULT_CLIENT_SECRET = None
 
-# The DFP API OAuth2 scope.
+# The Ad Manager API OAuth2 scope.
 SCOPE = u'https://www.googleapis.com/auth/dfp'
 # The redirect URI set for the given Client ID. The redirect URI for Client ID
 # generated for an installed application will always have this value.
@@ -95,7 +95,7 @@ def main(client_id, client_secret, scopes):
 
   auth_url, _ = flow.authorization_url(prompt='consent')
 
-  print ('Log into the Google Account you use to access your DFP account'
+  print ('Log into the Google Account you use to access your Ad Manager account'
          'and go to the following URL: \n%s\n' % (auth_url))
   print 'After approving the token enter the verification code (if specified).'
   code = raw_input('Code: ').strip()

examples/ad_manager/v201802/activity_group_service/create_activity_groups.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+#
+# Copyright 2015 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.
+
+"""This code example creates new activity groups.
+
+To determine which activity groups exist, run get_all_activity_groups.py.
+
+The LoadFromStorage method is pulling credentials and properties from a
+"googleads.yaml" file. By default, it looks for this file in your home
+directory. For more information, see the "Caching authentication information"
+section of our README.
+
+"""
+
+
+import uuid
+
+# Import appropriate modules from the client library.
+from googleads import ad_manager
+
+# Set the ID of the advertiser company this activity group is associated with.
+ADVERTISER_COMPANY_ID = 'INSERT_ADVERTISER_COMPANY_ID_HERE'
+
+
+def main(client, advertiser_company_id):
+  # Initialize appropriate service.
+  activity_group_service = client.GetService('ActivityGroupService',
+                                             version='v201802')
+
+  # Create a short-term activity group.
+  short_term_activity_group = {
+      'name': 'Short-term activity group #%s' % uuid.uuid4(),
+      'companyIds': [advertiser_company_id],
+      'clicksLookback': '1',
+      'impressionsLookback': '1'
+  }
+
+  # Create a long-term activity group.
+  long_term_activity_group = {
+      'name': 'Long-term activity group #%s' % uuid.uuid4(),
+      'companyIds': [advertiser_company_id],
+      'clicksLookback': '30',
+      'impressionsLookback': '30'
+  }
+
+  # Create the activity groups on the server.
+  activity_groups = activity_group_service.createActivityGroups([
+      short_term_activity_group, long_term_activity_group])
+
+  # Display results.
+  for activity_group in activity_groups:
+    print ('Activity group with ID "%s" and name "%s" was created.'
+           % (activity_group['id'], activity_group['name']))
+
+if __name__ == '__main__':
+  # Initialize client object.
+  ad_manager_client = ad_manager.AdManagerClient.LoadFromStorage()
+  main(ad_manager_client, ADVERTISER_COMPANY_ID)