Author Archives: Google Apps Developer Blog Editor

Google Drive: Uploading & downloading files plus the new v3 API redux

Posted by Posted by Wesley Chun (@wescpy), Developer Advocate, Google Apps

Seasons greetings! In case you missed it last week, the Google Drive team announced the release of the next version of their API. Today, we dig deeper into details about the release with developers. In the latest edition of the Launchpad Online developer video series, you'll get everything you need to know about the new release (v3), as well as its relationship with the previous version (v2).

This jam-packed episode features an introduction to the new API, an interview with a Google Drive engineer about the API design and a code walkthrough of real source code you can use today (as with all my Launchpad Online episodes). This time, it's a command-line script that performs Google Drive file uploads and downloads, presented first in v2 followed by a how-to segment on migrating it step-by-step to v3. In addition, the uploading segment includes the option of converting to Google Apps formats while the download portion covers exporting to alternative formats such as PDF®.


To get started using the Drive API, check out the links to the official documentation above (v2 or v3) where you’ll also find quickstart samples in a variety of programming languages to the left. For a deeper dive into both Python code samples covered here, including v3 migration, start with the first of two related posts posted to my blog.

If you’re new to the Launchpad Online, we share technical content aimed at novice Google developers -current tools with a little bit of code to help you launch your next app. Please give us your feedback below and tell us what topics you would like to see in future episodes!

Advanced Development Process with Apps Script

Posted by Matt Hessinger, Project Specialist, Google Apps Script

Welcome to our 100th blog post on Apps Script! It’s amazing how far we’ve come from our first post back in 2010. We started out highlighting some of the simple ways that you could develop with the Apps platform. Today, we’re sharing tips and best practices for developing more complex Apps Script solutions by pointing out some community contributions.

Apps Script and modern development

The Apps Script editor does not allow you to use your own source code management tool, making it a challenge to collaborate with other developers. Managing development, test, and production versions of a project becomes very tedious. What if you could have the best of both worlds — the powerful integration with Google’s platform that Apps Script offers, along with the development tooling and best practices that you use every day? Now, you can.

npm install -g node-google-apps-script

This project, “node-google-apps-script”, is a Node.js based command-line interface (CLI) that uses Google Drive API to update Apps Script project from the command line. You can view the node package on the NPM site, and also view the GitHub repo. Both links have usage instructions. This tool was created by Dan Thareja, with additional features added by Matt Condon.

Before using the tool, take a look at the Apps Script Importing and Exporting Projects page. There are a few things that you should be aware of as you plan out your development process. There are also a few best practices that you can employ to take full advantage of developing in this approach.

There is a sample project that demonstrates some of the practices described in this post: click here to view that code on GitHub. To get all of the Apps Script samples, including this import/export development example:

git clone https://github.com/google/google-apps-script-samples.git
The sample is in the “import_export_development” subdirectory.

Your standalone Apps Script projects live in Google Drive. If you use a command-line interface (CLI) tool like the one linked above, you can work in your favorite editor, and commit and sync code to your chosen repository. You can add tasks in your task runner to push code up to one or more Apps Script projects, conditionally including or excluding code for different environments, checking coding style, linting, minifying, etc. You can more easily create and push UI-related files to a file host outside of Apps Script, which could be useful if those same files are used in other apps you are building.


Typical development tools, integrated with Apps Script via the Drive API

Apps Script Project Lifecycle Best-practices

In addition to the information on the Importing and Exporting Projects page, here are a few things to consider:

  • Your local file set is the master. If you add, delete or rename files locally, the next upload with either of the linked tools will automatically make the Apps Script project reflect your local file set.
  • You can name local files whatever you want. You just need to then append “.html” to any client-side “.js” or “.css” in a file staging task before uploading to your project. The tool referenced above treats any “.js” files that you stage for upload as Apps Script server script files (“.gs” in the editor). It treats any “.html” that you stage as “client” code that you’ll access via the HtmlService. This means that you can develop server scripts as JavaScript, with the “.js” extension, so that your local tools recognize JavaScript syntax. While developing, client-side code (i.e., code that you need to interact with via the HtmlService) can be “.html”, “.js”, or “.css”, allowing your editor to provide the right syntax highlighting and validation experience.

Over and above the editing experience, the biggest improvements you get by working outside the script editor is that you are no longer locked into working in just one Apps Script project. You can much more easily collaborate as a team, with individual developers having their own working Apps Script projects, while also having more controlled test, user acceptance and production versions, each with more process and security. Beyond just the consistency with other normal project practices, there are a few Apps Script specific ways you can leverage this multi-environment approach.


If you are going to use this approach, here are three best practices to consider:

  • Use specific configuration values for “local” development.
  • Build test methods that can run standalone.
  • Include dependencies for development and testing.

