Advanced Google services

The advanced services in Apps Script let experienced developers connect to certain public Google APIs with less set-up than using their HTTP interfaces. Advanced services are essentially thin wrappers around those Google APIs. They work much like Apps Script's built-in services—for example, they offer autocomplete, and Apps Script handles the authorization flow automatically. However, you must enable an advanced service before you can use it in a script.

To see which Google APIs are available as advanced services, look for the Advanced Google Services section in the Reference. If you want to use a Google API that isn't available as an advanced service, just connect to it like any other external API.

Advanced services or HTTP?

Each of the advanced Google services is associated with a public Google API. In Apps Script, you can access these APIs via advanced services or by simply making the API requests directly using UrlFetch.

If you use the advanced service method, Apps Script handles the authorization flow and offers autocomplete support. However, you must enable the advanced service before you can use it. In addition, some advanced services only provide a subset of the functionality available in the API.

If you use the UrlFetch method to access the API directly, you are essentially treating the Google API as an external API. With this method, all aspects of the API can be used. However, it requires you to handle the API authorization yourself. You must also construct any needed headers and parse the API responses.

In general it's easiest to use an advanced service where possible and only use the UrlFetch method when the advanced service doesn't provide the functionality you need.

Requirements

Enabling advanced services requires that you have access to the script's Cloud Platform project. When you collaborate on a project in Team Drives, your access to the Cloud Platform project may be restricted; see the Cloud Project and Team Drives guide section for details.

You may wish to switch the Apps Script to use a standard Cloud Platform project in order to have direct access to the API monitoring information in the API Console dashboard. Doing so also ensures you and your collaborators have access to the Cloud Platform project settings while the script resides in a Team Drive.

Enabling advanced services

To use an advanced Google service, follow these instructions:

  1. In the script editor, select Resources > Advanced Google services....
  2. In the dialog that appears, click the on/off switch next to the service you want to use.
  3. At the bottom of the dialog, click the link for the Google API Console.
  4. In the console, click into the filter box and type part of the name of the API (for example, "Calendar"), then click the name once you see it.
  5. On the next screen, click Enable API.
  6. Close the API Console and return to the script editor. Click OK in the dialog. The advanced service you enabled is now available in autocomplete.

How method signatures are determined

Advanced services generally use the same objects, method names, and parameters as the corresponding public APIs, although method signatures are translated for use in Apps Script. The script editor's autocomplete function usually provides enough information to get started, but the rules below explain how Apps Script generates a method signature from a public Google API.

Requests to Google APIs can accept a variety of different types of data, including path parameters, query parameters, a request body, and/or a media upload attachment. Some advanced services can also accept specific HTTP request headers (for example, the Calendar advanced service).

The corresponding method signature in Google Apps Script has the following arguments:

  1. The request body (usually a resource), as a JavaScript object.
  2. Path or required parameters, as individual arguments.
  3. The media upload attachment, as a Blob argument.
  4. Optional parameters, as a JavaScript object mapping parameter names to values.
  5. HTTP request headers, as a JavaScript object mapping header names to header values.

If the method doesn't have any items in a given category, that part of the signature is omitted.

There are some special exceptions to be aware of:

  • For methods that accept a media upload, the parameter uploadType is set automatically.
  • Methods named delete in the Google API are named remove in Apps Script, since delete is a reserved word in JavaScript.
  • If an advanced service is configured to accept HTTP request headers, and you set a request headers JavaScript object, then you must also set the optional parameters JavaScript object (to an empty object if you aren't using optional parameters).

Support for advanced services

Advanced services are just thin wrappers that enables the use of a Google APIs within Apps Script. As such, any issue encountered while using them is usually an issue with the underlying API, not with Apps Script itself.

If you encounter a problem while using an advanced service, it should be reported using the support instructions for the underlying API. Links to these support instructions are provided in each advanced service guide in the Apps Script Reference section.

Feedback geben zu...