Create a Google Workspace Add-ons in Cloud Functions using the Node.js runtime.
Objectives
- Set up your environment.
- Create and deploy a Cloud Function.
- Create and deploy the add-on.
- Install the add-on.
Prerequisites
- A Google Cloud project.
- Make sure that you turn on billing for your Cloud project. Learn how to verify the billing status of your projects.
- The Cloud SDK configured with the Cloud project.
Set up your environment
Open your Cloud project in the Google Cloud console
- In the Google Cloud console, go to the Select a project page.
- Select the Google Cloud project you want to use. Or, click Create project and follow the on-screen instructions. If you create a Google Cloud project, you might need to turn on billing for the project.
Configure the OAuth consent screen
Google Workspace Add-ons require a consent screen configuration. Configuring your add-on's OAuth consent screen defines what Google displays to users.
- In the Google Cloud console, go to Menu > APIs & Services > OAuth consent screen.
- For User type select Internal, then click Create.
- Complete the app registration form, then click Save and Continue.
For now, you can skip adding scopes and click Save and Continue. In the future, when you create an app for use outside of your Google Workspace organization, you must change the User type to External, and then, add the authorization scopes that your app requires.
- Review your app registration summary. To make changes, click Edit. If the app registration looks OK, click Back to Dashboard.
Create and deploy a Cloud Function
In a local terminal, turn on the Cloud Functions, Cloud Build, and the Google Workspace Add-ons API:
gcloud services enable cloudfunctions cloudbuild.googleapis.com gsuiteaddons.googleapis.com
In an empty directory, create the file
function.js
with the following sample code:/** * Cloud Function that loads the homepage for a * Google Workspace Add-on. * * @param {Object} req Request sent from Google * @param {Object} res Response to send back */ exports.loadHomePage = function addonsHomePage (req, res) { res.send(createAction()); }; /** Creates a card with two widgets. */ function createAction() { return { "action": { "navigations": [ { "pushCard": { "header": { "title": "Cats!" }, "sections": [ { "widgets": [ { "textParagraph": { "text": "Your random cat:" } }, { "image": { "imageUrl": "https://cataas.com/cat" } } ] } ] } } ] } }; }
Deploy the function:
gcloud functions deploy loadHomePage --runtime nodejs12 --trigger-http
If prompted, specify that you don't allow unauthenticated invocations of the function. It might take a couple minutes for the function to deploy.
Create an add-on deployment
Find the service account email for the add-on:
gcloud workspace-add-ons get-authorization
Grant the service account the
cloudfunctions.invoker
role:gcloud functions add-iam-policy-binding loadHomePage \ --role roles/cloudfunctions.invoker \ --member serviceAccount:SERVICE_ACCOUNT_EMAIL
Get the URL of the deployed function. To get the URL, run the following command and look for the
url
field under thehttpsTrigger
section:gcloud functions describe loadHomePage
Create the file
deployment.json
with the following sample code. ReplaceURL
with the URL of the deployed function from the previous step.{ "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"], "addOns": { "common": { "name": "My HTTP Add-on", "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png", "homepageTrigger": { "runFunction": "URL" } }, "gmail": {}, "drive": {}, "calendar": {}, "docs": {}, "sheets": {}, "slides": {} } }
Create the deployment:
gcloud workspace-add-ons deployments create quickstart \ --deployment-file=deployment.json
Install the add-on
Install the deployment in development mode:
gcloud workspace-add-ons deployments install quickstart
Open or reload Gmail to view the add-on. In the toolbar on the right, look for a beaker icon.
Click the icon to open the add-on. If prompted, authorize the add-on.
Optional: Clean up
To avoid incurring charges to your account, delete the resources that you created:
Uninstall the add-on from your Google Account:
gcloud workspace-add-ons deployments uninstall quickstart
To avoid incurring charges for the resources used in this quickstart, delete the Cloud project:
gcloud projects delete PROJECT_ID
Replace PROJECT_ID with the ID of the Cloud project that you used for the quickstart. You can find the Cloud project ID in the Google Cloud console on the Dashboard page.
Next steps
To add more functionality to your Google Workspace Add-on, refer to the following guides: