คู่มือ Workshop สำหรับนักพัฒนา DevOps, Software Engineer และผู้สนใจ AI Agent
อัปเดต: ตุลาคม 2026

#บทนำ

Google Workspace CLI หรือ gws เป็นเครื่องมือ Command Line แบบโอเพนซอร์สที่ช่วยให้เราทำงานกับ Google Workspace APIs เช่น Google Drive, Gmail, Calendar, Sheets, Docs, Chat และบริการอื่น ๆ ได้จาก Terminal โดยตรง

จุดเด่นของ gws คือ command surface ถูกสร้างแบบ dynamic จาก Google Discovery Service จึงเหมาะทั้งสำหรับการใช้งานโดยนักพัฒนา การเขียน Shell Automation, CI/CD และการนำไปเป็นเครื่องมือให้ AI Agent

หมายเหตุ: โครงการ gws ระบุว่าไม่ใช่ผลิตภัณฑ์ Google ที่ได้รับการสนับสนุนอย่างเป็นทางการ และยังอยู่ระหว่างการพัฒนาก่อน v1.0 ดังนั้น syntax หรือพฤติกรรมบางส่วนอาจเปลี่ยนแปลงได้

#วัตถุประสงค์ของ Workshop

เมื่อจบ Workshop นี้ ผู้เรียนจะสามารถ

  1. ติดตั้ง Google Workspace CLI
  2. ตั้งค่า Google Cloud Project และ OAuth
  3. Login เข้า Google Workspace ผ่าน CLI
  4. ใช้งาน Google Drive ผ่าน Terminal
  5. สร้างและอ่าน Google Sheets
  6. ส่ง Gmail ผ่าน CLI
  7. อ่าน Google Calendar
  8. ใช้ JSON output ร่วมกับ jq
  9. ใช้ --dry-run และ gws schema
  10. เข้าใจแนวทางนำ gws ไปใช้กับ Automation และ AI Agent

#Architecture

Developer / DevOps / AI Agent
             |
             v
          gws CLI
             |
             v
   Google Discovery Service
             |
             v
      Workspace APIs
             |
   +---------+---------+
   |         |         |
   v         v         v
 Gmail     Drive    Calendar
   |         |         |
   +------ Sheets -----+
             |
             v
      Docs / Chat / Tasks

คำสั่งพื้นฐานมีรูปแบบประมาณ

gws <service> <resource> [sub-resource] <method> [flags]

ตัวอย่าง

gws drive files list

#Lab 1 --- เตรียมเครื่องมือ

#1.1 ตรวจสอบ Node.js

หากต้องการติดตั้งผ่าน npm ควรมี Node.js 18 ขึ้นไป

node --version
npm --version

#1.2 ติดตั้ง gws

npm install -g @googleworkspace/cli

ตรวจสอบ

gws --help

สำหรับ macOS/Linux สามารถใช้ Homebrew ได้เช่นกัน

brew install googleworkspace-cli

อีกทางเลือกคือใช้ pre-built binary จากหน้า Releases ของโครงการ

#Lab 2 --- ตั้งค่า Authentication

gws ใช้ OAuth เพื่อขอสิทธิ์เข้าถึง Google Workspace ของผู้ใช้

#2.1 วิธีอัตโนมัติ

หากเครื่องมี Google Cloud CLI (gcloud) และ login ไว้แล้ว สามารถใช้

gws auth setup

คำสั่งนี้ช่วยเตรียม Google Cloud project, APIs และ OAuth configuration

จากนั้น login:

gws auth login

#2.2 จำกัด Scope เฉพาะบริการที่ใช้

หลัก Least Privilege ควรอนุญาตเฉพาะบริการที่ Workshop ต้องใช้

gws auth login -s drive,gmail,sheets,calendar

การเลือก scope เท่าที่จำเป็นยังช่วยลดปัญหาของ OAuth app ที่อยู่ใน testing mode ซึ่งอาจมีข้อจำกัดด้านจำนวน scopes

#Lab 3 --- ตั้งค่า OAuth แบบ Manual

หากไม่ใช้ gcloud สามารถสร้าง OAuth client ผ่าน Google Cloud Console ได้

แนวทางคือ

  1. สร้างหรือเลือก Google Cloud Project
  2. Configure OAuth consent screen
  3. เพิ่มบัญชีของตนเองเป็น Test User หาก application ยังอยู่ใน Testing
  4. เปิด API ที่ต้องการ เช่น Drive API, Gmail API, Sheets API และ Calendar API
  5. สร้าง OAuth Client ID
  6. เลือก Application Type เป็น Desktop app
  7. Download Client JSON
  8. นำไฟล์ไปไว้ที่
~/.config/gws/client_secret.json

จากนั้น

gws auth login

อย่า commit client_secret.json, credentials หรือ token ขึ้น Git repository

#Lab 4 --- Google Drive

#4.1 แสดงรายการไฟล์

gws drive files list \
  --params '{"pageSize": 5}'

ผลลัพธ์หลักของ gws เป็น JSON ทำให้เหมาะกับ script และ AI Agent

#4.2 ดู schema ก่อนเรียก API

gws schema drive.files.list

แนวทางนี้มีประโยชน์มากเมื่อไม่แน่ใจชื่อ parameter หรือโครงสร้างข้อมูล

#4.3 Pagination

gws drive files list \
  --params '{"pageSize": 100}' \
  --page-all

ใช้ร่วมกับ jq:

gws drive files list \
  --params '{"pageSize": 100}' \
  --page-all |
jq -r '.files[].name'

#4.4 Upload file

สร้างไฟล์ทดลอง

echo "Hello Google Workspace CLI" > report.txt

Upload:

gws drive +upload ./report.txt \
  --name "Workshop Report"

#Lab 5 --- Google Sheets

#5.1 สร้าง Spreadsheet

gws sheets spreadsheets create \
  --json '{"properties":{"title":"GWS Workshop"}}'

เก็บค่า spreadsheetId ที่ได้จาก response

SPREADSHEET_ID

#5.2 เขียนข้อมูล

ตัวอย่าง append row:

gws sheets +append \
  --spreadsheet SPREADSHEET_ID \
  --values "Alice,95"

เพิ่มอีกแถว:

gws sheets +append \
  --spreadsheet SPREADSHEET_ID \
  --values "Bob,88"

#5.3 อ่านข้อมูล

gws sheets +read \
  --spreadsheet SPREADSHEET_ID \
  --range 'Sheet1!A1:B10'

ใน Bash ควรครอบ range ด้วย single quotes เพราะ ! อาจถูก shell ตีความเป็น history expansion

#Lab 6 --- Gmail

#6.1 ส่ง Email

gws gmail +send \
  --to user@example.com \
  --subject "Google Workspace CLI Workshop" \
  --body "Hello from gws CLI"

เปลี่ยน user@example.com เป็นอีเมลสำหรับทดสอบ

#6.2 Reply

gws gmail +reply \
  --message-id MESSAGE_ID \
  --body "Thank you"

gws ยังมี helper commands สำหรับงาน Gmail อื่น ๆ เช่น triage, watch, reply-all และ forward ตามเวอร์ชันที่ติดตั้ง

คำสั่งที่ส่งหรือแก้ไขข้อมูลจริงควรตรวจสอบ recipient, payload และ scope ให้ถูกต้องก่อนรัน

#Lab 7 --- Google Calendar

ดู agenda:

gws calendar +agenda

ดูเฉพาะวันนี้:

gws calendar +agenda --today

กำหนด timezone:

gws calendar +agenda \
  --today \
  --timezone Asia/Bangkok

#Lab 8 --- Output Format และ JSON Pipeline

ค่าเริ่มต้นเหมาะกับ JSON processing และยังรองรับ output format อื่นตามเวอร์ชัน เช่น

gws drive files list \
  --params '{"pageSize":5}' \
  --format table

หรือ

gws drive files list \
  --params '{"pageSize":5}' \
  --format yaml

JSON มีประโยชน์เมื่อใช้กับ

gws
 |
 v
