Google Sheets API: Hướng dẫn Từng Bước cho Người Mới Bắt Đầu

Google Sheets thường là nơi các nhóm lưu trữ và chia sẻ dữ liệu. Nhưng khi bạn phải cập nhật cùng một trang tính lặp đi lặp lại, việc sao chép-dán thủ công sẽ lãng phí thời gian.

Google Sheets API giúp bạn cập nhật và quản lý các trang tính tự động từ ứng dụng và script của riêng bạn. Bạn có thể kéo dữ liệu vào, đẩy cập nhật ra và giữ báo cáo luôn mới mà không cần làm thủ công.

Trong hướng dẫn này, chúng tôi sẽ hướng dẫn bạn cách thiết lập, đọc, ghi, định dạng và tự động hóa các tác vụ bảng tính phổ biến từng bước.

Bắt đầu với Google Sheets API

Để bắt đầu sử dụng Google Sheets API, bạn cần một dự án Google Cloud và cách xác thực ứng dụng của mình. Hãy xem cách thiết lập ở mức khái quát. 

Tạo dự án Google Cloud

Tất cả Google API đều chạy trong một dự án Google Cloud. Dự án này chứa thông tin xác thực, cài đặt API và giới hạn sử dụng của bạn.

Cách tạo dự án đầu tiên của bạn: 

• Đi tới Google Cloud Console.
• Nhấp Select a project ở trên cùng.
• Một cửa sổ bật lên Select a project xuất hiện. Tại đây, nhấp New Project.
• Ở cửa sổ tiếp theo, nhập tên dự án.
• Nhấp Create.

Tạo dự án mới trong Google Console. Ảnh: Tác giả.

Khi dự án đã sẵn sàng, hãy bật các API cần thiết: 

• Mở dự án của bạn.
• Nhấp vào ba dòng ở góc trên bên trái. 
• Đi tới APIs & Services > Enabled APIs & services.
• Nhấp + Enable APIs & services.

Vào Enable APIs & Services để bật API. Ảnh: Tác giả.

• Giờ cửa sổ API Library sẽ xuất hiện. Trong thanh tìm kiếm, tìm Google Sheets API và nhấp vào.
• Nhấp Enable.

Bật Google Sheets API. Ảnh: Tác giả.

Nếu ứng dụng của bạn cần tạo, di chuyển hoặc quản lý tệp bảng tính, hãy bật cả Google Drive API: 

• Tìm Google Drive API.
• Nhấp Enable.

Xác thực và ủy quyền

Google Sheets API hỗ trợ ba phương thức xác thực chính. Bạn dùng phương thức nào tùy thuộc vào cách ứng dụng của bạn hoạt động.

OAuth 2.0

Dùng khi người dùng thực đăng nhập và làm việc với bảng tính của riêng họ. Cách này cho phép người dùng phê duyệt quyền truy cập và ứng dụng của bạn chỉ có thể làm những gì họ cho phép.

Giả sử bạn đang xây dựng một ứng dụng web cho phép người dùng kết nối tài khoản Google của họ để ứng dụng có thể đọc hoặc cập nhật Sheets cá nhân. Trong trường hợp này, hãy chọn OAuth 2.0. 

Cách thực hiện:

• Trong Google Console, vào Navigation Menu (ba dòng ở góc trên bên trái) > API & Services > OAuth consent screen

Đi tới màn hình đồng ý OAuth. Ảnh: Tác giả.

• Bây giờ điền thông tin chi tiết: 
• Nhập tên ứng dụng cần xin phép vào trường App name
• Nhập email hỗ trợ để người dùng có thể đặt câu hỏi tại đó và nhấp Next
• Chọn loại đối tượng External và nhấp Next
• Tiếp theo, điền thông tin liên hệ (địa chỉ email) để Google có thể thông báo cho bạn về các thay đổi của dự án. Sau đó, nhấp Next
• Đồng ý chính sách bằng cách tích vào ô và nhấp Continue

• Nhấp Save. Một thông báo sẽ xuất hiện hiển thị OAuth configuration created!

Giờ, để xác thực người dùng cuối và truy cập dữ liệu Google Sheets của họ, hãy tạo thông tin xác thực client OAuth 2.0. Client ID xác định duy nhất ứng dụng của bạn với máy chủ OAuth của Google.

Cách thực hiện: 

• Nhấp vào Navigation Menu > APIs & Services > Credentials.
• Trong cửa sổ Credentials, nhấp + Create credentials và chọn OAuth client ID.

Đi tới OAuth client ID. Ảnh: Tác giả.

