Merge pull request #195 from gsuitedevs/manifest

Mention not needing the library for Google APIs

Author: asrivas

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

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);
+  });
+}

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

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"
+  ]
+}