Run your first Sheets script

Read a safe sample

Create a bound script that reads the Customers tab and writes its rows to the execution log without changing the spreadsheet.

function readAllCustomerRows() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Customers');
  if (!sheet) throw new Error('Add a Sheet tab named Customers before running this function.');
  const values = sheet.getDataRange().getValues();
  Logger.log(values);
}

getDataRange() selects the used rectangle on the tab. getValues() returns that rectangle as an array of rows, and Logger.log() writes it to the execution log. The Range reference documents the read API and its Sheets authorization requirements; the Logger reference documents the log call.

Set up the spreadsheet

1. Create a new blank Google Sheet for this exercise. Do not use a live customer spreadsheet.

2. Create or rename its first tab to Customers.

3. Copy the comma-separated text from sample.csv into cell A1, or import sample.csv shown below with File > Import. Select column A, choose Data > Split text to columns, set the separator to Comma, and verify that Customers!A1:C4 contains four rows starting with the Name, Email, and Status headers:

Name,Email,Status
Avery Quinn,avery@example.com,Active
Morgan Lee,morgan@example.com,Paused
Riley Park,riley@example.com,Active

4. In that spreadsheet, choose Extensions > Apps Script. Replace the default code in Code.gs with the complete Code.gs example file.

5. In Project Settings, select Show "appsscript.json" manifest file in editor, then replace its contents with the project manifest (appsscript.json):

{
  "timeZone": "Etc/UTC",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets.currentonly"
  ]
}

Save all files.

The project is bound to this spreadsheet, so getActiveSpreadsheet() returns the parent file. A standalone project would need to open a spreadsheet by ID or URL instead; see Google's bound-script guide.

Run the entrypoint

1. Choose readAllCustomerRows in the function menu at the top of the editor.

2. Click Run.

3. Read the permission prompt. The manifest scope requests access only to the current spreadsheet.

4. Open Execution log after the run finishes.

The function runs as the user at the keyboard. Apps Script checks the scopes that code needs and prompts for consent when the user has not granted them. Google describes that lifecycle in its authorization guide.

Recognize the result

The log shows the rows from the sheet, including the header row:

[
  ["Name", "Email", "Status"],
  ["Avery Quinn", "avery@example.com", "Active"],
  ["Morgan Lee", "morgan@example.com", "Paused"],
  ["Riley Park", "riley@example.com", "Active"]
]

The exact log display can differ, but it shows four rows and three values per row. This is a two-dimensional array: an outer array of rows, with an inner array of cell values for each row.

Handle ordinary failures

• If the run stops with Add a Sheet tab named Customers before running this function., rename or create the tab Customers, then run again.

• If the authorization dialog requests broader access than the current spreadsheet, cancel it. Check that appsscript.json contains the current-spreadsheet scope and that no other service calls were added to the project.

• If the log has only one column, select column A and use Data > Split text to columns with Comma as the separator so the input spans four rows by three columns.

Change the input

Change Paused in the sample sheet to Active and run readAllCustomerRows again. The logged value for Morgan changes from Paused to Active.

Clean up and continue

Delete the disposable spreadsheet when you no longer need it, which also removes its bound script. Next, store and compare values in JavaScript so your script can inspect each row and decide what to do with it.