• Chọn Web Application trong danh sách thả xuống Application type.
• Nhập tên client OAuth 2.0 để nhận diện trong bảng điều khiển.
• Trong Authorized redirect URIs, nhấp Add URI
• Nhập URL chuyển hướng nơi Google sẽ gửi phản hồi ủy quyền. URL này phải khớp chính xác với redirect URI được cấu hình trong ứng dụng của bạn (ví dụ, endpoint callback OAuth của bạn)
• Nhấp Create
• Sao chép và lưu Client ID và Client Secret. 

API keys

API key xác định dự án của bạn, không phải người dùng. Chúng chỉ hoạt động với bảng tính công khai và không thể chỉnh sửa tệp riêng tư.

Vì vậy, bạn chỉ nên dùng khi muốn đọc dữ liệu từ một Google Sheet công khai để hiển thị trên website hoặc thử nghiệm script đơn giản.

Cách tạo API key: 

• Đi tới Navigation Menu > APIs & Services > Credentials.

Đi tới API Keys. Ảnh: Tác giả.

• Nhấp + Create credentials, sau đó chọn API key.
• Cuộn xuống, chọn ô Restrict key, rồi chọn các API trong danh sách thả xuống mà API key này có thể sử dụng. 
• Nhấp Create.
• Sao chép và lưu khóa được tạo.

Lưu API key đã tạo. Ảnh: Tác giả.

Service accounts

Service account cho phép ứng dụng của bạn chạy độc lập, không cần người dùng đăng nhập. Bạn chia sẻ các bảng tính cụ thể với email của service account và kiểm soát những gì nó có thể làm.

Nếu bạn muốn chạy một script theo lịch để cập nhật báo cáo mỗi đêm hoặc đồng bộ dữ liệu từ cơ sở dữ liệu vào một Google Sheet dùng chung, service account sẽ là lựa chọn tốt nhất. 

Hãy xem cách tạo và cấu hình chúng: 

Tạo và cấu hình service account

Cách thực hiện: 

• Nhấp vào Google Sheets API mà chúng ta đã bật trước đó. 
• Ở góc trên bên trái, nhấp nút Create credentials.

Tạo Credentials trong Google Sheets API. Ảnh: Tác giả.

• Trong cửa sổ Create Credentials, đảm bảo Google Sheets API được chọn trong trường Select an API. Giờ chọn loại dữ liệu bạn muốn truy cập. Vì bạn đang dùng service account, chọn Application data và nhấp Next.

Nhập thông tin xác thực. Ảnh: Tác giả.

• Giờ một cửa sổ mới Create service account xuất hiện:
• Thêm Tên service account, ID service account và Mô tả service account. 
• Nhấp Create and continue.

Một thông báo bật lên sẽ hiển thị Service account created.

Tạo service account trong Google Sheets API. Ảnh: Tác giả.

Service account không dùng đăng nhập hay màn hình đồng ý. Thay vào đó, nó xác thực bằng khóa riêng lưu trong tệp khóa JSON. Tệp khóa này cho phép máy chủ ứng dụng chứng minh danh tính với Google và tự động yêu cầu access token.

Giờ, để tạo tệp khóa: 

• Mở service account. (Bạn cũng có thể tìm thấy nó dưới IAM & Admin > Service Account) 
• Đi tới tab Keys.
• Nhấp Add key > Create new key.
• Chọn JSON và nhấp Create.

Tệp sẽ bắt đầu tải xuống. 

Tạo tệp khóa JSON cho Google Sheets API. Ảnh: Tác giả.

Chia sẻ Google Sheets với service account

Service account không tự động có quyền truy cập bảng tính của bạn. Bạn phải chia sẻ từng tệp với email của service account.

Cách thực hiện: 

• Mở tệp chúng ta đã tải xuống và tìm client_email. Hoặc nhấp vào service account đã tạo trong menu Service Account, sau đó tìm Email. Đây đều là cùng một địa chỉ email. 
• Sao chép email đó. 

Sao chép client email từ tệp khóa JSON. Ảnh: Tác giả.

• Mở Google Sheet.
• Đi tới tùy chọn Share ở góc trên bên phải. 
• Dán email đã sao chép vào trường chia sẻ.
• Chọn quyền Viewer (cho phép đọc và ghi dữ liệu) hoặc Editor (chỉ cho phép đọc) . 
• Nhấp Send để chia sẻ quyền truy cập. 

Chia sẻ quyền truy cập service account qua Google Sheets. Ảnh: Tác giả.

Cài đặt thư viện khách hàng

Google cung cấp các thư viện khách hàng chính thức giúp đơn giản hóa việc làm việc với Sheets API. Chúng xử lý xác thực, định dạng yêu cầu và retry cho bạn. Thực tế, cách này dễ và an toàn hơn so với gửi yêu cầu HTTP thô.

Dưới đây là các ví dụ cài đặt cho những ngôn ngữ phổ biến:

Python

pip install google-api-python-client google-auth google-auth-oauthlibĐược hỗ trợ bởi

Node.js

npm install googleapisĐược hỗ trợ bởi

Java (thêm thư viện khách hàng bằng Maven)

<dependency>
  <groupId>com.google.apis</groupId>
  <artifactId>google-api-services-sheets</artifactId>
</dependency>Được hỗ trợ bởi

Lưu ý: Thư viện khách hàng giúp tiết kiệm thời gian thiết lập và giảm lỗi khi dự án của bạn lớn dần.

Các thao tác dữ liệu cốt lõi

Google Sheets API chủ yếu được dùng để đọc, ghi, cập nhật và định dạng dữ liệu bảng tính. Hãy cùng tìm hiểu: 

Đọc dữ liệu từ bảng tính

Để đọc dữ liệu từ một Google Sheet, bạn cần hai thứ: ID bảng tính và phạm vi ô bạn muốn truy cập.

Spreadsheet ID lấy từ URL của Google Sheets. Đó là chuỗi dài giữa /d/ và /edit. Nó cho API biết cần đọc từ bảng tính nào.

Ví dụ, nếu URL Sheet của tôi là: https://docs.google.com/spreadsheets/d/1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI/edit?gid=0#gid=0  

Trong trường hợp này, Spreadsheet ID là: 1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI

Spreadsheet ID. Ảnh: Tác giả.

Phạm vi được viết theo ký hiệu A1, mô tả các ô bằng chữ cột và số hàng. Ví dụ:

• A1 đọc một ô đơn

• A1:C10 đọc một khối ô

• Sheet1!A:A đọc toàn bộ một cột

• Sheet1!1:1 đọc toàn bộ một hàng

Để lấy giá trị, API cung cấp hai phương thức chính:

• spreadsheets.values.get đọc dữ liệu từ một phạm vi đơn. Dùng khi bạn biết chính xác bảng hay khối cần lấy. 

• spreadsheets.values.batchGet đọc dữ liệu từ nhiều phạm vi trong một yêu cầu. Dùng khi bạn cần dữ liệu từ nhiều nơi cùng lúc, như tổng hợp từ một sheet và chi tiết từ sheet khác.

Đọc dữ liệu không thay đổi bảng tính. Nó chỉ trả về giá trị để ứng dụng của bạn dùng ở nơi khác. Bạn có thể dùng để kéo dữ liệu vào dashboard, xuất dữ liệu để phân tích và tạo báo cáo tự động.

Ghi dữ liệu vào bảng tính

Ghi dữ liệu tương tự như đọc dữ liệu. Bạn vẫn cần Spreadsheet ID và phạm vi, nhưng lần này bạn cũng gửi các giá trị muốn ghi.

Google Sheets API cung cấp hai phương thức chính cho việc này:

• spreadsheets.values.update: Dùng khi bạn muốn ghi dữ liệu vào một phạm vi cụ thể và ghi đè nội dung hiện có. Ví dụ, nếu bạn muốn thay thế hàng tiêu đề của một bảng bằng tên cột mới, update là lựa chọn đúng. Các giá trị bạn gửi sẽ thay thế ô hiện có trong phạm vi đó.

• spreadsheets.values.append: Dùng khi bạn muốn thêm hàng mới mà không ảnh hưởng dữ liệu hiện có. Hữu ích khi dữ liệu tăng dần theo thời gian, như ghi log chỉ số hằng ngày, thêm bản ghi mới hoặc lưu phản hồi biểu mẫu. API sẽ tự động chèn giá trị mới sau hàng không rỗng cuối cùng.

Tùy chọn nhập giá trị

Khi ghi dữ liệu, bạn cũng cần chọn cách Google Sheets xử lý giá trị gửi lên. Điều này được kiểm soát bởi ValueInputOption.

• RAW lưu giá trị đúng như bạn gửi

• USER_ENTERED xử lý giá trị như thể được nhập trực tiếp vào trang tính

Ví dụ, nếu bạn gửi =SUM(1,2):

• Với RAW, nó được lưu dưới dạng văn bản thường

• Với USER_ENTERED, nó được đánh giá như một công thức

Ghi đè so với thêm dữ liệu

Chọn giữa update và append phụ thuộc vào cách trang tính của bạn được cấu trúc.

Dùng update khi:

• Vị trí dữ liệu cố định
• Bạn đang thay thế tiêu đề hoặc các ô đã biết

Dùng append khi:

• Dữ liệu tăng theo thời gian
• Bạn muốn tránh ghi đè các hàng hiện có

Tác vụ theo lô (batch)

Batch cho phép bạn nhóm nhiều thay đổi trong một yêu cầu API. Điều này giảm số lần gọi từ ứng dụng và giúp bạn ở trong giới hạn sử dụng.

