Kết Nối Google Workspace

Level: L7 — MCP, API & Connectors (Bài 7/11 theo thứ tự sản xuất — · Đối tượng: Người đã học bài 65-69 (API/Webhook/Tool Calling/MCP),

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Giải thích vì sao Google Workspace là ví dụ tốt cho “1 lần xác thực, nhiều dịch vụ” — áp dụng đúng khái niệm scope (đào sâu ở bài 74).
Đọc và hiểu 3 thao tác cốt lõi của Google Docs API: create, get, batchUpdate.
Thiết kế được luồng kết nối Notes App (dự án tích lũy) với Google Docs để nhập nội dung ghi chú từ tài liệu có sẵn.
Xác định đúng scope tối thiểu cần cho 1 tác vụ cụ thể trong hệ sinh thái đa dịch vụ của Google.

2. Khái niệm cốt lõi

Bước 1 — Concept: bạn đã có 1 Notes App (dự án tích lũy, hoàn thiện ở bài 64/L6). Nhưng người dùng thường đã có sẵn nội dung nằm rải rác ở nơi khác — ví dụ: ghi chú cuộc họp đã viết trong Google Docs. Làm sao Notes App đọc được nội dung đó thay vì bắt người dùng gõ lại?

Bước 2/3 — Real implementation trên nền chuẩn đã học (Google Workspace là ví dụ cụ thể, không phải chuẩn mở riêng — áp dụng lại đúng chuẩn REST đã học bài 65, cộng khái niệm OAuth sẽ đào sâu ở bài 74): Google Workspace cung cấp API riêng cho nhiều dịch vụ dưới cùng 1 hệ sinh thái: Docs, Sheets, Slides, Forms, Sites (năng suất); Gmail, Calendar, Chat, Meet (giao tiếp); Drive, Keep, Tasks, Classroom (tổ chức) [S109]. Đây là điểm đặc thù quan trọng nhất của Google so với các bài 71-73: 1 lần xác thực OAuth (bài 74) có thể mở ra quyền truy cập nhiều dịch vụ khác nhau, tùy vào scope cụ thể bạn xin cho từng dịch vụ.

3 thao tác cốt lõi của Google Docs API [S109] — đúng mẫu hình REST đã học bài 65:

create — tạo tài liệu mới (method POST).
get — lấy nội dung 1 tài liệu (method GET).
batchUpdate — áp dụng 1 hoặc nhiều thay đổi cho tài liệu (method POST) — ví dụ endpoint: https://docs.googleapis.com/v1/documents/{documentId}.

3. Tại sao nội dung này quan trọng

Đây là lần đầu tiên trong hành trình Level 7 bạn áp dụng đồng thời mọi khái niệm đã học: gọi API thật (bài 65), qua xác thực OAuth thật (bài 74), có thể kết hợp Tool Calling (bài 67) để AI tự quyết định khi nào cần đọc 1 tài liệu Google Docs cụ thể. Google Workspace, với hệ sinh thái đa dịch vụ, còn dạy thêm 1 bài học riêng: scope không phải “tất cả hoặc không gì” — bạn có thể xin quyền đọc Docs nhưng không xin quyền đọc Gmail, dù cùng 1 nhà cung cấp.

4. Cơ chế hoạt động

Luồng kết nối Notes App với Google Docs (áp dụng khái niệm OAuth sẽ đào sâu ở bài 74, cụ thể hóa cho Google):

Đăng ký ứng dụng với Google, nhận client_id/client_secret.
Xin đúng scope cần cho Docs (đọc, hoặc đọc+ghi tùy tác vụ) — không xin thêm scope Gmail/Calendar nếu chưa cần dùng tới.
Người dùng đồng ý qua màn hình OAuth của Google (đúng luồng tổng quát đã áp dụng, đào sâu ở bài 74).
Nhận access token, dùng để gọi API Docs: GET để đọc nội dung tài liệu người dùng chỉ định.
Đưa nội dung đọc được vào Notes App như 1 ghi chú mới (có thể qua Tool Calling — bài 67 — nếu để AI tự quyết định khi nào cần đọc).

5. Mental model

Tiếp nối ẩn dụ mạng lưới nhà cung cấp: Google Workspace giống 1 tập đoàn có nhiều phòng ban riêng biệt (phòng văn bản = Docs, phòng lịch = Calendar, phòng thư từ = Gmail) nhưng dùng chung 1 cổng bảo vệ (OAuth). Khi bạn xin phép vào tập đoàn, bạn chỉ nên xin chìa khóa đúng phòng ban cần vào — không xin chìa khóa toàn bộ tòa nhà chỉ vì “tiện.”

6. Hướng dẫn từng bước

Checklist kết nối Notes App với Google Docs (tổng hợp của người viết, dựa trên S109, áp dụng khái niệm sẽ đào sâu ở bài 74):

Xác định chính xác dịch vụ Google cần (Docs, không phải toàn bộ Workspace).
Đăng ký OAuth app, xin đúng scope của riêng Docs.
Xác định thao tác cần: chỉ đọc (get) hay cả tạo/sửa (create/batchUpdate)?
Thiết kế 1 tool (đúng khái niệm bài 67) cho AI: ví dụ “đọc nội dung 1 Google Doc theo ID” — mô tả rõ để model biết khi nào nên gọi.
Lưu access token đúng cách (biến môi trường, bài 63/L6).

7. Ví dụ thực tế

Vendor example cụ thể: với dự án Notes App, thiết kế 1 tool “Nhập từ Google Docs” — khi người dùng nói “tóm tắt tài liệu họp hôm qua,” AI (qua Tool Calling, bài 67) gọi tool này với ID tài liệu tương ứng, tool thực hiện GET tới Docs API, trả nội dung về cho AI xử lý tiếp (ví dụ: tạo bản tóm tắt, đúng tính năng đã xây ở bài 64/L6).

8. Prompt/template/workflow

Khung thiết kế tích hợp Google Workspace (tái sử dụng):

Dịch vụ Google cần kết nối: [Docs/Calendar/Drive/...]
Thao tác cần: [chỉ đọc / đọc và ghi]
Scope tối thiểu tương ứng: [xác định qua tài liệu chính thức]
Tool cho AI (nếu áp dụng bài 67): [tên tool, mô tả, tham số]

9. Visual hoặc diagram cần thiết

Hình 7.6 — Google Workspace: 1 cổng OAuth chung, chìa khoá riêng từng phòng — Notes App chỉ có quyền Docs.

10. Bài tập thực hành

Tra cứu tài liệu chính thức Google Docs API — xác định scope cụ thể cần cho việc chỉ đọc nội dung tài liệu.
Thiết kế 1 tool (bài 67) để AI gọi khi cần đọc 1 Google Doc, dùng khung ở mục 8.
Viết ra: nếu sau này Notes App cần thêm đọc lịch (Calendar) để tự tạo ghi chú nhắc việc, scope nào cần thêm — có ảnh hưởng tới scope Docs đã xin trước đó không?

11. Checklist

Giải thích được vì sao Google Workspace là ví dụ "1 xác thực, nhiều dịch vụ."
Đọc hiểu 3 thao tác cốt lõi của Docs API.
Thiết kế được luồng kết nối Notes App với Google Docs.
Xác định đúng scope tối thiểu cho 1 dịch vụ cụ thể, không xin dư.

12. Lỗi thường gặp

(Suy luận từ nguyên tắc [S109] + bài 65/74, không phải quan sát độc lập.)

Xin scope “toàn bộ Google Workspace” thay vì đúng dịch vụ cần — đúng vi phạm nguyên tắc least privilege (đào sâu ở bài 74).
Dùng batchUpdate khi chỉ cần get — thực hiện thao tác ghi khi chỉ cần đọc, tăng rủi ro không cần thiết.
Không kiểm tra ID tài liệu hợp lệ trước khi gọi API — dẫn tới lỗi hoặc (tệ hơn) đọc nhầm tài liệu khác nếu ID sai định dạng.

13. Giới hạn & khi nào KHÔNG nên áp dụng

Bài này không dạy chi tiết từng API con (Docs/Calendar/Gmail) — chỉ dạy mẫu hình chung + ví dụ Docs; tra cứu tài liệu chính thức của dịch vụ cụ thể khi triển khai thật.
Không dạy lại cơ chế OAuth (bài 74) hay Tool Calling (bài 67) — chỉ áp dụng.
Danh sách scope chi tiết không có trong nguồn đã thu thập — cần tra cứu tài liệu API con cụ thể trước khi triển khai thật (đã ghi rõ trong raw note S109).

14. An toàn & quản trị (Safety/Governance)

Rủi ro riêng của Google Workspace (do là 1 hệ sinh thái đa dịch vụ): xin scope rộng cho “cả Workspace” thay vì đúng 1 dịch vụ là rủi ro dữ liệu cao hơn nhiều so với các tích hợp đơn dịch vụ (71-73) — nếu credential bị lộ, phạm vi thiệt hại có thể lan qua nhiều dịch vụ cùng lúc (Docs + Gmail + Calendar) thay vì giới hạn ở 1 nơi. Đây là ví dụ cụ thể đầu tiên minh họa vì sao nguyên tắc least privilege (bài 74) quan trọng hơn nhiều khi tích hợp với 1 nhà cung cấp đa dịch vụ — sẽ được tổng hợp đầy đủ ở bài 75.

15. Best practices

Luôn xác định đúng 1 dịch vụ cần trước khi xin scope — không xin “trọn gói Workspace.”
Ưu tiên get (chỉ đọc) khi tác vụ không cần ghi/sửa.
Thiết kế tool (bài 67) với mô tả rõ ràng, giới hạn đúng phạm vi tài liệu/dữ liệu cần đọc — không để AI tự do đọc “mọi Google Doc.”

16. Nội dung nâng cao (không bắt buộc)

Ngoài luồng đọc/ghi cơ bản, Google Workspace còn hỗ trợ Push Notifications (dạng webhook, đã học bài 66) để được báo ngay khi 1 tài liệu thay đổi, thay vì phải liên tục gọi get để kiểm tra — áp dụng đúng nguyên tắc Pull vs Push đã học, không lặp lại giải thích ở đây.

17. Nguồn tham khảo

[S109] Google Workspace APIs (Reference Overview) — developers.google.com/workspace — hệ sinh thái đa dịch vụ, 3 thao tác cốt lõi Docs API.
Dẫn chiếu (không trích dẫn mới): bài 65 (REST cơ bản); bài 66 (webhook, dẫn chiếu mục 16); bài 67 (Tool Calling); bài 74 (Authentication, scope, least privilege).

18. Ngày kiểm chứng

Nội dung kiểm chứng qua nguồn Tier 1 (S109) ngày 2026-07-13. Mẫu hình API (create/get/batchUpdate, REST) ổn định; danh sách scope/endpoint chi tiết của từng dịch vụ con có thể đổi theo thời gian — khuyến nghị re-verify trước khi triển khai thật.