JSON
 |
 +--> jq
 |
 +--> Bash/Python
 |
 +--> CI/CD
 |
 +--> AI Agent

#Lab 9 --- ใช้ --dry-run

ก่อนทำ operation ที่เปลี่ยนข้อมูล ควร preview request ก่อนเมื่อ command รองรับ

ตัวอย่างแนวคิด:

gws chat spaces messages create \
  --params '{"parent":"spaces/SPACE_ID"}' \
  --json '{"text":"Deploy complete"}' \
  --dry-run

จากนั้นเมื่อมั่นใจจึงเรียกคำสั่งจริงโดยนำ --dry-run ออก

แนวปฏิบัติสำหรับ automation:

Discover schema
      |
      v
Build request
      |
      v
   Dry Run
      |
      v
Validate
      |
      v
Execute API

#Lab 10 --- Workflow Commands

gws มี higher-level helper/workflow commands สำหรับงานที่พบบ่อย

ตัวอย่าง standup:

gws workflow +standup-report

เตรียมข้อมูลก่อนประชุม:

gws workflow +meeting-prep

ตัวอย่าง workflow อื่นที่โครงการระบุ ได้แก่

+email-to-task
+weekly-digest
+file-announce

ทำให้สามารถรวมหลายบริการของ Google Workspace เข้าเป็น workflow เดียวได้ง่ายขึ้น

#Lab 11 --- Automation ด้วย Shell Script

สร้างไฟล์

workspace-report.sh

ตัวอย่าง:

#!/bin/bash

echo "=== Google Workspace Daily Report ==="

echo
echo "Calendar"
gws calendar +agenda --today --timezone Asia/Bangkok

echo
echo "Drive"
gws drive files list \
  --params '{"pageSize":5}'

echo
echo "Finished"

Linux/macOS:

chmod +x workspace-report.sh
./workspace-report.sh

แนวคิดสามารถขยายไปเป็น Cron Job, GitHub Actions หรือ CI/CD pipeline ได้

#Lab 12 --- Headless / CI

สำหรับ server หรือ CI สามารถ authenticate บนเครื่องที่มี browser ก่อน แล้ว export credentials ตามแนวทางของโครงการ

gws auth export --unmasked > credentials.json

จากนั้นกำหนด credentials file บน environment เป้าหมาย:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

แล้วเรียก:

gws drive files list \
  --params '{"pageSize":5}'

credentials.json เป็น secret ต้องจัดเก็บใน Secret Manager/CI Secret และห้าม commit ลง repository

สำหรับ server-to-server บางกรณี gws รองรับ credentials file ของ Service Account เช่นกัน แต่สิทธิ์ที่เข้าถึง Workspace data จริงยังขึ้นกับ API, account และการตั้งค่าขององค์กร

#Lab 13 --- AI Agent Integration

เหตุผลที่ gws เหมาะกับ Agent คือ

  • command interface สม่ำเสมอ
  • response เป็น structured data
  • inspect schema ได้
  • มี --dry-run
  • รองรับหลาย Workspace APIs
  • repository มี Agent Skills สำหรับบริการต่าง ๆ

ติดตั้ง Agent Skills ตามแนวทางของโครงการ:

npx skills add https://github.com/googleworkspace/cli

หรือเลือกเฉพาะ Drive:

npx skills add \
  https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

แนวคิด Agent:

User
 |
 v
LLM / AI Agent
 |
 v
Agent Skill
 |
 v
gws CLI
 |
 v
Google Workspace APIs
 |
 +--> Gmail
 +--> Drive
 +--> Calendar
 +--> Sheets
 +--> Docs
 +--> Chat

ตัวอย่างโจทย์:

"ตรวจสอบตารางประชุมวันนี้
ค้นหาเอกสารที่เกี่ยวข้องใน Drive
แล้วสร้างข้อมูลสรุปสำหรับเตรียมประชุม"

Agent สามารถวางแผนเรียก Calendar → Drive → Docs/Sheets ผ่าน gws ตามสิทธิ์ที่ได้รับ

#Lab 14 --- Gemini CLI

โครงการยังมีแนวทางติดตั้งเป็น Gemini CLI extension