Best practice: Use specific configuration values for “local” development.

The provided sample shows a simple example of how a base configuration class could allow a developer to inject their local values for their own debugging and testing. In this case, the developer also added the annotation @NotOnlyCurrentDoc, which tells Apps Script that they need the full scope for Drive API access. In this project, the “production” deployment has the annotation @OnlyCurrentDoc, which leads to the OAuth scope that is limited to the document associated with script running as Sheets, Docs, or Forms add-on. If you add a standard file pattern to the source project’s “ignore” file, these developer-specific files will never get into the actual codebase.

Benefits for your project — Production can have more limited OAuth scopes, while a developer can use broader access during development. Developers can also have their own personal configuration settings to support their individual development efforts.

Best practice: Build test methods that can run standalone.

While there is no current way to trigger tests in an automated way, you still may want to author unit tests that validate specific functions within your projects. You’ll also likely have specific configuration values for testing. Once again, none of these files should make it into a production deployment. You can even use the Apps Script Execution API to drive those tests from a test runner!

Benefits for your project — You can author test functions, and keep them separate from the production Apps Script file. This slims down your production Apps Script project, and keeps the correct OAuth scopes that are needed for production users.

Best practice: Include dependencies for development and testing.

If you are developing an add-on for Sheets or Docs, and you expect to have an “active” item on the SpreadsheetApp. However when you are developing or testing, you may be running your Apps Script without an “active” context. If you need to develop in this mode, you can wrap the call to get the current active item in a method that also can determine what mode you are running in. This would allow your development or test instance to inject the ID of an “active” document to use for testing, while delegating to the getActive* result when running in a real context.

Benefits for your project — You can integrate better unit testing methodologies into your projects, even if the end deployment state dependents on resources that aren’t typically available when debugging.

Wrapping up

You now have the option to use your own development and source management tools. While you still do need to use the Apps Script editor in your application’s lifecycle — to publish as a web app or add-on, configure advanced services, etc. — taking this step will help you get the most out of the power of the Apps Script platform. Remember to check out Apps Script on the Google Developers site to get more information and samples for your Apps Script development.

If you happen to use python tools on the command line to facilitate your team’s build process, you can check out Joe Stump's python-gas-cli. You can view the package info here or the GitHub repo where you’ll also find usage instructions.

Here are some additional reference links related to this post:

Enhancements to the Classroom Share Button

Posted by Andrew Garrett, Software Engineer, Classroom API and Michael Stillwell, Developer Advocate, Google Apps

By popular developer request, the Classroom Share Button now supports JavaScript callbacks and a question post type (in addition to announcements and assignments).

The following callbacks are supported:

  • onsharestart is called immediately after the user clicks the share button
  • onsharecomplete is called after the user successfully shares the URL to their class

The callbacks are supported by both the share tag and the JavaScript API, and they work on all supported browsers except Internet Explorer.

What can you use this for? There's a bunch of different things you can do, but to get you started, here are some suggestions:

  • Analytics and reporting How frequently is the share button used? What's the most frequently shared URL across the site?
  • Shared URL history Store the list of URLs a user has shared, to provide a customized and more engaging site.
  • Contextual help The first time a user shares a link back to your site, explain what happened and what they should expect to see next.
  • A/B testing Are many users starting a share action, but failing to finish?

