Skip to content

Commit ca3f821

Browse files
BenRKarlBenRKarl
authored
Add Service account support and refactor credentials and oauth logic. (googleads#129)
1 parent 339d9d4 commit ca3f821

8 files changed

Lines changed: 840 additions & 289 deletions

File tree

‎README.rst‎

Lines changed: 52 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ Requirements
1616
* `pip`_
1717

1818

19+
Documentation
20+
-------------
21+
This README has general information to get you started with the library, but more
22+
extensive documentation can be found on our `Developer Site`_.
23+
1924
Getting started
2025
---------------
2126

@@ -33,8 +38,12 @@ Configuration file setup
3338
########################
3439

3540
To authenticate your API calls, you must specify your **client ID**,
36-
**client secret**, **refresh token**, **developer token**, and, if
37-
you are authenticating with a manager account, a **login customer id**.
41+
**client secret**, **refresh token**, **developer token**, or, if you
42+
are authenticating via a service account you will instead need to specify
43+
a **path_to_private_key_file** and **delegate_account**. If you
44+
are authenticating with a manager account you will need to provide a
45+
**login customer id** configuration value.
46+
3847
If you have not yet created a client ID, see the `Authorization guide`_
3948
and the `authentication samples`_ to get started. Likewise, see
4049
`Obtain your developer token`_ if you do not yet have one.
@@ -44,8 +53,20 @@ class method, the default behavior is to load a configuration file named
4453
**google-ads.yaml** located in your home directory. Included in this repository
4554
is a `template`_ you can use.
4655

47-
For a complete walk-through of the OAuth Installed Application flow in Python,
48-
please refer to `this page of the wiki`_.
56+
For a complete walk-through of how to configure this library, please refer
57+
to our `configuration documentation`_.
58+
59+
OAuth2 Options
60+
##############
61+
62+
This client library can authenticate using one of three different OAuth2 flows, either the
63+
`Installed Application Flow`_, the `Web Application Flow`_ or the `Service Account Flow`_.
64+
The Installed Application Flow and Web Application Flow use the same credentials and are
65+
functionally identical in terms of configuring this library. When retrieving the
66+
configuration for these authentication flows, if configuration is present
67+
for _both_ types of flows the library will default to using the Installed/Web Application
68+
Flow. If you wish to use the Service Account Flow you must make sure that the Installed/Web
69+
Application Flow `configuration values`_ are not present in your configuration.
4970

5071
Create a GoogleAdsClient
5172
########################
@@ -58,21 +79,32 @@ configuration file named **google-ads.yaml** stored in your home directory:
5879

5980
.. code-block:: python
6081
61-
client = google.ads.google_ads.client.GoogleAdsClient.load_from_storage()
82+
from google.ads.google_ads.client import GoogleAdsClient
83+
client = GoogleAdsClient.load_from_storage()
6284
6385
Using environment variables
6486
***************************
6587

66-
You can also retrieve it exporting environment variables.
88+
You can also retrieve it by exporting environment variables.
6789

6890
* Required:
6991

7092
.. code-block:: bash
7193
94+
export GOOGLE_ADS_DEVELOPER_TOKEN=INSERT_DEVELOPER_TOKEN_HERE
95+
96+
* Required for OAuth2 Installed Application Flow
97+
98+
.. code-block::bash
99+
72100
export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
73101
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
74102
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE
75-
export GOOGLE_ADS_DEVELOPER_TOKEN=INSERT_DEVELOPER_TOKEN_HERE
103+
104+
* Required for OAuth2 Service Account Flow:
105+
106+
export GOOGLE_ADS_PATH_TO_PRIVATE_KEY_FILE=INSERT_PRIVATE_KEY_PATH_HERE
107+
export GOOGLE_ADS_DELEGATED_ACCOUNT=INSERT_DELEGATED_ACCOUNT_HERE
76108

77109
* Optional:
78110

@@ -94,8 +126,11 @@ Then run the following to retrieve a GoogleAdsClient instance:
94126

95127
.. code-block:: python
96128
97-
client = google.ads.google_ads.client.GoogleAdsClient.load_from_env()
129+
from google.ads.google_ads.client import GoogleAdsClient
130+
client = GoogleAdsClient.load_from_env()
98131
132+
The `configuration documentation`_ has more information on how these different
133+
sets of variables are set and retrieved.
99134

100135
Get types and service clients
101136
#############################
@@ -114,6 +149,8 @@ retrieve the corresponding service client instance:
114149
115150
google_ads_service = client.get_service('GoogleAdsService')
116151
152+
More details can be found in our `proto getters documentation`_.
153+
117154
API versioning
118155
################################
119156
With the release of Google Ads API v1_0 it's now possible to specify an API
@@ -192,11 +229,17 @@ Authors
192229
* `David Wihl`_
193230
* `Ben Karl`_
194231

232+
.. _Developer Site: https://developers.google.com/google-ads/api/docs/client-libs/python/
233+
.. _Installed Application Flow: https://developers.google.com/google-ads/api/docs/client-libs/python/oauth-installed
234+
.. _Web Application Flow: https://developers.google.com/google-ads/api/docs/client-libs/python/oauth-web
235+
.. _Service Account Flow: https://developers.google.com/google-ads/api/docs/client-libs/python/oauth-service
236+
.. _configuration values: https://github.com/googleads/google-ads-python/blob/master/google-ads.yaml#L1
195237
.. _pip: https://pip.pypa.io/en/stable/installing
196238
.. _blog post: https://ads-developers.googleblog.com/2019/04/python-2-deprecation-in-ads-api-client.html
197239
.. _template: https://github.com/googleads/google-ads-python/blob/master/google-ads.yaml
198-
.. _this page of the wiki: https://github.com/googleads/google-ads-python/wiki/OAuth-Installed-Application-Flow
240+
.. _configuration documentation: https://developers.google.com/google-ads/api/docs/client-libs/python/configuration
199241
.. _Authorization guide: https://developers.google.com/google-ads/api/docs/oauth/overview
242+
.. _proto getters documentation: https://developers.google.com/google-ads/api/docs/client-libs/python/proto-getters
200243
.. _authentication samples: https://github.com/googleads/google-ads-python/blob/master/examples/authentication
201244
.. _Obtain your developer token: https://developers.google.com/google-ads/api/docs/first-call/dev-token
202245
.. _google-ads.yaml: https://github.com/googleads/google-ads-python/blob/master/google-ads.yaml

‎google-ads.yaml‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,37 @@
1+
-# OAuth2 configuration
2+
-###############################################################################
3+
-# The below configuration parameters are used to authenticate using the #
4+
-# recommended OAuth2 flow. For more information on authenticating with OAuth2 #
5+
-# see: https://developers.google.com/google-ads/api/docs/oauth/overview #
6+
-###############################################################################
17
developer_token: INSERT_DEVELOPER_TOKEN_HERE
28
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
39
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
410
refresh_token: INSERT_REFRESH_TOKEN_HERE
5-
# Required for manager accounts only: Specify the login customer ID used to
6-
# authenticate API calls. This will be the customer ID of the authenticated
7-
# manager account. It should be set without dashes, for example: 1234567890
8-
# instead of 123-456-7890. You can also specify this later in code if your
9-
# application uses multiple manager account + OAuth pairs.
11+
12+
-# Login customer ID configuration
13+
-###############################################################################
14+
-# Required for manager accounts only: Specify the login customer ID used to #
15+
-# authenticate API calls. This will be the customer ID of the authenticated #
16+
-# manager account. It should be set without dashes, for example: 1234567890 #
17+
-# instead of 123-456-7890. You can also specify this later in code if your #
18+
-# application uses multiple manager account + OAuth pairs. #
19+
-###############################################################################
1020
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
1121

22+
-# Service Account configuration
23+
-###############################################################################
24+
-# To authenticate with a service account add the appropriate values to the #
25+
-# below configuration parameters and remove the four OAuth credentials above. #
26+
-# The "path_to_private_key_file" value should be a path to your local private #
27+
-# key json file, and "delegated_account" should be the email address that is #
28+
-# being used to impersonate the credentials making requests. for more #
29+
-# information on service accounts, see: #
30+
-# https://developers.google.com/google-ads/api/docs/oauth/service-accounts #
31+
-###############################################################################
32+
-# path_to_private_key_file: INSERT_PATH_TO_JSON_KEY_FILE_HERE
33+
-# delegated_account: INSERT_DOMAIN_WIDE_DELEGATION_ACCOUNT
34+
1235
# Logging configuration
1336
###############################################################################
1437
# Below you may specify the logging configuration. This will be provided as #

0 commit comments

Comments
 (0)