Google Apps Script: Khắc phục lỗi 'Authorization required. This script requires your permission to access your data.'

Kịch bản lỗi

Bạn vừa triển khai một Google Apps Script mới, hoặc có thể đã thực hiện một bản cập nhật quan trọng cho một script hiện có. Bạn kích hoạt script, mong đợi nó thực hiện công việc của mình—có thể là cập nhật Google Sheet, gửi email hoặc tương tác với Google Drive. Thay vì kết quả mong đợi, bạn lại gặp phải một thông báo lỗi khó chịu, xuất hiện trong hộp thoại bật lên, nhật ký thực thi hoặc thanh bên:

Authorization required. This script requires your permission to access your data.

Điều này thường xảy ra khi một script được người dùng chạy lần đầu tiên, sau những thay đổi đáng kể trong mã nguồn có giới thiệu các dịch vụ mới, hoặc khi một script được chia sẻ với những cộng tác viên mới chưa cấp quyền. Đó là một trở ngại gây khó chịu, đặc biệt khi bạn đang cố gắng hoàn thành công việc một cách nhanh chóng.

Phân tích: Tại sao điều này xảy ra

Google Apps Script hoạt động trong hệ sinh thái của Google, vốn được bảo mật rất chặt chẽ. Để đảm bảo quyền riêng tư và bảo mật dữ liệu người dùng, Apps Script sử dụng OAuth 2.0. Điều này có nghĩa là bất kỳ script nào cố gắng truy cập dữ liệu hoặc dịch vụ của Google của người dùng (như đọc bảng tính, gửi email hoặc tạo tệp trong Drive) đều phải được người dùng cấp quyền rõ ràng trước.

Lỗi Authorization required không phải là một lỗi trong mã của bạn, mà là một lời nhắc bảo mật. Nó báo hiệu rằng script của bạn đang cố gắng thực hiện một hành động thuộc một phạm vi OAuth cụ thể (một cấp độ quyền) mà người dùng hiện tại chưa cấp. Điều này thường xảy ra vì:

• Script đang được người dùng chạy lần đầu tiên.
• Bạn đã thêm chức năng mới vào script yêu cầu các quyền bổ sung (ví dụ: bạn đã thêm MailApp.sendEmail() vào một script trước đây chỉ truy cập bảng tính).
• Mã thông báo ủy quyền của script đã hết hạn hoặc bị thu hồi (ít phổ biến hơn, nhưng có thể xảy ra).
• Một tài khoản Google khác đã đăng nhập, hoặc tài khoản chính đã thay đổi.

Khắc phục nhanh: Cấp quyền ủy quyền ngay lập tức

Khi bạn gặp lỗi này vào lúc 2 giờ sáng, bạn cần một giải pháp nhanh chóng. Cách trực tiếp nhất để giải quyết vấn đề này là kích hoạt luồng ủy quyền theo cách thủ công.

• Chạy Script theo cách thủ công: Mở dự án Google Apps Script của bạn. Nếu nó được liên kết với một Google Sheet, bạn thường có thể chạy nó trực tiếp từ menu tùy chỉnh mà bạn đã tạo, hoặc bằng cách mở Trình chỉnh sửa Script (Extensions > Apps Script) và chạy bất kỳ chức năng nào từ thanh công cụ của trình chỉnh sửa (chọn một chức năng và nhấp vào biểu tượng "Run").

  Nếu đó là một script độc lập hoặc ứng dụng web, việc thực thi nó (ví dụ: làm mới URL ứng dụng web, chạy một chức năng từ trình chỉnh sửa) cũng sẽ kích hoạt lời nhắc.

• Tìm Hộp thoại ủy quyền: Một cửa sổ trình duyệt mới hoặc hộp thoại bật lên sẽ xuất hiện, hiển thị nội dung như "Authorization required" hoặc "Review Permissions."

  (Lưu ý: Hình ảnh thực tế có thể hơi khác một chút tùy thuộc vào các bản cập nhật giao diện người dùng của Google. Hình ảnh giữ chỗ là một đại diện phổ biến.)

• Nhấp vào "Review permissions": Thao tác này sẽ đưa bạn đến trang đăng nhập Google.