Authenticate ก่อน:

gws auth setup

ติดตั้ง extension:

gemini extensions install \
  https://github.com/googleworkspace/cli

จากนั้น Gemini CLI สามารถใช้ gws commands และ skills ใน environment ที่ authenticate ไว้

#Security Best Practices

#1. Least Privilege

เลือก OAuth scopes เฉพาะบริการที่จำเป็น เช่น

gws auth login -s drive,sheets

แทนการให้สิทธิ์ทุกบริการ

#2. อย่าเก็บ Secret ใน Git

ควรเพิ่มไฟล์ credentials ใน .gitignore

credentials.json
client_secret.json
.env

#3. ใช้ --dry-run

โดยเฉพาะ create/update/delete/send operation

#4. Inspect Schema

ก่อนให้ Agent สร้าง request:

gws schema drive.files.list

#5. จำกัด Output

Workspace APIs อาจคืนข้อมูลจำนวนมาก ควรใช้ pageSize, pagination limit และ field selection เมื่อเหมาะสม เพื่อลดข้อมูลที่ไม่จำเป็น โดยเฉพาะเมื่อ output จะถูกส่งเข้า LLM

#Troubleshooting

#gws: command not found

ตรวจสอบ:

npm list -g @googleworkspace/cli

และ PATH ของ npm global binaries

#OAuth: Access blocked

หาก OAuth app อยู่ใน Testing ให้ตรวจสอบว่า account ที่ใช้ถูกเพิ่มใน Test users

#redirect_uri_mismatch

ตรวจสอบว่า OAuth Client ถูกสร้างเป็นประเภท Desktop app

#accessNotConfigured

API ที่เรียกอาจยังไม่ได้ Enable ใน Google Cloud project เช่น Gmail API หรือ Drive API ให้เปิด API ที่ต้องใช้แล้วลองใหม่

#Scope มากเกินไป

แทนการขอ scope จำนวนมาก ให้เลือกเฉพาะบริการ:

gws auth login -s drive,gmail,sheets,calendar

#Workshop Challenge

สร้างระบบ Workspace Daily Assistant

Requirements:

  1. อ่าน Calendar ของวันนี้
  2. อ่านไฟล์ล่าสุดจาก Drive
  3. อ่านข้อมูลจาก Google Sheets
  4. สร้างข้อมูลสรุป
  5. ส่งผลลัพธ์เข้า workflow ที่เหมาะสม เช่น Gmail หรือ Google Chat
  6. ใช้ JSON เป็นข้อมูลกลาง
  7. ใช้ Least Privilege
  8. ตรวจสอบ mutating requests ด้วย --dry-run เมื่อรองรับ

Architecture:

            Scheduler
                |
                v
           Shell Script
                |
                v
              gws
       +--------+--------+
       |        |        |
       v        v        v
   Calendar   Drive    Sheets
       |        |        |
       +--------+--------+
                |
                v
          JSON / jq
                |
                v
           AI Agent
                |
          +-----+-----+
          |           |
          v           v
        Gmail        Chat

#สรุป

Google Workspace CLI ทำให้ Workspace APIs กลายเป็น command-line interface ที่เหมาะกับ Developer Automation และ AI Agent โดยเฉพาะ เพราะใช้ structured output และสามารถตรวจสอบ API schema ได้จาก CLI

เส้นทางการเรียนรู้ที่แนะนำคือ

Install
  |
  v
OAuth
  |
  v
Drive
  |
  v
Sheets
  |
  v
Gmail
  |
  v
Calendar
  |
  v
Shell Automation
  |
  v
AI Agent

เมื่อเข้าใจ workflow นี้แล้ว สามารถขยายไปยัง Docs, Chat, Tasks, Admin, Classroom และ Workspace APIs อื่น ๆ ได้ต่อไป

#แหล่งอ้างอิง

ควรตรวจสอบ gws --help, gws <service> --help และ repository ล่าสุดก่อนใช้ในระบบจริง เนื่องจากโครงการยังมีการพัฒนาอย่างต่อเนื่อง