Có hai kiểu batch phổ biến trong Google Sheets API.

Đối với giá trị, bạn có thể dùng:

• spreadsheets.values.batchGet để đọc nhiều phạm vi cùng lúc

• spreadsheets.values.batchUpdate để ghi vào nhiều phạm vi trong một yêu cầu

Đối với thay đổi cấu trúc và định dạng, dùng spreadsheets.batchUpdate. Đây là phương thức batch hữu ích nhất và hỗ trợ nhiều hành động trong một yêu cầu.

Với spreadsheets.batchUpdate, bạn có thể kết hợp các thay đổi như:

• Tạo hoặc xóa sheet
• Đổi tên bảng tính hoặc tab
• Đóng băng hàng tiêu đề
• Thay đổi độ rộng cột
• Áp dụng định dạng
• Cập nhật nhiều phạm vi cùng lúc

Ví dụ, thay vì gửi yêu cầu riêng để đổi tên bảng tính và tạo tab mới, bạn có thể làm cả hai trong một lệnh batchUpdate. Cách này nhanh hơn và dễ quản lý hơn khi quy trình của bạn lớn dần.

Bạn có thể dùng batch để thiết lập báo cáo, áp dụng định dạng nhất quán hoặc cập nhật lớn trên toàn bộ bảng tính.

Cập nhật và xóa dữ liệu

Cập nhật dữ liệu nghĩa là thay thế giá trị trong các ô hoặc phạm vi cụ thể. Việc này thường dùng khi bạn muốn làm mới số liệu, cập nhật KPI hoặc ghi đè một vùng đầu ra cố định trong sheet.

Để cập nhật giá trị hiện có, dùng spreadsheets.values.update. Tại đây, bạn chỉ định phạm vi đích và gửi giá trị mới, dữ liệu hiện có trong phạm vi đó sẽ bị thay thế.

Xóa nội dung so với xóa dữ liệu

Xóa nội dung và xóa dữ liệu không giống nhau:

Xóa nội dung sẽ loại bỏ giá trị trong ô nhưng giữ nguyên sheet, bố cục và định dạng. Dùng spreadsheets.values.clear khi bạn muốn làm trống một phạm vi mà không ảnh hưởng cấu trúc.

Ví dụ: Xóa nội dung phần báo cáo cũ trước khi ghi dữ liệu mới vào chính các ô đó.

Xóa dữ liệu là xóa hẳn một tab sheet. Việc này được thực hiện bằng spreadsheets.batchUpdate với yêu cầu deleteSheet. Xóa sheet sẽ loại bỏ vĩnh viễn dữ liệu và cấu trúc của nó.

Vì xóa sheet là không thể hoàn tác, tốt nhất chỉ dùng khi bạn chắc chắn dữ liệu không còn cần thiết.

Tính năng và chức năng nâng cao

Ngoài đọc và ghi dữ liệu, Google Sheets API cho phép bạn kiểm soát cách bảng tính hiển thị và hoạt động. Điều này giúp tự động hóa định dạng và quy tắc trực quan ở quy mô lớn.

Định dạng và định dạng có điều kiện

Google Sheets API cho phép bạn áp dụng định dạng ô bằng lập trình thay vì qua giao diện Sheets. Bao gồm kiểu chữ, màu sắc, định dạng số và thay đổi bố cục.

Tất cả thay đổi định dạng được gửi như yêu cầu JSON qua spreadsheets.batchUpdate. Mỗi yêu cầu mô tả cần thay đổi gì và áp dụng ở đâu.

Các tác vụ định dạng phổ biến gồm:

• Bôi đậm hàng tiêu đề
• Áp dụng định dạng số cho tiền tệ hoặc phần trăm
• Điều chỉnh độ rộng cột
• Đặt màu nền cho phạm vi cụ thể

Ví dụ, một yêu cầu định dạng có thể nhắm tới hàng đầu tiên của sheet và làm đậm với màu nền nhạt. Yêu cầu dùng chỉ số bắt đầu từ 0, trong đó hàng 0 là hàng đầu tiên.

Định dạng có điều kiện

Định dạng có điều kiện cho phép bạn tạo kiểu ô tự động dựa trên giá trị của chúng. Nếu bạn muốn Sheets làm nổi bật dữ liệu quan trọng mà không cần rà soát thủ công, định dạng có điều kiện sẽ hữu ích. 

Khi dùng API, các quy tắc định dạng có điều kiện được định nghĩa bằng JSON và áp dụng qua spreadsheets.batchUpdate.

Bạn có thể dùng để:

• Tô đỏ các giá trị âm
• Gắn cờ các giá trị trên hoặc dưới ngưỡng
• Tự động tạo kiểu cho các hàng thỏa điều kiện nhất định

Ví dụ, bạn có thể định nghĩa quy tắc tô nổi bật mọi giá trị dưới 0 trong một cột cụ thể. Sau khi áp dụng, định dạng sẽ tự động cập nhật khi dữ liệu thay đổi.

Pivot table và tổng hợp dữ liệu

Google Sheets API có thể tạo và cập nhật pivot table bằng mã. Pivot table tóm tắt các tập dữ liệu lớn mà không thay đổi dữ liệu gốc, giúp cho việc báo cáo và phân tích.

Bạn chỉ cần định nghĩa pivot table bằng yêu cầu JSON và áp dụng với spreadsheets.batchUpdate. Những yêu cầu này mô tả cách nhóm, tổng hợp và hiển thị dữ liệu.

Qua API, bạn có thể:

• Chọn cột làm nhãn hàng
• Chọn phương pháp tổng hợp như tổng, đếm hoặc trung bình
• Kiểm soát vị trí xuất hiện của pivot table
• Làm mới hoặc chỉnh sửa pivot table khi dữ liệu mới được thêm

Ví dụ, bạn có thể nhóm các hàng theo từ khóa và tự động tính tổng số lượt nhấp và hiển thị. Khi dữ liệu nền thay đổi, pivot table cũng tự động cập nhật.

Connected Sheets và tích hợp BigQuery

Connected Sheets cho phép Google Sheets làm việc trực tiếp với BigQuery. BigQuery xử lý các tập dữ liệu lớn, trong khi Sheets được dùng cho phân tích và báo cáo. 

Thay vì sao chép hàng triệu dòng vào sheet, Connected Sheets chạy truy vấn trên BigQuery và hiển thị kết quả. Điều này giúp bảng tính nhanh và phản hồi tốt, ngay cả với tập dữ liệu rất lớn.

Kết nối được tạo từ trong Google Sheets. Google Sheets API không được dùng để thiết lập kết nối này.

Cách hoạt động như sau:

• Dữ liệu nằm trong một bảng BigQuery
• Bạn kết nối một Google Sheet với bảng đó
• Sheets chạy truy vấn và hiển thị kết quả
• Dữ liệu có thể được làm mới mà không cần xuất tệp

Khi đã kết nối, bạn có thể tạo pivot table, áp dụng công thức và lập báo cáo trực tiếp trong Sheets.

Xác thực và phân quyền

Quyền truy cập Connected Sheets được kiểm soát qua Google Cloud Identity and Access Management.

Tài khoản kết nối Sheets với BigQuery phải có:

• Quyền BigQuery Data Viewer
• Quyền BigQuery Job User
• Quyền truy cập Google Sheet

Xác thực được xử lý tự động qua giao diện Google Sheets.

Tuy nhiên, bạn nên lưu ý một số giới hạn. Mặc dù Sheets API có thể đọc dữ liệu từ Connected Sheets và áp dụng định dạng hoặc tạo pivot table, nó không thể sửa đổi truy vấn BigQuery nền hoặc ghi dữ liệu trở lại các phạm vi dựa trên BigQuery.

Vì vậy, Connected Sheets phù hợp nhất cho phân tích và báo cáo, không phải để chèn hoặc chỉnh sửa dữ liệu thô.

Dùng công cụ tích hợp no-code

Không phải mọi quy trình đều cần mã tùy chỉnh. Một số công cụ no-code và low-code kết nối trực tiếp với Google Sheets API và xử lý các chi tiết kỹ thuật cho bạn. Ba lựa chọn phổ biến gồm:

• Apipheny
• Supermetrics
• Funnel

Những công cụ này cung cấp giao diện trực quan để chọn nguồn dữ liệu, đặt lịch và gửi kết quả tới Google Sheets. Chúng xử lý xác thực, yêu cầu API và xử lý lỗi ở hậu trường.

Điều này khiến các công cụ no-code phù hợp với marketer và nhà phân tích cần pipeline dữ liệu đáng tin cậy mà không cần viết mã. Chúng cũng rút ngắn thời gian thiết lập cho các trường hợp báo cáo và dashboard phổ biến.

Giá và giới hạn API

Với hầu hết dự án, bạn có thể dùng Google Sheets API miễn phí. Điều quan trọng là hiểu cách giới hạn sử dụng hoạt động.

Tổng quan giá API

Google không tính phí theo yêu cầu hoặc theo hành động trong bảng tính. Thay vào đó, việc sử dụng được kiểm soát bởi hạn ngạch. 

Miễn là dự án của bạn nằm trong các giới hạn đó, bạn có thể dùng API miễn phí. Nếu vượt quá, yêu cầu sẽ tạm thời bị chặn cho đến khi mức sử dụng giảm hoặc giới hạn được tăng.