• Chọn Tài khoản Google của bạn: Chọn tài khoản Google mà bạn muốn script chạy dưới đó (và cấp quyền cho nó). Đảm bảo đó là tài khoản chính xác, đặc biệt nếu bạn quản lý nhiều hồ sơ Google.

• Xem lại và "Allow": Sau đó, bạn sẽ thấy một màn hình liệt kê tất cả các quyền mà script của bạn đang yêu cầu (ví dụ: "Xem, chỉnh sửa, tạo và xóa tất cả bảng tính Google Sheets của bạn", "Gửi email với tư cách của bạn"). Cẩn thận xem xét các quyền này để hiểu script của bạn sẽ có thể làm gì. Nếu mọi thứ đều chính xác, hãy nhấp vào nút "Allow".

Sau khi bạn đã cấp quyền, script sẽ thực thi thành công. Nếu bạn chia sẻ script với người khác, mỗi người dùng sẽ cần trải qua quá trình ủy quyền này lần đầu tiên họ chạy script.

Khắc phục vĩnh viễn / Phòng ngừa: Quản lý các phạm vi một cách hiệu quả

Mặc dù cách khắc phục nhanh giúp bạn thoát khỏi tình trạng mắc kẹt, nhưng việc hiểu và quản lý các phạm vi OAuth của script có thể ngăn chặn các lỗi ủy quyền này tái diễn, đặc biệt khi script của bạn phát triển hoặc được nhiều người sử dụng hơn.

1. Khai báo rõ ràng các phạm vi trong appsscript.json

Google Apps Script thường suy ra các phạm vi OAuth cần thiết từ các dịch vụ mà script của bạn sử dụng. Ví dụ: nếu bạn sử dụng SpreadsheetApp, nó sẽ ngầm yêu cầu https://www.googleapis.com/auth/spreadsheets. Tuy nhiên, tốt nhất nên khai báo rõ ràng các phạm vi cần thiết của bạn trong tệp manifest của script, appsscript.json. Điều này làm cho các quyền của script của bạn minh bạch và có thể giúp ngăn chặn các lời nhắc ủy quyền không mong muốn khi các phạm vi ngầm định mới được suy ra.

Cách truy cập và chỉnh sửa appsscript.json:

• Mở dự án Google Apps Script của bạn.
• Trong thanh bên trái, nhấp vào Project Settings ().
• Cuộn xuống và chọn hộp kiểm "Show "appsscript.json" manifest file in editor."
• Quay lại trình chỉnh sửa (biểu tượng mã trong thanh bên trái). Bây giờ bạn sẽ thấy appsscript.json được liệt kê.

Ví dụ appsscript.json với các phạm vi rõ ràng:

Thêm một mảng oauthScopes vào manifest của bạn, liệt kê tất cả các URL cho các quyền mà script của bạn cần. Một tập hợp phổ biến có thể trông như thế này:

{
  "timeZone": "America/New_York",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/gmail.send"
  ]
}

Trong ví dụ này:

• https://www.googleapis.com/auth/spreadsheets: Cho phép truy cập vào Google Sheets.
• https://www.googleapis.com/auth/script.container.ui: Cho phép script tạo các yếu tố giao diện người dùng (menu, hộp thoại) trong ứng dụng máy chủ.
• https://www.googleapis.com/auth/script.external_request: Cho phép script thực hiện các yêu cầu HTTP(S) đến các dịch vụ bên ngoài.
• https://www.googleapis.com/auth/gmail.send: Cho phép script gửi email bằng Gmail.

Bạn có thể tìm thấy danh sách đầy đủ các phạm vi có sẵn trong tài liệu Google API Scopes.

2. Giảm thiểu các quyền được yêu cầu

Luôn tuân theo nguyên tắc đặc quyền tối thiểu: chỉ yêu cầu các phạm vi mà script của bạn thực sự cần để hoạt động. Yêu cầu quá nhiều quyền có thể khiến người dùng ngần ngại cấp quyền truy cập, và nó cũng làm tăng diện tích bề mặt bảo mật của script của bạn.

