1. Giới thiệu
Hàng tỷ doanh nghiệp và cá nhân sử dụng Gmail và các dịch vụ khác của G Suite để giao tiếp và xử lý dữ liệu. Google cung cấp các API G Suite để giúp bạn truy cập thông tin trong các dịch vụ này theo phương thức lập trình, đồng thời bạn có thể sử dụng các API này để dễ dàng tự động hoá quy trình làm việc hằng ngày. Trong phòng thí nghiệm này, bạn sẽ tạo một tiện ích mạnh mẽ cho Gmail, tiện ích này sẽ tự động phân loại email trong thư đến và lưu các danh mục đó vào một trang tính trên Google. Tiện ích này sẽ sử dụng các API RESTful của G Suite, Google Cloud Functions và các dịch vụ khác của Google Cloud Platform.
Sản phẩm bạn sẽ tạo ra
Trong phòng thí nghiệm này, bạn sẽ tạo và triển khai một số Cloud Functions được kết nối với API G Suite và các dịch vụ khác của Google Cloud Platform. Các hàm này sẽ:
- Cho phép truy cập an toàn vào dữ liệu của bạn trên Gmail và Google Trang tính
- Trích xuất hình ảnh được đính kèm vào mọi thư đến
- Phân loại những hình ảnh đó bằng Cloud Vision API
- Viết các danh mục đó, địa chỉ của người gửi và tên của tệp đính kèm vào một tệp Google Trang tính
Kiến thức bạn sẽ học được
- Kiến thức cơ bản về API RESTful của G Suite
- Kiến thức cơ bản về Google Cloud Functions và các dịch vụ khác của Google Cloud Platform
- Cách truy cập vào Gmail theo phương thức lập trình bằng Google Cloud Functions
Bạn cần có
- Tài khoản Google có quyền truy cập vào Gmail và Google Trang tính. Nếu chưa có, hãy tạo một tài khoản tại đây.
- Kiến thức cơ bản về Javascript/Node.js.
2. Trước tiên
Bật các API
Trong phòng thí nghiệm này, bạn sẽ sử dụng các sản phẩm/dịch vụ sau đây của Google:
- Google Cloud Functions
- Google Cloud Pub/Sub
- Google Cloud Vision API
- Google Cloud Datastore
- API Gmail
- API Google Trang tính
Google Cloud Functions
Google Cloud Functions là nền tảng Functions-as-a-Service (Hàm dưới dạng dịch vụ) không cần máy chủ của Google, cho phép bạn chạy các đoạn mã riêng lẻ ("hàm") theo cách đơn giản và có thể mở rộng.
Để bật Google Cloud Functions, hãy nhấp vào trình đơn ba đường kẻ ở trên cùng bên trái màn hình để mở thanh điều hướng bên trái:
Tìm Cloud Functions trong trình đơn điều hướng rồi nhấp vào đó. Nhấp vào Bật API để bật Google Cloud Functions trong dự án của bạn.
Google Cloud Pub/Sub
Google Cloud Pub/Sub là một nền tảng đơn giản và có khả năng mở rộng để truyền phát dữ liệu và phân phối sự kiện. Trong phòng thí nghiệm này, nó đóng vai trò là người chuyển phát giữa Gmail và Google Cloud Functions.
Để bật Google Cloud Pub/Sub, hãy mở thanh bên điều hướng bên trái, tìm Pub/Sub rồi nhấp vào đó. Nhấp vào Bật API để bật Google Cloud Pub/Sub trong dự án của bạn.
Google Cloud Datastore
Google Cloud Datastore là một cơ sở dữ liệu không máy chủ, có thể mở rộng và phân tán.
Để bật Google Cloud Datastore, trong thanh điều hướng bên trái, hãy tìm Datastore rồi nhấp vào đó. Nhấp vào Chọn chế độ kho dữ liệu trong trang mới.
Bạn có thể sử dụng bất kỳ vị trí cơ sở dữ liệu nào cho phòng thí nghiệm này. Nhấp vào Tạo cơ sở dữ liệu để bật Google Cloud Datastore; quá trình này có thể mất vài phút để hoàn tất.
Google Cloud Vision
Google Cloud Vision API là một dịch vụ học máy mạnh mẽ sử dụng các mô hình được huấn luyện trước để lấy thông tin chi tiết từ hình ảnh của bạn.
Hãy xem hướng dẫn bên dưới để biết thông tin về cách bật Google Cloud Vision API.
Bật API Gmail, API Google Trang tính và Cloud Vision API
Một lần nữa, hãy mở thanh điều hướng bên trái và tìm API và dịch vụ. Nhấp vào Thư viện. Trong trường Tìm kiếm API và dịch vụ, hãy nhập Gmail. Trong kết quả tìm kiếm, hãy chọn Gmail API rồi nhấp vào Bật.
Quay lại trang Thư viện API. Tìm API Google Trang tính rồi bật API này.
Lặp lại quy trình. Tìm Cloud Vision API rồi bật API này.
Mở Google Cloud Shell
Trong phòng thí nghiệm này, bạn sẽ sử dụng Google Cloud Shell để thực hiện hầu hết các thao tác. Cloud Shell cung cấp cho bạn quyền truy cập dòng lệnh vào các tài nguyên trên Google Cloud Platform ngay từ trình duyệt, cho phép bạn quản lý các tài nguyên đó mà không cần dùng máy cục bộ.
Để mở Google Cloud Shell, hãy nhấp vào nút Kích hoạt Cloud Shell trên thanh ngang màu xanh dương ở trên cùng:
Một bảng điều khiển mới sẽ xuất hiện ở cuối màn hình:
Nhấp vào nút Khởi chạy trình soạn thảo mã để bắt đầu Trình soạn thảo mã Cloud Shell:
Cloud Shell Code Editor sẽ mở ra trong một cửa sổ mới.
Tải mã xuống
Chạy lệnh bên dưới trong Cloud Shell để sao chép dự án:
git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git cd gcf-gmail-codelab
Bạn sẽ thấy một thư mục mới, gcf-gmail-codelab, xuất hiện trong Cloud Shell Code Editor.
3. Tổng quan về kiến trúc
Sau đây là quy trình thực hiện trong phòng thí nghiệm này:
- Người dùng thiết lập thông báo đẩy của Gmail: mỗi khi có thư mới đến hộp thư đến, Gmail sẽ gửi thông báo đến Cloud Pub/Sub.
- Cloud Pub/Sub gửi thông báo về tin nhắn mới đến Google Cloud Functions.
- Khi nhận được thông báo về thư mới, một phiên bản Cloud Functions sẽ kết nối với Gmail và truy xuất thư mới.
- Nếu thư có hình ảnh dưới dạng tệp đính kèm, thì phiên bản Cloud Functions sẽ gọi Cloud Vision API để phân tích tệp đính kèm.
- Phiên bản Cloud Functions sẽ cập nhật một Google Trang tính mà bạn chọn, cho biết người gửi tin nhắn và nơi tải tệp đính kèm xuống.
4. Cho phép truy cập vào Gmail
Trước khi thiết lập một Cloud Function để tự động đọc email, bạn phải cho phép Cloud Function truy cập vào Gmail. Bạn sẽ cần đăng ký một Ứng dụng OAuth với Google và tạo một mã ứng dụng khách liên kết.
Đăng ký ứng dụng OAuth
Trong trình đơn điều hướng bên trái của Google Cloud Console, hãy tìm API và dịch vụ. Nhấp vào màn hình xin phép bằng OAuth.
Nhập tên vào trường Application name (Tên ứng dụng), chẳng hạn như GCF + Gmail Codelab. Giữ nguyên các chế độ cài đặt khác, di chuyển xuống cuối trang rồi nhấp vào Lưu.
Tạo mã ứng dụng khách được liên kết
Chuyển sang thẻ Credentials (Thông tin xác thực). Nhấp vào Tạo thông tin xác thực rồi chọn Mã ứng dụng khách OAuth. Chọn loại Ứng dụng web, đặt tên cho ứng dụng (bạn có thể sử dụng lại GCF + Lớp học lập trình Gmail tại đây) rồi nhấp vào Tạo. Hiện tại, hãy để trống các trường Giới hạn.
Ghi lại mã ứng dụng khách và mật khẩu ứng dụng khách xuất hiện trong cửa sổ bật lên. Bạn có thể nhấp vào tên khách hàng trên trang để xem lại các giá trị này:
Thực hiện quy trình uỷ quyền
Trong mã mẫu, auth/index.js chỉ định 2 Cloud Functions (auth_init và auth_callback) hoạt động cùng nhau để thực hiện quy trình uỷ quyền, bằng cách sử dụng mã ứng dụng khách và mật khẩu ứng dụng khách mà bạn vừa tạo.
Để kiểm tra mã, hãy mở auth/index.js trong Trình chỉnh sửa mã Cloud Shell.
Quy trình uỷ quyền trả về 2 loại mã thông báo: mã truy cập và mã làm mới.
- Mã truy cập là bằng chứng nhận dạng có thời hạn ngắn, cấp cho bất kỳ ai có mã này quyền truy cập có phạm vi vào dữ liệu của bạn;
auth_callbacklưu mã truy cập trong Cloud Datastore. - Mã làm mới được dùng để lấy mã truy cập mới và có thời gian tồn tại dài hơn đáng kể.
Thông thường, các mã này được mã hoá và/hoặc lưu trữ riêng biệt với mã truy cập.
Chỉnh sửa auth/env_vars.yaml trong Trình chỉnh sửa mã Cloud Shell. Thay thế YOUR-GOOGLE-CLIENT-ID và YOUR-GOOGLE-CLIENT-SECRET bằng các giá trị của riêng bạn. Hãy xem bước trước đó để biết thêm thông tin. Hiện tại, bạn cứ để nguyên giá trị của YOUR-GOOGLE-CLIENT-CALLBACK-URL và YOUR-PUBSUB-TOPIC.
Sau khi chỉnh sửa auth/env_vars.yaml, hãy chạy lệnh sau trong Cloud Shell để triển khai Cloud Functions:
cd ~ cd gcf-gmail-codelab/auth # Deploy Cloud Function auth_init gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml # Deploy Cloud Function auth_callback gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml
Có thể mất vài phút để triển khai Cloud Functions. Nếu được nhắc, hãy cấp cho Cloud SDK quyền cài đặt các lệnh beta.
Tiếp theo, hãy chuyển đến Google Cloud Console rồi nhấp vào Cloud Functions trong trình đơn điều hướng bên trái. Nhấp vào auth_callback trong danh sách Cloud Functions rồi chuyển sang thẻ Trình kích hoạt.
Sao chép URL trên trang. Quay lại trang Cloud Functions, nhấp vào auth_init trong danh sách Cloud Functions. Trong thẻ Chung, hãy nhấp vào Chỉnh sửa. Nhấp vào Environmental variables, networking, timeouts and more (Biến môi trường, mạng, thời gian chờ và các thông tin khác), rồi thay thế giá trị của GOOGLE_CALLBACK_URL bằng URL bạn vừa sao chép.
Nhấp vào Triển khai để áp dụng các thay đổi. Lặp lại quy trình này và cập nhật cả auth_callback.
Cuối cùng, hãy mở trình đơn điều hướng bên trái rồi nhấp vào API và dịch vụ > Xác minh miền. Để thêm một miền được uỷ quyền, hãy nhấp vào Thêm miền. Ví dụ: Nếu URL bạn đã sao chép trước đó có dạng
https://us-central1-my-project.cloudfunctions.net/auth_callback
Bạn nên thêm những miền sau làm miền được uỷ quyền:
us-central1-my-project.cloudfunctions.net
Nhấn vào Thêm miền để xác nhận.
Quay lại trang Thông tin đăng nhập. Nhấp vào tên ứng dụng OAuth của bạn rồi thêm URL mà bạn đã sao chép làm URI chuyển hướng được uỷ quyền. Nhấn phím Enter để xác nhận.
Xoá phần /auth_callback khỏi URL và thêm phần còn lại làm Gốc JavaScript được phép. Ví dụ: nếu URL của bạn có dạng
https://us-central1-my-project.cloudfunctions.net/auth_callback
Bạn nên thêm những thông tin sau làm nguồn gốc:
https://us-central1-my-project.cloudfunctions.net/
Nhấn phím Enter để xác nhận và nhấp vào Lưu để áp dụng các thay đổi.
5. Thiết lập thông báo đẩy của Gmail
Nếu quá trình uỷ quyền thành công, auth_callback sẽ tự động gọi Gmail API để thiết lập thông báo đẩy.
Để nhận thông báo đẩy của Gmail, bạn phải tạo một chủ đề Pub/Sub. Mọi người đăng ký theo dõi chủ đề sẽ tự động nhận được thông báo về tin nhắn đến khi tin nhắn đó được gửi từ Gmail.
Để tạo một chủ đề Pub/Sub, hãy truy cập vào Google Cloud Console rồi nhấp vào Pub/Sub > Chủ đề trong trình đơn điều hướng bên trái. Nhấp vào Tạo chủ đề. Nhập tên của chủ đề, chẳng hạn như gmail-watch, rồi nhấp vào Tạo. Ngoài ra, bạn phải cấp cho Gmail quyền gửi thư đến chủ đề Pub/Sub của bạn: nhấp vào trình đơn theo bối cảnh của chủ đề mà bạn vừa tạo (ba dấu chấm dọc) rồi chọn Quyền; nhấp vào Thêm thành viên, chỉ định gmail-api-push@system.gserviceaccount.com làm thành viên mới và cấp cho thành viên này vai trò Pub/Sub > Pub/Sub Publisher; cuối cùng, nhấp vào Lưu để áp dụng các thay đổi.
Cập nhật Cloud Function auth_callback để chỉ định chủ đề Pub/Sub cần sử dụng. Nhấp vào Cloud Functions trong trình đơn điều hướng bên trái, rồi chọn auth_callback trong danh sách Cloud Functions. Trong thẻ Chung, hãy nhấp vào Chỉnh sửa. Nhấp vào Tuỳ chọn khác rồi thay thế giá trị của PUBSUB_TOPIC bằng tên của chủ đề Pub/Sub mà bạn vừa tạo. Nhấp vào Lưu để áp dụng các thay đổi.
Giờ đây, bạn đã sẵn sàng uỷ quyền và thiết lập thông báo đẩy của Gmail. Đợi cho đến khi các thay đổi mới hoàn tất, sau đó quay lại trang Cloud Functions, chọn auth_init trong danh sách Cloud Functions rồi chuyển sang thẻ Trigger (Trình kích hoạt). Nhấp vào URL đó, bạn sẽ được chuyển hướng đến trang Đăng nhập bằng Google:
Đăng nhập bằng một Tài khoản Gmail mà bạn sở hữu. Mọi thư mới đến hộp thư đến của tài khoản sẽ kích hoạt một thông báo đẩy. Sau khi đăng nhập, bạn sẽ thấy trang bên dưới:
Nhấp vào Cho phép để uỷ quyền truy cập. auth_callback sẽ hoàn tất quy trình uỷ quyền, lưu mã truy cập và thiết lập thông báo đẩy của Gmail cho bạn. Bạn sẽ thấy thông báo Successfully set up Gmail push notifications trong trình duyệt khi quá trình này hoàn tất.
Lớp học lập trình này sử dụng gói @google-cloud/express-oauth2-handlers để tự động hoá quy trình uỷ quyền cho bạn. Để biết thêm thông tin, hãy xem kho lưu trữ của nó trên GitHub.
6. Xử lý tin nhắn đến
Như đã đề cập trước đó, mọi người đăng ký chủ đề Pub/Sub mà bạn đã tạo sẽ nhận được thông báo khi có tin nhắn mới trong hộp thư đến của bạn. pubsub/index.js chỉ định một Cloud Function (Hàm trên đám mây), watchGmailMessages. Sau khi được triển khai dưới dạng một người đăng ký cho chủ đề, hàm này sẽ đọc các thông báo mới, phân loại hình ảnh được đính kèm và xuất các danh mục đó sang một Google Trang tính.
Để kiểm tra mã, hãy mở pubsub/index.js trong Trình chỉnh sửa mã Cloud Shell.
Truy xuất tin nhắn
Thông báo đẩy của Gmail bao gồm địa chỉ email được liên kết với thông báo và mã nhận dạng nhật ký. Để đơn giản, trong lớp học lập trình này, bạn chỉ cần yêu cầu API Gmail cung cấp tin nhắn mới nhất khi nhận được thông báo đẩy; để có kết quả tốt hơn, hãy sử dụng mã nhận dạng nhật ký để tra cứu tin nhắn.
// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
userId: email,
maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;
// Get the message using the message ID.
const message = await gmail.users.messages.get({
userId: email,
id: messageId
});
return message;
Phân tích tệp đính kèm hình ảnh
Nếu tin nhắn có tệp hình ảnh đính kèm, watchGmailMessages sẽ gọi Cloud Vision API để chú thích hình ảnh. Trong lớp học lập trình này, bạn sẽ yêu cầu Cloud Vision API phân loại hình ảnh và trả về một số thẻ hình ảnh; ví dụ: nếu bạn cung cấp hình ảnh bầu trời xanh, Cloud Vision API có thể trả về các thẻ xanh dương, bầu trời và thiên nhiên.
watchGmailMessages sử dụng Thư viện Cloud Vision API cho Node.js để gọi Cloud Vision API:
// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
var topLabels = ['', '', ''];
if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
const [analysis] = await visionClient.labelDetection({
image: {
content: Buffer.from(data, 'base64')
}
});
const labels = analysis.labelAnnotations;
topLabels = labels.map(x => x.description).slice(0, 3);
}
return topLabels;
};
Cập nhật Google Trang tính
watchGmailMessages xuất kết quả của bản phân tích này sang Google Trang tính. Thông tin này bao gồm tên người gửi, tên tệp đính kèm và thẻ của tệp đính kèm hình ảnh (nếu có).
Trước tiên, hãy tạo một Google Trang tính. Mở Google Trang tính rồi nhấp vào mẫu Trống trong mục Bắt đầu bảng tính mới. Sao chép mã nhận dạng của trang tính. Ví dụ: nếu địa chỉ trong trình duyệt của bạn có dạng như sau:
https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0
Mã bảng tính của bạn là abcdefghij01234567890. Trong Cloud Shell Code Editor, hãy cập nhật gcf-gmail-codelab/pubsub/env_vars.yaml và thay thế YOUR-GOOGLE-SHEET-ID bằng giá trị của riêng bạn.
watchGmailMessages kết nối với API Google Trang tính để thêm thông tin:
const updateReferenceSheet = async (from, filename, topLabels) => {
await googleSheets.spreadsheets.values.append({
spreadsheetId: SHEET,
range: SHEET_RANGE,
valueInputOption: 'USER_ENTERED',
requestBody: {
range: SHEET_RANGE,
majorDimension: 'ROWS',
values: [
[from, filename].concat(topLabels)
]
}
});
};
Một bước cuối cùng
Trong Cloud Shell Code Editor, hãy mở gcf-gmail-codelab/pubsub/env_vars.yaml rồi thay thế YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET và YOUR-GOOGLE-CALLBACK-URL bằng các giá trị của riêng bạn. Bạn có thể tìm thấy các giá trị này trong Google Cloud Console: mở Cloud Functions trong trình đơn điều hướng bên trái, chọn auth_init trong danh sách Cloud Functions và tìm mục Biến môi trường.
Triển khai mã
Chạy lệnh bên dưới để triển khai Cloud Function:
cd ~ cd gcf-gmail-codelab/pubsub gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml
Nếu bạn đặt tên cho chủ đề Cloud Pub/Sub khác với gmail-watch, hãy thay thế gmail-watch trong lệnh trên bằng tên chủ đề của bạn. Có thể mất vài giây để triển khai Cloud Functions.
7. Dùng thử
Xin chúc mừng, bạn đã hoàn tất! Tự gửi email cho mình kèm theo một tệp đính kèm là hình ảnh. Sau vài giây, bạn sẽ thấy Google Trang tính mà bạn tạo tự động cập nhật thông tin bạn cung cấp.