Giới hạn sử dụng và hạn ngạch

Google Sheets API áp đặt giới hạn để duy trì ổn định hiệu năng và ngăn lạm dụng. Các giới hạn này thường áp dụng theo dự án và, trong một số trường hợp, theo người dùng.

Hầu hết dự án gặp hai loại giới hạn chính:

1. Số yêu cầu mỗi phút: Giới hạn này kiểm soát số lệnh gọi API dự án của bạn có thể gửi trong thời gian ngắn. Quá nhiều yêu cầu nhỏ gửi cùng lúc có thể gây lỗi tạm thời.

Theo mặc định, Google Sheets API cho phép:

Giới hạn chủ yếu áp dụng cho số yêu cầu bạn gửi mỗi phút, không phải tổng số trong ngày.

Để ở trong giới hạn và tránh sự cố:

• Gộp nhiều cập nhật vào một yêu cầu
• Tránh đọc lặp lại cho các thay đổi nhỏ
• Cache dữ liệu thay vì lấy lại
• Theo dõi mức sử dụng trong Google Cloud Console và điều chỉnh sớm

Tối ưu hiệu năng và quản lý hạn ngạch

Khi bạn tự động hóa Google Sheets, vấn đề hiệu năng thường đến từ việc gửi quá nhiều yêu cầu quá nhanh. Vì vậy, điều quan trọng là hiểu cách hạn ngạch hoạt động. 

Hiểu hạn ngạch và giới hạn tốc độ API

Google áp dụng hạn ngạch để giới hạn số yêu cầu dự án của bạn có thể gửi trong một khoảng thời gian nhất định. Một số giới hạn áp dụng theo dự án, số khác áp dụng theo người dùng.

Những giới hạn này ảnh hưởng trực tiếp đến quy trình tự động. Nếu script của bạn gửi quá nhiều yêu cầu quá nhanh, API sẽ bắt đầu trả lỗi và quy trình dừng lại. Điều này thường xảy ra khi script:

• Cập nhật từng hàng một
• Đọc lặp lại những phạm vi lớn
• Chạy quá thường xuyên mà không batch

Theo dõi mức sử dụng giúp bạn phát hiện sớm vấn đề. Trong Google Cloud Console, bạn có thể xem dự án của mình gần chạm giới hạn đến đâu và phát hiện đột biến hoạt động. Cách làm:

• Mở dự án của bạn.
• Vào APIs & Services > Enabled API Services 
• Nhấp Google Sheets API.
• Mở Quotas & System Limits.

Nếu bạn thấy đột biến, thường đó là dấu hiệu của mẫu yêu cầu kém hiệu quả.

Hạn ngạch và giới hạn hệ thống. Ảnh: Tác giả.

Triển khai exponential backoff

Ngay cả script viết tốt cũng có thể gặp lỗi API tạm thời. Những lỗi phổ biến nhất rất dễ nhận ra:

• Lỗi 429 nghĩa là gửi quá nhiều yêu cầu trong thời gian ngắn
• Lỗi 5xx nghĩa là API gặp sự cố máy chủ tạm thời

Những lỗi này thường tự hết. Thử lại ngay lập tức có thể làm vấn đề tệ hơn.

Exponential backoff là cách tiêu chuẩn để thử lại yêu cầu một cách an toàn. Thay vì thử lại ngay, script của bạn đợi trước khi thử lần nữa. Thời gian đợi tăng sau mỗi lần thất bại.

Mẫu backoff đơn giản như sau:

• Gửi một yêu cầu
• Nếu nhận lỗi 429 hoặc 5xx, chờ một giây
• Thử lại
• Nếu lại thất bại, chờ hai giây, rồi bốn, rồi tám
• Dừng sau thời gian chờ tối đa hoặc số lần thử tối đa

Cách này giảm tải cho API và tăng khả năng thử lại thành công.

Exponential backoff trong thực tế

Đây là ví dụ Python đơn giản thử lại một yêu cầu bằng exponential backoff:

import time
from googleapiclient.errors import HttpError

def run_with_backoff(callable_request, max_retries=5):
    delay = 1

    for attempt in range(max_retries):
        try:
            return callable_request()
        except HttpError as e:
            status = getattr(e.resp, "status", None)

            if status in [429, 500, 502, 503, 504]:
                time.sleep(delay)
                delay = min(delay * 2, 32)
                continue

            raise

    raise RuntimeError("Request failed after retries.")Được hỗ trợ bởi

Bạn có thể bọc bất kỳ lệnh gọi API nào bằng hàm trợ giúp này:

result = run_with_backoff(
    lambda: service.spreadsheets().values().get(
        spreadsheetId=spreadsheet_id,
        range="Report!A1:E100"
    ).execute()
)Được hỗ trợ bởi

Điều này giúp script của bạn không thất bại ngay khi sự cố chỉ tạm thời, giúp quy trình chạy ổn định hơn.

Chiến lược tối ưu

Hiệu năng được cải thiện khi bạn gửi ít yêu cầu hơn và giữ payload nhỏ. Phần lớn chậm trễ xảy ra khi script làm quá nhiều việc trong một lần gọi.

Dưới đây là các kỹ thuật hiệu quả nhất để tránh chậm:

Yêu cầu theo lô

Các phương thức batch như spreadsheets.values.batchGet, spreadsheets.values.batchUpdate, và spreadsheets.batchreadsheets.batchUpdate cho phép bạn kết hợp nhiều hành động trong một yêu cầu. Đây là cách cải thiện hiệu năng lớn nhất.

Bộ nhớ đệm (caching)

Đọc lặp lại cùng một dữ liệu lãng phí thời gian và hạn ngạch. Hãy lấy metadata bảng tính hoặc sheet ID một lần, rồi tái sử dụng trong suốt lần chạy script.

Phân trang

Một số phản hồi API trả dữ liệu theo trang. Xử lý từng trang một thay vì tải tất cả cùng lúc. Điều này tránh quá thời gian và vấn đề bộ nhớ khi làm việc với tập dữ liệu lớn.

Nén Gzip

Hầu hết thư viện khách hàng của Google và HTTP client đều tự động hỗ trợ nén gzip. Nén giúp giảm kích thước khi phản hồi lớn, như khi đọc phạm vi rộng hoặc lấy metadata bảng tính.

Phản hồi một phần

Khi có thể, chỉ yêu cầu các trường bạn cần thay vì toàn bộ tài nguyên. Phản hồi nhỏ hơn nhanh hơn và dùng ít băng thông hơn.

Giảm kích thước payload

Tránh ghi từng ô một. Hãy ghi cả phạm vi. Bỏ qua cập nhật định dạng nếu không có gì thay đổi và đừng gửi lại dữ liệu không cần thiết.

Một quy tắc đơn giản rất hiệu quả: nếu một script lặp qua các hàng và gọi API bên trong vòng lặp đó, nó sẽ không mở rộng tốt. Hãy batch công việc, giảm số yêu cầu và giữ payload nhỏ.

Xử lý lỗi và khắc phục sự cố

Lỗi là một phần khi làm việc với bất kỳ API nào. Vậy hãy xem cách khắc phục sự cố nhanh chóng và giữ tự động hóa ổn định. 

Các vấn đề xác thực thường gặp

Sự cố xác thực là nguồn lỗi phổ biến nhất khi bắt đầu với Google Sheets API. Phần lớn đến từ thiết lập sai hơn là lỗi trong mã của bạn.

Vấn đề thường gặp gồm:

• Lỗi Permission denied: Bảng tính chưa được chia sẻ với email service account, hoặc người dùng chưa cấp các scope OAuth cần thiết
• Lỗi Invalid credentials hoặc file not found: Đường dẫn tệp khóa JSON sai hoặc tên tệp không khớp
• Lỗi API not enabled: Google Sheets API chưa được bật trong cùng dự án Google Cloud với thông tin xác thực

Sự cố OAuth thường xảy ra khi scope không khớp với hành động bạn muốn thực hiện. Ví dụ, scope chỉ đọc sẽ không cho phép ghi.

Sự cố service account thường do thiếu chia sẻ tệp. Service account không thể thấy bất kỳ bảng tính nào trừ khi được chia sẻ rõ ràng với địa chỉ email của nó.

Lỗi định dạng dữ liệu và yêu cầu

Lỗi yêu cầu thường xảy ra khi dữ liệu gửi lên không khớp với kỳ vọng của API. Thông báo lỗi thường mô tả rõ, nhưng ban đầu có thể vẫn gây bối rối.

Nguyên nhân phổ biến gồm:

• Ký hiệu A1 không hợp lệ: Tên sheet viết sai hoặc phạm vi không tồn tại

• Cấu trúc dữ liệu không đúng: Giá trị phải được gửi dưới dạng mảng hai chiều, kể cả với một hàng

• Sai kiểu: Số, ngày và công thức hoạt động khác nhau tùy theo valueInputOption

Khi khắc phục sự cố, luôn đọc toàn bộ phản hồi lỗi vì Google API thường chỉ ra chính xác trường nào không đạt xác thực.

Tính sẵn sàng dịch vụ và thách thức hiệu năng

Giống mọi dịch vụ đám mây, Google Sheets API đôi khi có thể trả lỗi máy chủ như 503 Service Unavailable trong thời gian tải cao hoặc gián đoạn tạm thời.

