shenghaiwang/googleapiswiftsdk

Quick Start

1. Authentication Setup

Service Account Authentication (Server-to-Server)

Service account authentication is ideal for server-side applications, automation scripts, and scenarios where you need to access Google Sheets without user interaction.

Setup

1. Create a Service Account in the Google Cloud Console
2. Download the JSON key file for your service account
3. Share your spreadsheet with the service account email address (found in the JSON file)
4. Enable the Google Sheets API for your project

Authentication Methods

Method 1: Load from JSON file

import GoogleSheetsSwift

// Load service account from JSON file
let tokenManager = try ServiceAccountTokenManager.loadFromFile("/path/to/service-account.json")
let client = GoogleSheetsClient(tokenManager: tokenManager)

// Now you can perform operations
let values = try await client.readRange("spreadsheet-id", range: "Sheet1!A1:C10")

Method 2: Load from environment variable

import GoogleSheetsSwift

// Set environment variable: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
let tokenManager = try ServiceAccountTokenManager.loadFromEnvironment()
let client = GoogleSheetsClient(tokenManager: tokenManager)

Method 3: Initialize directly with ServiceAccountKey

import GoogleSheetsSwift

// Load and parse the service account JSON
let serviceAccountData = try Data(contentsOf: URL(fileURLWithPath: "/path/to/service-account.json"))
let serviceAccountKey = try JSONDecoder().decode(ServiceAccountKey.self, from: serviceAccountData)

// Create token manager
let tokenManager = ServiceAccountTokenManager(serviceAccountKey: serviceAccountKey)
let client = GoogleSheetsClient(tokenManager: tokenManager)

2. Basic Operations

Reading Data

// Read values from a range
let values = try await client.readRange(
    "your-spreadsheet-id",
    range: "Sheet1!A1:C10"
)

// Get string values directly
let stringValues = try await client.readStringValues(
    "your-spreadsheet-id", 
    range: "Sheet1!A1:C10"
)

print("First cell: \(stringValues[0][0] ?? "Empty")")

Writing Data

// Write data to a range
let data = [
    ["Name", "Age", "City"],
    ["John", "25", "New York"],
    ["Jane", "30", "San Francisco"]
]

let response = try await client.writeRange(
    "your-spreadsheet-id",
    range: "Sheet1!A1:C3",
    values: data
)

print("Updated \(response.updatedCells ?? 0) cells")

Creating Spreadsheets

// Create a new spreadsheet
let spreadsheet = try await client.createSpreadsheet(
    title: "My New Spreadsheet",
    sheetTitles: ["Data", "Analysis"]
)

print("Created spreadsheet: \(spreadsheet.spreadsheetId ?? "unknown")")

Advanced Usage

Batch Operations

// Batch read multiple ranges
let operations = [
    BatchReadOperation(range: "Sheet1!A1:C10"),
    BatchReadOperation(range: "Sheet2!A1:D5")
]

let results = try await client.batchRead(
    "your-spreadsheet-id",
    operations: operations
)

// Batch write to multiple ranges
let writeOperations = [
    BatchWriteOperation(range: "Sheet1!A1:B2", values: [["A1", "B1"], ["A2", "B2"]]),
    BatchWriteOperation(range: "Sheet1!D1:E2", values: [["D1", "E1"], ["D2", "E2"]])
]

let writeResponse = try await client.batchWrite(
    "your-spreadsheet-id",
    operations: writeOperations
)

Custom Configuration

// Create client with custom configuration
let logger = ConsoleGoogleSheetsLogger(minimumLevel: .debug)
let cache = InMemoryResponseCache()
let cacheConfig = CacheConfiguration(ttl: 300, maxSize: 100)

let client = GoogleSheetsClient(
    tokenManager: tokenManager,
    logger: logger,
    cache: cache,
    cacheConfiguration: cacheConfig
)

// Enable debug mode
client.setDebugMode(true)

Error Handling

do {
    let values = try await client.readRange("spreadsheet-id", range: "A1:B2")
    // Process values
} catch GoogleSheetsError.authenticationFailed(let message) {
    print("Authentication failed: \(message)")
} catch GoogleSheetsError.rateLimitExceeded(let retryAfter) {
    print("Rate limited. Retry after: \(retryAfter ?? 0) seconds")
} catch GoogleSheetsError.invalidSpreadsheetId(let id) {
    print("Invalid spreadsheet ID: \(id)")
} catch {
    print("Unexpected error: \(error)")
}

A1 Notation Utilities

// Validate A1 notation
let isValid = GoogleSheetsClient.isValidA1Range("Sheet1!A1:B10")

// Convert column numbers to letters
let columnLetter = GoogleSheetsClient.columnNumberToLetters(27) // "AA"

// Convert column letters to numbers  
let columnNumber = try GoogleSheetsClient.columnLettersToNumber("AA") // 27

// Build A1 ranges programmatically
let range = GoogleSheetsClient.buildA1Range(
    sheetName: "Data",
    startColumn: 1, startRow: 1,
    endColumn: 5, endRow: 100
) // "Data!A1:E100"

Package Metadata

Repository: shenghaiwang/googleapiswiftsdk

Default branch: master

README: README.md