GCS Service

FastAPI service for working with Google Cloud Storage buckets.

Features

• List buckets in the project
• List files in a bucket (with prefix filtering)
• Upload files to buckets
• Download files from buckets
• Delete files from buckets
• Copy files between buckets
• Get bucket and file information
• Automatic gzip compression/decompression support

API Endpoints

Health Check

• GET /health - Health check endpoint

Buckets

• GET /buckets - List all buckets
• GET /buckets/{bucket_name}/info - Get bucket information

Files

• GET /buckets/{bucket_name}/files - List files in a bucket
  • Query parameters:
    • prefix (optional): Filter files by prefix
    • max_results (optional, default: 100): Maximum number of results (1-1000)
• GET /buckets/{bucket_name}/files/{file_path} - Download a file
  • Query parameters:
    • decompress (optional, default: false): Automatically decompress gzip files
• POST /buckets/{bucket_name}/files/{file_path} - Upload a file
  • Query parameters:
    • content_type (optional): Content type (auto-detected if not provided)
    • compress (optional, default: false): Compress file with gzip before uploading
• DELETE /buckets/{bucket_name}/files/{file_path} - Delete a file
• GET /buckets/{bucket_name}/files/{file_path}/info - Get file information
• POST /buckets/{bucket_name}/files/{file_path}/copy - Copy a file
  • Request body:

    {
      "destination_bucket": "target-bucket-name",
      "destination_path": "optional/new/path/file.txt"
    }

Environment Variables

• PORT (default: 8006) - Service port
• GOOGLE_APPLICATION_CREDENTIALS (optional) - Path to service account JSON file
  • If not provided, uses default credentials (from environment or gcloud)

Authentication

The service supports two authentication methods:

1. Service Account JSON File: Set GOOGLE_APPLICATION_CREDENTIALS environment variable
2. Default Credentials: Uses application default credentials (from gcloud or environment)

Examples

List all buckets

curl http://localhost:8006/buckets

List files in a bucket

curl "http://localhost:8006/buckets/my-bucket/files?prefix=pdfs/&max_results=50"

Upload a file

curl -X POST \
  -F "file=@/path/to/file.pdf" \
  "http://localhost:8006/buckets/my-bucket/files/pdfs/file.pdf?compress=true"

Download a file

curl "http://localhost:8006/buckets/my-bucket/files/pdfs/file.pdf" -o file.pdf

Download and decompress a gzip file

curl "http://localhost:8006/buckets/my-bucket/files/data.json.gz?decompress=true" -o data.json

Delete a file

curl -X DELETE "http://localhost:8006/buckets/my-bucket/files/pdfs/file.pdf"

Copy a file

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"destination_bucket": "backup-bucket", "destination_path": "backup/file.pdf"}' \
  "http://localhost:8006/buckets/my-bucket/files/pdfs/file.pdf/copy"

Docker

Build and run:

docker build -t gcs-service .
docker run -p 8006:8006 \
  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json \
  -v /path/to/credentials.json:/path/to/credentials.json \
  gcs-service

Docker Compose

The service is included in docker-compose.yml:

gcs-service:
  build:
    context: ./gcs_service
  ports:
    - "8006:8006"
  environment:
    PORT: 8006
    GOOGLE_APPLICATION_CREDENTIALS: ${GOOGLE_APPLICATION_CREDENTIALS:-}

API Documentation

Once the service is running, visit:

• Swagger UI: http://localhost:8006/docs
• ReDoc: http://localhost:8006/redoc