3. Kiểm tra luồng ủy quyền sau khi thay đổi

Bất cứ khi nào bạn thêm các dịch vụ hoặc API mới vào script của mình, hãy tạo thói quen kiểm tra luồng ủy quyền. Chạy script và xác nhận rằng không có lời nhắc ủy quyền mới nào xuất hiện bất ngờ. Nếu có, hãy cập nhật oauthScopes trong appsscript.json của bạn cho phù hợp.

4. Giao tiếp rõ ràng với người dùng

Nếu script của bạn dành cho người khác, hãy đảm bảo họ hiểu rằng cần có một bước ủy quyền một lần. Cung cấp hướng dẫn rõ ràng, tương tự như các bước "Khắc phục nhanh" ở trên. Đối với các triển khai lớn hơn hoặc tiện ích bổ sung, hãy cân nhắc thêm hướng dẫn ủy quyền vào tài liệu của bạn.

Các bước xác minh

Sau khi bạn đã cấp các quyền cần thiết (thông qua cách khắc phục nhanh hoặc bằng cách cập nhật appsscript.json và chạy lại), hãy xác nhận rằng vấn đề đã được giải quyết hoàn toàn:

• Chạy lại Script: Thực thi script theo cách đã kích hoạt lỗi ban đầu.
• Kiểm tra thông báo lỗi: Đảm bảo không có hộp thoại ủy quyền hoặc thông báo lỗi nào xuất hiện lần này.
• Xác minh kết quả mong đợi: Xác nhận rằng script thực hiện hành động dự định của nó. Ví dụ: nếu nó được cho là cập nhật một bảng tính, hãy kiểm tra bảng tính. Nếu nó gửi email, hãy kiểm tra hộp thư đến/thư đã gửi của bạn.
• Xem lại nhật ký thực thi: Trong trình chỉnh sửa Apps Script, đi tới tab "Executions" (biểu tượng đồng hồ trong thanh bên trái) để xem script đã hoàn thành thành công mà không có lỗi hay không.

Mẹo và Thực hành tốt nhất

• Kiểm toán định kỳ: Định kỳ xem xét chức năng của script và oauthScopes đã khai báo của nó. Nếu bạn loại bỏ các tính năng yêu cầu các quyền cụ thể, hãy cân nhắc xóa các phạm vi đó khỏi manifest của bạn để duy trì nguyên tắc đặc quyền tối thiểu.
• Hiểu các phạm vi nhạy cảm: Lưu ý rằng một số phạm vi (ví dụ: những phạm vi cho phép truy cập vào email người dùng, tệp Drive hoặc dữ liệu lịch) được coi là nhạy cảm. Nếu bạn xuất bản một tiện ích bổ sung hoặc ứng dụng web sử dụng chúng, Google có thể yêu cầu một quy trình xác minh nghiêm ngặt hơn.
• Bộ công cụ nhà phát triển: Xử lý quyền trên các hệ thống khác nhau là một thách thức phổ biến của nhà phát triển. Mặc dù Google Apps Script có luồng OAuth độc đáo riêng, nhưng các nguyên tắc cơ bản về kiểm soát truy cập là phổ biến. Ví dụ, khi tôi làm việc với các script phía máy chủ hoặc hệ thống tệp, tôi thường cần nhanh chóng xác minh hoặc tính toán các quyền Unix. Đối với điều đó, tôi thấy các tiện ích dựa trên trình duyệt như Unix Permissions Calculator của ToolCraft cực kỳ hữu ích. Đây là một công cụ miễn phí, hoạt động hoàn toàn ở phía máy khách và giữ dữ liệu của bạn riêng tư, đây là một điểm cộng lớn khi bạn nhanh chóng kiểm tra các cấu hình nhạy cảm. Đó là một bổ sung tiện dụng cho bộ công cụ của bất kỳ nhà phát triển nào, ngay cả khi không trực tiếp cho Apps Script OAuth.

Bằng cách hiểu tại sao lỗi Authorization required xảy ra và quản lý cẩn thận các quyền của script của bạn, bạn có thể đảm bảo các dự án Google Apps Script của mình chạy trơn tru và an toàn.