Finally, if you want to fully control the appearance and behavior of the share button (and don't need the callbacks), you can customize the Classroom icon (as long as it still meets our branding guidelines) and initiate the share via a URL of the form:

https://classroom.google.com/share?url=https://foo.com/

As ever, please continue asking questions (or answering them!) on StackOverflow (use the google-classroom tag) and report bugs and feature requests via the Classroom API bug tracker.

Introducing the new Calendar Resource API

Posted by Muzammil Esmail, Product Manager, Google for Work and Wesley Chun, Developer Advocate, Google Apps

Over the years, we’ve been updating our APIs with new versions across Drive and Calendar, as well as those used for managing Google Apps for Work domains. These new services offer developers improvements over previous functionality and introduces new features that help Apps administrators better manage their domains.

To deliver even more granular control, today we are announcing the new Calendar Resource API as part of the Admin SDK’s Directory API that enables Google for Work customers to manage their physical resources, like conference rooms, printers, nap pods, tennis courts, walkstations, etc. These physical resources can be added to meetings by end users as needed. The API released today replaces the GDATA Calendar Resource API, so we encourage developers to begin moving their applications and tools to the new API. Please note that we will begin deprecation in January 2016 and sunset the existing API in January 2017. Stay tuned for a formal deprecation announcement with details.

A leaner and faster Google Drive API

Posted by Dan McGrath, Product Manager, Google Drive

Today, version 3 (v3) of the Google Drive API is available, providing developers with a leaner, faster by default, and more consistent interface to Google Drive. This latest update is designed to be easier for developers who are integrating with Drive for the first time.

In the time since we launched the original version of the Drive SDK, we’ve learned a lot about how developers are using our API and the pitfalls they’ve encountered. This version simplifies the API in several ways, including:

  • Reducing the number of collections developers need to understand
  • Removing some duplication
  • Cleaning up method and property names to be more consistent
  • Setting defaults that are faster and more efficient

For example, our files.list call now only includes the most commonly used fields that we serve efficiently by default, with additional fields able to be added via the fields parameter. This makes the default call nearly 6X faster in v3 than in v2:

While future versions of the API will be more feature-focused, this release provides improved performance and ease of use over the previous version of the API (v2). We will continue to support both versions so that existing apps using v2 can run without changes (developers don’t have to upgrade). For developers with a v2 app who want to take advantage of the new improvements, we’ve got a handy cheat sheet to help with migration.

To get started using the new version of the API, check out the developer docs; and for any questions, find us with the google-drive-sdk tag on StackOverflow. We look forward to seeing what you’ll build with the new API!

Google Apps Admin SDK: Introducing the Roles API

Posted by Rishi Dhand, Product Manager, Google Apps Admin SDK and Wesley Chun, Developer Advocate, Google Apps

In a Google Apps domain, Admin role management (i.e. create, assign, and update admin roles) is a critical function for super admins that helps them distribute admin responsibilities in a more secure manner. Until now, this functionality was only available via the Admin console UI.


This is what Role management looks like in the Admin console, but now you can also do this programmatically with the Roles API.


Today’s launch of the Roles API (one of the Admin SDK Directory APIs) enables developers to build admin tools that can perform role management programmatically.

This new API will be useful to admins who have either built internal admin tools using the Admin SDK, or developers of third-party admin tools. Both can now use the Roles API to provide selective access to Delegated Admins (DAs) to specific admin capabilities within third-party applications.

Here are some examples of use cases where the Roles API can be leveraged:

  • A third-party user management app that relies on the Admin SDK to perform various user related operations can now use the Roles API to selectively show the capabilities of User management DAs, such as creating/deleting users or resetting passwords.
  • A mobile device management (MDM) app developer looking to build a tool for access by Mobile Management DAs can use the Roles API to determine the privileges of the logged-in DA and selectively display MDM related admin functionality.
  • Admins (or admin tools) can now programmatically create reports on admin role assignments which can help super admins better manage access to DAs.

For more information and to get started, please check out the Roles API documentation. We look forward to helping more admins manage their domains in a more programmatic way so they can focus on more critical aspects of managing their corporate IT infrastructure.

Google Apps Script: An update to HtmlService

Posted by Saurabh Gupta, Product Manager, Google Apps Script

Back in December 2014, we announced the IFRAME sandbox mode for HtmlService which has helped improve the speed of an application’s user interface (UI). It also gives users a choice of using a variety of JS libraries on the client. We have been working hard to improve IFRAME sandbox mode and have added many features since then, including: Firefox support, file uploads, top navigation support, and improved Google Picker API support. Since IFRAME sandbox provides faster UIs and has more capabilities than NATIVE and EMULATED modes, developers should only be using IFRAME sandbox mode moving forward.

As of today, both EMULATED and NATIVE modes in HtmlService are deprecated. Over the next few months, we plan on sunsetting both EMULATED and NATIVE modes in stages to give you enough time to migrate your scripts.

We have created a migration guide to help you with this transition. For many scripts, no changes will be needed, unless they use a small set of features described in the migration guide. The guide also describes a few potential breaking changes. It is important that you review all your scripts that use HtmlService to ensure that the switch to IFRAME sandbox mode does not cause them to fail.

Here’s the timeline:

In November 2015, all new scripts will default to IFRAME sandbox mode unless NATIVE mode is explicitly specified. For example, if you make a copy of an existing script, the new script will use IFRAME sandbox mode unless you have explicitly set the sandbox mode to NATIVE.

In December 2015 (see sunset schedule for exact dates), EMULATED mode will be shutdown. Any scripts explicitly using EMULATED mode will default to IFRAME sandbox mode.

On April 28th, 2016, all scripts will default to IFRAME sandbox unless you have explicitly specified NATIVE mode in your script. For example, if your script has not specified any mode, then it will change from using NATIVE mode to IFRAME sandbox mode. Please make sure that your UI works well in IFRAME sandbox mode.

On June 30th 2016, NATIVE mode will be shutdown. All scripts explicitly using NATIVE mode will default to IFRAME sandbox mode.

While deprecations may at times seem inconvenient, this staged deprecation should ease in the migration process. Our goal is to provide a modern and secure environment enabling developers to create great apps for their users with Google Apps Script.

(A day at the office) Automating YouTube stats with Google Apps Script

Originally posted on the Google Developer blog

Posted by Wesley Chun, Developer Advocate, Google Apps

Happy Monday! Have you ever been asked by your boss to do something simple (good) but long and tedious (bad)? Take for example, the simple task of counting up all of the YouTube views for your corporate videos and your competitors’. It doesn’t even have to be your boss. What if you and your gamer friends are competing to see whose gameplay clips are garnering the most attention? It’s easy to manually track ten videos, but how about 100 or even 1,000? While simple -- you can visit the YouTube to grab the view count for each video -- you know the real problem with a task like this is that you don’t scale with the amount of content, so it’s better to automate with a simple app instead. This is the exact scenario that my colleagues and I set out to address in the latest episode of the Launchpad Online, introducing users to a pair of Google developer tools that can help solve this particular problem:



The first developer tool covered is the YouTube Data API. You can access it like most modern Google APIs from your preferred programming environment using one of the Google APIs Client Libraries. However, this type of data generally lives in a spreadsheet, and if you’re using Google Sheets, you can instead write the app with Google Apps Script, a JavaScript environment running in Google’s cloud that, if authorized, can write that video information to the cells in your Sheet. YouTube is just one of the many supported services available to Apps Script developers.

As with all my Launchpad Online episodes, I walk you through a short code snippet (only eight lines this time) that will get you started building your own custom solution. If you’re new to the developer series, we share technical content aimed at novice Google developers… current tools with a little bit of code to help you launch your next app. Please give us your feedback below and tell us what topics you would like to see in future episodes!

Google Apps: New Domain Management Features in the Admin SDK

Posted by Sushmit Goswami, Product Manager, Google Apps for Work and Wesley Chun, Developer Advocate, Google Apps

To provide developers and administrators with more fine-grained control, the Google Apps Admin SDK now includes new domain management features. These new APIs let you programmatically manage domains for your Google Apps account, similar to other RESTful resources like Users, Groups, etc., providing a superset of the domain management capabilities available on the Domains page in the admin console today.


Change your primary domain

The Customers API gives enterprise developers and administrators the ability to swap the current primary domain with a selected secondary domain for a Google Apps installation. The “change primary” operation is essentially transparent to the user, but users moved to the secondary domain will be subject to certain restrictions (refer to Help Center article for details). Customers who want to rebrand their business with a new primary domain can follow this up by renaming users from the old (now secondary) to the new (now primary) domain using the Users API.


Add and remove domains & aliases

The Domains API lets developers create tools for administrators to add and remove domains, similar to the functionality available on the Domains page in the admin console. In addition, the API lets you programmatically add aliases for any domain, primary or secondary, but aliases for secondary domain can only be added via the API.

Run Apps Script code from anywhere using the Execution API

Posted by Edward Jones, Software Engineer, Google Apps Script and Wesley Chun, Developer Advocate, Google Apps

Have you ever wanted a server API that modifies cells in a Google Sheet, to execute a Google Apps Script app from outside of Google Apps, or a way to use Apps Script as an API platform? Today, we’re excited to announce you can do all that and more with the Google Apps Script Execution API.

The Execution API allows developers to execute scripts from any client (browser, server, mobile, or any device). You provide the authorization, and the Execution API will run your script. If you’re new to Apps Script, it’s simply JavaScript code hosted in the cloud that can access authorized Google Apps data using the same technology that powers add-ons. The Execution API extends the ability to execute Apps Script code and unlocks the power of Docs, Sheets, Forms, and other supported services for developers.

One of our launch partners, Pear Deck, used the new API to create an interactive presentation tool that connects students to teachers by converting slide decks into interactive experiences. Their app calls the Execution API to automatically generate a Google Doc customized for each student, so everyone gets a personalized set of notes from the presentation. Without the use of Apps Script, their app would be limited to using PDFs and other static file types. Check out the video below to see how it works.



Bruce McPherson, a Google Developer Expert (GDE) for Google Apps, says: “The Execution API is a great tool for enabling what I call ‘incremental transition’ from Microsoft Office (and VBA) to Apps (and Apps Script). A mature Office workflow may involve a number of processes currently orchestrated by VBA, with data in various formats and locations. It can be a challenge to move an entire workload in one step, especially an automated process with many moving parts. This new capability enables the migration of data and process in manageable chunks.” You can find some of Bruce’s sample migration code using the Execution API here.

The Google Apps Script Execution API is live and ready for you to use today. To get started, check out the developer documentation and quickstarts. We invite you to show us what you build with the Execution API!