diff options
author | Paul B <paul@bonaud.fr> | 2020-11-19 12:35:22 +0100 |
---|---|---|
committer | Paul B <paul@bonaud.fr> | 2020-11-21 00:32:35 +0100 |
commit | 4bf194076d39d516c3cd0f5c3559954ebe8a12f2 (patch) | |
tree | 422588a014088598ad93884f86224a90ee4333fa /README.md | |
parent | 1080d5ece1d90464c448c7e3f8dc58410fad0601 (diff) | |
download | tap-google-sheets-4bf194076d39d516c3cd0f5c3559954ebe8a12f2.tar.gz tap-google-sheets-4bf194076d39d516c3cd0f5c3559954ebe8a12f2.tar.zst tap-google-sheets-4bf194076d39d516c3cd0f5c3559954ebe8a12f2.zip |
feat: use the official Google API python library
These changes will make use of the official `google-api-python-client`
library instead of relying on manual HTTP requests.
Therer are two main advantages of these changes:
- the Tap doesn't need to worry about the Google API interaction
details as its hidden away by the Google official lib.
- We can use the authentication helpers from the lib to ease the
credentials management for the user. In that way the current PR
implements two auth mean: installed OAuth client authentication or
Service Accounts authentication.
The only downside of this change is that it breaks the current
`config.json` parameters for existing users.
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 34 |
1 files changed, 18 insertions, 16 deletions
@@ -67,16 +67,21 @@ This tap: | |||
67 | - Process/send records to target | 67 | - Process/send records to target |
68 | 68 | ||
69 | ## Authentication | 69 | ## Authentication |
70 | The [**Google Sheets Setup & Authentication**](https://drive.google.com/open?id=1FojlvtLwS0-BzGS37R0jEXtwSHqSiO1Uw-7RKQQO-C4) Google Doc provides instructions show how to configure the Google Cloud API credentials to enable Google Drive and Google Sheets APIs, configure Google Cloud to authorize/verify your domain ownership, generate an API key (client_id, client_secret), authenticate and generate a refresh_token, and prepare your tap config.json with the necessary parameters. | 70 | |
71 | - Enable Googe Drive APIs and Authorization Scope: https://www.googleapis.com/auth/drive.metadata.readonly | 71 | You will need a Google developer project to use this tool. After [creating a project](https://console.developers.google.com/projectcreate) (or selecting an existing one) in your Google developers console the authentication can be configured in two different ways: |
72 | - Enable Google Sheets API and Authorization Scope: https://www.googleapis.com/auth/spreadsheets.readonly | 72 | |
73 | - Tap config.json parameters: | 73 | - Via an OAuth client which will ask the user to login to its Google user account. |
74 | - client_id: identifies your application | 74 | |
75 | - client_secret: authenticates your application | 75 | Please check the [“Creating application credentials”](https://github.com/googleapis/google-api-python-client/blob/d0110cf4f7aaa93d6f56fc028cd6a1e3d8dd300a/docs/oauth-installed.md#creating-application-credentials) paragraph of the Google Python library to download your Google credentials file. |
76 | - refresh_token: generates an access token to authorize your session | 76 | |
77 | - spreadsheet_id: unique identifier for each spreadsheet in Google Drive | 77 | - Via a Service account (ideal for server-to-server communication) |
78 | - start_date: absolute minimum start date to check file modified | 78 | |
79 | - user_agent: tap-name and email address; identifies your application in the Remote API server logs | 79 | Please check the [“Creating a service account”](https://github.com/googleapis/google-api-python-client/blob/d0110cf4f7aaa93d6f56fc028cd6a1e3d8dd300a/docs/oauth-server.md#creating-a-service-account) paragraph of the Google Python library to download your Google Service Account key file. |
80 | |||
81 | - Tap `config.json` parameters: | ||
82 | - `credentials_file`: the path to a valid Google credentials file (Either an OAuth client secrets file or a Service Account key file) | ||
83 | - `spreadsheet_id`: unique identifier for each spreadsheet in Google Drive | ||
84 | - `start_date`: absolute minimum start date to check file modified | ||
80 | 85 | ||
81 | ## Quick Start | 86 | ## Quick Start |
82 | 87 | ||
@@ -103,16 +108,13 @@ The [**Google Sheets Setup & Authentication**](https://drive.google.com/open?id= | |||
103 | - [singer-tools](https://github.com/singer-io/singer-tools) | 108 | - [singer-tools](https://github.com/singer-io/singer-tools) |
104 | - [target-stitch](https://github.com/singer-io/target-stitch) | 109 | - [target-stitch](https://github.com/singer-io/target-stitch) |
105 | 110 | ||
106 | 3. Create your tap's `config.json` file. Include the client_id, client_secret, refresh_token, site_urls (website URL properties in a comma delimited list; do not include the domain-level property in the list), start_date (UTC format), and user_agent (tap name with the api user email address). | 111 | 3. Create your tap's `config.json` file. Include the `credentials_file` path to your google secrets file as described in the [Authentication](#authentication) paragraph. |
107 | 112 | ||
108 | ```json | 113 | ```json |
109 | { | 114 | { |
110 | "client_id": "YOUR_CLIENT_ID", | 115 | "credentials_file": "PATH_TO_YOUR_GOOGLE_CREDENTIALS_FILE", |
111 | "client_secret": "YOUR_CLIENT_SECRET", | ||
112 | "refresh_token": "YOUR_REFRESH_TOKEN", | ||
113 | "spreadsheet_id": "YOUR_GOOGLE_SPREADSHEET_ID", | 116 | "spreadsheet_id": "YOUR_GOOGLE_SPREADSHEET_ID", |
114 | "start_date": "2019-01-01T00:00:00Z", | 117 | "start_date": "2019-01-01T00:00:00Z" |
115 | "user_agent": "tap-google-sheets <api_user_email@example.com>" | ||
116 | } | 118 | } |
117 | ``` | 119 | ``` |
118 | 120 | ||