Những lỗi này thường chỉ tạm thời. Nhưng đừng thử lại ngay vì có thể làm tình hình xấu hơn.

Để xử lý vấn đề độ tin cậy hiệu quả hơn:

• Chỉ thử lại với lỗi tạm thời như phản hồi 429 và 5xx
• Dùng exponential backoff giữa các lần thử
• Batch yêu cầu để giảm lưu lượng
• Theo dõi mức dùng hạn ngạch để tránh chạm giới hạn

Một tích hợp vững chắc giả định rằng một số yêu cầu sẽ thất bại. Việc retry đúng cách, batch và giám sát cho phép script của bạn tự động phục hồi và tiếp tục chạy mà không cần can thiệp thủ công.

Thực hành tốt và bảo mật

Google Sheets API dễ sử dụng, nhưng độ tin cậy lâu dài phụ thuộc vào cách chúng ta thiết kế và bảo mật thiết lập.

Công cụ và tài nguyên phát triển

Google cung cấp các công cụ và tài nguyên chính thức để giúp phát triển an toàn và dễ dàng hơn:

• Google Workspace APIs Explorer cho phép bạn thử các yêu cầu Sheets API trực tiếp trên trình duyệt. Bạn có thể thử nghiệm endpoint, xem tham số bắt buộc và kiểm tra phản hồi mà không cần viết mã. 
• Hướng dẫn nhanh Sheets API trình bày thiết lập cơ bản cho các ngôn ngữ khác nhau. Chúng cho thấy xác thực, một lệnh đọc hoặc ghi đơn giản và các bước cấu hình phổ biến. 
• Tài liệu chính thức phản ánh hành vi hiện tại và các giới hạn đã biết.
• Một bảng tính thử nghiệm cho phép bạn trải nghiệm mà không rủi ro dữ liệu sản xuất hoặc ghi đè báo cáo đang chạy.

Sử dụng thư viện khách hàng và SDK

Google duy trì các thư viện khách hàng chính thức cho Sheets API. Các thư viện này xử lý xác thực, retry và định dạng yêu cầu. Chúng ta có thể giảm lỗi và tiết kiệm thời gian với thư viện được hỗ trợ. Chúng cũng thích ứng tốt hơn với cập nhật API so với mã HTTP tùy chỉnh.

Các ngôn ngữ được hỗ trợ gồm Python, JavaScript với Node.js, Java và Go.

Mỗi thư viện tuân theo cấu trúc API lõi giống nhau, nhưng một số cung cấp trợ giúp theo ngôn ngữ. Python và Node.js thường được ưa chuộng cho tự động hóa do thiết lập đơn giản hơn và cộng đồng mạnh.

Các thư viện khách hàng cũng tích hợp gọn với các Google API khác, hữu ích khi quy trình làm việc liên quan tới Drive, BigQuery hoặc Gmail.

Quản lý thông tin xác thực và bảo mật

Thông tin xác thực kiểm soát quyền truy cập dữ liệu của bạn, vì vậy hãy xử lý đúng bằng cách tuân thủ các thực hành tốt sau:

• Không bao giờ commit tệp khóa vào hệ thống quản lý phiên bản

• Lưu khóa ngoài các kho lưu trữ công khai

• Sử dụng biến môi trường hoặc secret manager trong môi trường sản xuất

• Chỉ cấp quyền cần thiết

• Ưu tiên vai trò hẹp hơn thay vì vai trò rộng

• Giới hạn quyền service account cho các tác vụ cụ thể

• Theo dõi dấu hiệu bất thường hoặc mẫu truy cập lạ

• Thường xuyên xoay vòng khóa và thu hồi, thay thế ngay các khóa bị lộ

Kết luận 

Bước tiếp theo tốt nhất là tự động hóa một tác vụ nhỏ mà bạn đang làm thủ công. Chọn một bảng tính bạn kiểm soát, đọc một phạm vi, rồi ghi hoặc thêm dữ liệu vào đó. Khi đã chạy ổn, hãy đặt lịch và để nó tự vận hành.

Đó là lúc Google Sheets API bắt đầu phát huy hiệu quả. 

Bạn không cần một hệ thống phức tạp ngay lập tức. Một quy trình làm việc ổn định là đủ để tiết kiệm thời gian, và nó khiến việc xây dựng quy trình tiếp theo dễ dàng hơn nhiều. Nếu bạn muốn trau dồi kỹ năng song song với tự động hóa, hãy xem lộ trình Google Sheets Fundamentals hoặc các khóa Introduction to Google Sheets và Intermediate Google Sheets để tối đa giá trị từ mọi quy trình bạn tự động hóa.