Ballerina Google Sheets Connector

The Google Sheets, developed by Google LLC, allows users to programmatically interact with Google Sheets, facilitating tasks such as data manipulation, analysis, and automation.

The ballerinax/googleapis.gsheets package offers APIs to connect and interact with Sheets API endpoints, specifically based on Google Sheets API v4.

Setup guide

To use the Google Sheets connector, you must have access to the Google Sheets API through a Google Cloud Platform (GCP) account and a project under it. If you do not have a GCP account, you can sign up for one here.

Step 1: Create a Google Cloud Platform project

Open the Google Cloud Platform Console.
Click on Select a project in the drop-down menu and either select an existing project or create a new one.

Step 2: Enabling Google Sheets API

Select the created project.
Navigate to APIs & Services > Library.
Search and select Google Sheets API. Then click ENABLE.

Step 3: Creating an OAuth consent app

Click on the OAuth Consent Screen in the sidebar.
Select External and click CREATE.
Fill in the app information and add the necessary scopes for Google Sheets API.

Step 4: Generating client ID & client secret

In the left sidebar, click on Credentials.
Click on + CREATE CREDENTIALS and choose OAuth Client ID.
You will be directed to the OAuth consent screen, in which you need to fill in the necessary information below.

Field Value

Application type Web Application

Name Sheets Client

Authorized Redirect URIs https://developers.google.com/oauthplayground

Field	Value
Application type	Web Application
Name	Sheets Client
Authorized Redirect URIs	https://developers.google.com/oauthplayground

Step 5: Obtain the access and refresh tokens

Follow these steps to generate the access and refresh tokens.

Note: It is recommended to use the OAuth 2.0 playground to acquire the tokens.

Configure the OAuth playground with the OAuth client ID and client secret.
Authorize the Google Sheets APIs.
Exchange the authorization code for tokens.

Quickstart

To use the Google Sheets connector in your Ballerina project, modify the .bal file as follows:

Step 1: Import connector

Import the ballerinax/googleapis.gsheets module.

import ballerinax/googleapis.gsheets;

Step 2: Create a new connector instance

Create a gsheets:ConnectionConfig with the obtained OAuth2.0 tokens and initialize the connector with it.

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;
configurable string refreshUrl = ?;

gsheets:Client spreadsheetClient = check new ({
    auth: {
        clientId,
        clientSecret,
        refreshToken,
        refreshUrl
    }
});

Step 3: Invoke connector operation

Now, utilize the available connector operations.

Create a spreadsheet with a given name

public function main() returns error? {

    // create a spreadsheet
    gsheets:Spreadsheet response = check spreadsheetClient->createSpreadsheet("NewSpreadsheet");

    // Add a new worksheet with given name to the Spreadsheet
    string spreadsheetId = response.spreadsheetId;
    gsheets:Sheet sheet = check spreadsheetClient->addSheet(spreadsheetId, "NewWorksheet");
}

Step 4: Run the Ballerina application

bal run

Examples

The Google Sheets connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering use cases like creating, reading, and appending rows.

Cell operations - Operations associated with a cell, such as clearing, setting, and deleting cell values.
Grid filtering - Demonstrate filtering sheet values using a grid range.
Sheet modifying - Basic operations associated with sheets such as creating, reading, and appending rows.

Build from the source

Prerequisites

Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:
- Oracle JDK
- OpenJDK
Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.
Download and install Ballerina Swan Lake.
Download and install Docker.

Note: Ensure that the Docker daemon is running before executing any tests.

Build options

Execute the commands below to build from the source.

To build the package:
```
./gradlew clean build
```
To run the tests:
```
./gradlew clean test
```
To build the without the tests:
```
./gradlew clean build -x test
```

To run tests against different environments:

./gradlew clean test -Pgroups=<Comma separated groups/test cases>

To debug the package with a remote debugger:
```
./gradlew clean build -Pdebug=<port>
```

To debug with the Ballerina language:

./gradlew clean build -PbalJavaDebug=<port>

Publish the generated artifacts to the local Ballerina Central repository:
```
./gradlew clean build -PpublishToLocalCentral=true
```
Publish the generated artifacts to the Ballerina Central repository:
```
./gradlew clean build -PpublishToCentral=true
```

Contribute to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

For more information go to the googleapis.gsheets package.
For example, demonstrations of the usage, go to Ballerina By Examples.
Chat live with us via our Discord server.
Post all technical questions on Stack Overflow with the #ballerina tag.

ballerina-platform / module-ballerinax-googleapis.sheets