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. 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 của mình. Trong phòng thí nghiệm này, bạn sẽ xây dựng một tiện ích Gmail mạnh mẽ. Tiện ích này tự động phân loại email trong các thư đến và lưu các danh mục đó vào một Google Trang tính. Tiện ích này sẽ sử dụng 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ẽ xây dựng và triển khai một số Chức năng đám mây đượ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 Gmail và Google Trang tính của bạn
- Trích xuất hình ảnh đính kèm vào bất kỳ thư đến nào
- Phân loại các hình ảnh đó bằng Cloud Vision API
- Viết các danh mục đó, địa chỉ người gửi và tên của tệp đính kèm vào 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
- Thông tin 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 Gmail theo cách lập trình bằng Chức năng đám mây của Google
Bạn cần có
- Một Tài khoản Google có quyền truy cập vào Gmail và Google Trang tính. Nếu bạn chưa có tài khoản, 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 của Google:
- Chức năng đám mây của Google
- Google Cloud Pub/Sub
- Google Cloud Vision API
- Kho dữ liệu đám mây của Google
- API Gmail
- API Google Trang tính
Chức năng đám mây của Google
Google Cloud Functions là nền tảng Chức năng dưới dạng dịch vụ không máy chủ của Google, cho phép bạn chạy từng đoạn mã ("functions") 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 của màn hình để mở thanh bên đ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 Enable API (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ó thể mở rộng để truyền dữ liệu và phân phối sự kiện. Trong phòng thí nghiệm này, ứng dụng này đóng vai trò là kênh chuyển 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.
Kho dữ liệu đám mây của Google
Google Cloud Datastore là một cơ sở dữ liệu không máy chủ, có thể mở rộng và phân phối.
Để bật Google Cloud Datastore, trong thanh bên điều hướng bên trái, hãy tìm Datastore (Kho dữ liệu) rồi nhấp vào đó. Nhấp vào Select Datastore Mode (Chọn chế độ kho dữ liệu) trên 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 Create Database (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.
Tầm nhìn của Google Cloud
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à Google Cloud Vision API
Một lần nữa, hãy mở thanh bên điều hướng bên trái và tìm API và Dịch vụ. Nhấp vào Thư viện. Trong ô Tìm kiếm API & Dịch vụ, nhập Gmail. Trong kết quả tìm kiếm, hãy chọn API Gmail rồi nhấp vào Bật.
Quay lại trang Thư viện API. Tìm Google Trang tính API rồi bật API này.
Lặp lại quy trình. Tìm Cloud Vision API rồi bật dịch vụ 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 của Google Cloud Platform ngay từ trình duyệt để bạn quản lý chúng mà không cần sử 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ã để khởi động Trình soạn thảo mã Cloud Shell:
Trình soạn thảo mã Cloud Shell sẽ mở trong 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 là gcf-gmail-codelab xuất hiện trong Cloud Shell Code Editor.
3. Tổng quan về kiến trúc
Dưới đây là quy trình làm việc của 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 vào 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 tin nhắn mới đến Google Cloud Functions.
- Khi nhận được thông báo mới, một thực thể 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, phiên bản Cloud Functions sẽ gọi Cloud Vision API để phân tích tệp đính kèm.
- Thực thể Cloud Functions sẽ cập nhật một tệp Google Trang tính mà bạn chọn, trong đó chỉ định 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 Chức năng đám mây để tự động đọc email của bạn, bạn phải cho phép chức năng này truy cập vào Gmail. Bạn sẽ cần đăng ký ứng dụng OAuth với Google rồi tạo một mã ứng dụng khách liên kết.
Đăng ký một ứ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 mục API và Dịch vụ. Nhấp vào Màn hình xin phép bằng ứng dụ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 (Lớp học lập trình về GCF + Gmail). Giữ nguyên các chế độ cài đặt khác, di chuyển xuống phía dưới của trang rồi nhấp vào Lưu.
Tạo một 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 loại (bạn có thể sử dụng lại Lớp học lập trình GCF + Gmail tại đây) rồi nhấp vào Tạo. Hiện tại, hãy để trống các trường Hạn chế.
Ghi lại mã ứng dụng khách và mật khẩu ứng dụng khách được trả về trong cửa sổ bật lên. Bạn có thể nhấp vào tên của ứng dụng trên trang này để 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 hai Hàm đám mây, auth_init và auth_callback, phối hợp hoạt động để thực hiện quá trình cấp phép, bằng cách sử dụng ID ứng dụng khách và mật khẩu ứng dụng khách bạn vừa tạo.
Để kiểm tra mã, hãy mở auth/index.js trong Cloud Shell Code Editor.
Quy trình uỷ quyền sẽ 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 ngắn hạn về danh tính, cấp cho bất kỳ ai sở hữu chúng quyền truy cập trong phạm vi vào dữ liệu của bạn;
auth_callbacksẽ lưu các tệ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 lâu 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 soạn thảo 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. Bây giờ, hãy giữ nguyên các 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 lệnh beta.
Tiếp theo, hãy truy cập 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 và 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 Biến môi trường, kết nối mạng, thời gian chờ, v.v. 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 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 & 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 mà bạn đã sao chép trước đó trông giống như
https://us-central1-my-project.cloudfunctions.net/auth_callback
Bạn nên thêm các miền sau dưới dạng 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 xác thực. Nhấp vào tên của ứng dụng OAuth rồi thêm URL mà bạn đã sao chép dưới dạng URI chuyển hướng được phép. Nhấn Enter để xác nhận.
Hãy xoá phần /auth_callback khỏi URL rồi thêm phần còn lại dưới dạng Nguồn gốc JavaScript được uỷ quyền. 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 đoạn mã sau làm nguồn gốc:
https://us-central1-my-project.cloudfunctions.net/
Nhấn 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 trong Gmail
Nếu quá trình uỷ quyền thành công, auth_callback sẽ tự động gọi API Gmail để 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. Bất kỳ người đăng ký chủ đề nào cũng sẽ tự động nhận được thông báo về tin nhắn đến khi họ đến từ Gmail.
Để tạo một chủ đề Pub/Sub, hãy truy cập 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 chủ đề (ví dụ: 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ủ đề 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à chỉ định vai trò Pub/Sub > Nhà xuất bản Pub/Sub; cuối cùng, nhấp vào Lưu để áp dụng các thay đổi.
Cập nhật Hàm đám mây auth_callback để chỉ định chủ đề Pub/Sub sẽ 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 More (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.
Bây giờ, bạn đã sẵn sàng cho phép và thiết lập thông báo đẩy của Gmail. Hãy đợ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 và 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 tài khoản Gmail mà bạn sở hữu. Bất kỳ tin nhắn mới nào đến hộp thư đến của tài khoản đều sẽ kích hoạ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 để cấp quyền truy cập. auth_callback sẽ hoàn tất quá trình uỷ quyền, lưu mã truy cập và thiết lập thông báo đẩy trong Gmail cho bạn. Bạn sẽ thấy thông báo Successfully set up Gmail push notifications trên 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 ứng dụng trên GitHub.
6. Xử lý tin nhắn đến
Như chúng tôi đã đề cập trước đó, bất kỳ 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 Chức năng đám mây watchGmailMessages. Sau khi được triển khai làm người đăng ký chủ đề, chức năng này sẽ đọc các tin nhắn mới, phân loại hình ảnh đính kèm và xuất các danh mục đó sang một tệp Google Trang tính.
Để kiểm tra mã, hãy mở pubsub/index.js trong Cloud Shell Code Editor.
Đang truy xuất thông báo
Thông báo đẩy của Gmail bao gồm địa chỉ email liên kết với thông báo và mã lịch sử. Để đơn giản hoá, 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 thông báo mới nhất khi có thông báo đẩy; để có kết quả tốt hơn, hãy sử dụng ID lịch sử để 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 đính kèm hình ảnh, 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 cung cấp hình ảnh bầu trời xanh, thì API Cloud Vision có thể trả về các thẻ màu 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 một tệp Google Trang tính. Thư này bao gồm tên người gửi, tên của 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 tệp 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 trang tính. Ví dụ: nếu địa chỉ trong trình duyệt của bạn trông giố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)
]
}
});
};
Chỉ còn một bước cuối cùng
Trong Trình soạn thảo mã Cloud Shell, 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 rồi 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 Hàm đám mây:
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ủ đề trên Cloud Pub/Sub không phải là 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 Chức năng đám mây.
7. Dùng thử
Xin chúc mừng, bạn đã hoàn tất! Gửi email có đính kèm hình ảnh cho chính bạn. 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 cùng với thông tin bạn cung cấp.