diff --git a/README.md b/README.md index 8ba2b26b..d5afca8a 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,31 @@ expire. This library uses Apps Script's [StateTokenBuilder](https://developers.google.com/apps-script/reference/script/state-token-builder) and `/usercallback` endpoint to handle the redirects. +## Connecting to a Google API + +If you are trying to connect to a Google API from Apps Script you might not need +to use this library at all. Apps Script has a number of easy-to-use, +[built-in services][built_in], as well as a variety of +[advanced services][advanced] that wrap existing Google REST APIs. + +Even if your API is not covered by either, you can still use Apps Script to +obtain the OAuth2 token for you. Simply +[edit the script's manifest][edit_manifest] to +[include the additional scopes][additional_scopes] that your API requires. +When the user authorizes your script they will also be asked to approve those +additional scopes. Then use the method [`ScriptApp.getOAuthToken()`][scriptapp] +in your code to access the OAuth2 access token the script has acquired and pass +it in the `Authorization` header of a `UrlFetchApp.fetch()` call. + +Visit the sample [`NoLibrary`](samples/NoLibrary) to see an example of how this +can be done. + +[built_in]: https://developers.google.com/apps-script/reference/calendar/ +[advanced]: https://developers.google.com/apps-script/advanced/admin-sdk-directory +[edit_manifest]: https://developers.google.com/apps-script/concepts/manifests#editing_a_manifest +[additional_scopes]: https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes +[scriptapp]: https://developers.google.com/apps-script/reference/script/script-app#getoauthtoken + ## Setup This library is already published as an Apps Script, making it easy to include diff --git a/samples/NoLibrary/Code.gs b/samples/NoLibrary/Code.gs new file mode 100644 index 00000000..efbf27a1 --- /dev/null +++ b/samples/NoLibrary/Code.gs @@ -0,0 +1,17 @@ +/** + * Use the Search Console API to list the URLs of all the sites you have setup. + * @see {@link https://developers.google.com/webmaster-tools/} + */ +function listSearchConsoleSites() { + var url = 'https://www.googleapis.com/webmasters/v3/sites'; + var token = ScriptApp.getOAuthToken(); + var response = UrlFetchApp.fetch(url, { + headers: { + Authorization: 'Bearer ' + token + } + }); + var result = JSON.parse(response.getContentText()); + result.siteEntry.forEach(function(siteEntry) { + Logger.log(siteEntry.siteUrl); + }); +} diff --git a/samples/NoLibrary/README.md b/samples/NoLibrary/README.md new file mode 100644 index 00000000..8d4a95d6 --- /dev/null +++ b/samples/NoLibrary/README.md @@ -0,0 +1,15 @@ +# Connect to a Google API without this library + +This sample demonstrates how to connect to a Google Search Console API, which is +not available natively in Apps Script. The +[script's manifest file][edit_manifest] +has been edited to [include the additional scope][additional_scopes] that the +API requires. When a user authorizes the script they will also be asked to +approve that additional scope. We can then use the method +[`ScriptApp.getOAuthToken()`][scriptapp] to access the OAuth2 access token the +script has acquired and pass it in the `Authorization` header of a +`UrlFetchApp.fetch()` call to the API. + +[edit_manifest]: https://developers.google.com/apps-script/concepts/manifests#editing_a_manifest +[additional_scopes]: https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes +[scriptapp]: https://developers.google.com/apps-script/reference/script/script-app#getoauthtoken diff --git a/samples/NoLibrary/appsscript.json b/samples/NoLibrary/appsscript.json new file mode 100644 index 00000000..19181c4e --- /dev/null +++ b/samples/NoLibrary/appsscript.json @@ -0,0 +1,10 @@ +{ + "timeZone": "America/New_York", + "dependencies": { + }, + "exceptionLogging": "STACKDRIVER", + "oauthScopes": [ + "https://www.googleapis.com/auth/script.external_request", + "https://www.googleapis.com/auth/webmasters" + ] +}