utsmannn/sheet-api

Sheet API 镜像

镜像概述

本镜像提供一个基于Ktor框架的Kotlin REST API，用于与Google Sheets进行交互，支持自动模式检测、数据验证、API密钥认证等核心功能，帮助开发者高效管理表格数据。

核心功能

使用场景

• 快速构建与Google Sheets集成的后端服务
• 自动化处理表格数据的批量读写与验证
• 为Web应用提供安全的表格数据API接口

配置说明

通过环境变量配置镜像：

• SHEET_ID：目标Google Sheets的唯一ID
• API_SECRET_KEY：生成API密钥的秘密密钥
• CREDENTIAL_PATH：Google服务账户JSON密钥文件的容器内路径

Docker部署示例

直接运行容器

bash
docker pull docker.xuanyuan.run/utsmannn/sheet-api:latest
docker run -d \
  -p 8910:8910 \
  -e SHEET_ID="你的Google Sheets ID" \
  -e API_SECRET_KEY="你的秘密密钥" \
  -e CREDENTIAL_PATH="/app/credentials/service-account.json" \
  -v /本地路径/service-account.json:/app/credentials/service-account.json \
  --name sheet-api \
  docker.xuanyuan.run/utsmannn/sheet-api:latest

使用Docker Compose

1. 创建docker-compose.yml文件：

yaml
version: '3.8'
services:
  sheet-api:
    image: docker.xuanyuan.run/utsmannn/sheet-api:latest
    container_name: sheet-api-kotlin
    ports:
      - "8910:8910"
    environment:
      - SHEET_ID=${SHEET_ID}
      - API_SECRET_KEY=${API_SECRET_KEY}
      - CREDENTIAL_PATH=/app/credentials/service-account-key.json
    volumes:
      - ./credentials:/app/credentials:ro
    restart: unless-stopped

2. 创建.env文件：

SHEET_ID=你的Google Sheets ID
API_SECRET_KEY=你的秘密密钥

3. 创建credentials目录并放入Google服务账户JSON密钥文件
4. 启动容器：docker-compose up -d

API端点（需认证）

获取表格数据

bash
GET /api/sheets/{sheetName}?per_page=10&offset=1
Headers: X-API-Key: 你的API密钥

获取表格模式

bash
GET /api/sheets/{sheetName}/schema
Headers: X-API-Key: 你的API密钥

添加新行

bash
POST /api/sheets/{sheetName}
Headers: X-API-Key: 你的API密钥; Content-Type: application/json
Body: {"id":123,"name":"John Doe","email":"john@example.com","active":"true"}

API认证

所有业务API端点需认证，支持X-API-Key或Authorization Bearer header。API密钥格式为base64("{API_SECRET_KEY}:{13位时间戳}")，可通过在线工具、命令行或代码生成。

数据类型检测

自动分析表格数据，检测类型包括：

• 整数：可解析为整数的值（如"123"）
• 浮点数：可解析为浮点数的值（如"12.34"）
• 布尔值：支持true/false、1/0、yes/no等格式
• 字符串：默认类型，适用于其他所有值

许可证

本项目采用Apache License 2.0授权，详见LICENSE文件。