Như mô tả trong phần Khai báo thao tác, khi người dùng tương tác với một hành động trong ứng dụng, Google sẽ gửi một yêu cầu HTTP đến một URL được khai báo trong thao tác đó.
Ví dụ sau đây thêm nút ConfirmAction vào một email về báo cáo chi phí:
JSON-LD
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ConfirmAction",
"name": "Approve Expense",
"handler": {
"@type": "HttpActionHandler",
"url": "https://myexpenses.com/approve?expenseId=abc123"
}
},
"description": "Approval request for John's $10.13 expense for office supplies"
}
</script>
Vi dữ liệu
<div itemscope itemtype="http://schema.org/EmailMessage">
<div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
<meta itemprop="name" content="Approve Expense"/>
<div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
<link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
</div>
</div>
<meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>
Khi người dùng nhấp vào nút này, một yêu cầu HTTP sẽ được Google gửi đến dịch vụ của bạn để ghi lại thông tin xác nhận. Dịch vụ của bạn sẽ nhận được yêu cầu HTTP sau đây từ Google:
POST /approve?expenseId=abc123 HTTP/1.1
Host: your-domain.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)
confirmed=Approved
Phần còn lại của trang này mô tả những việc mà dịch vụ tại https://your-domain.com/approve?expenseId=abc123 cần làm để xử lý thao tác đúng cách. Nội dung như vậy bao gồm:
- Xác minh yêu cầu
- Xử lý tải trọng
- Trả về mã phản hồi
Bước 1: Xác minh yêu cầu
Bạn nên kiểm tra dịch vụ tại https://your-domain.com/approve?expenseId=abc123:
- Mã truy cập sử dụng có giới hạn – Để bảo vệ khỏi các cuộc tấn công phát lại.
- Tác nhân người dùng – Để đảm bảo yêu cầu đến từ Google.
- Mã thông báo Bearer – Để đảm bảo yêu cầu đến từ Google là dành cho dịch vụ.
Tác nhân người dùng cho tất cả các yêu cầu Thao tác là Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).
Nếu tất cả các bước kiểm tra đều thành công, thì dịch vụ có thể chuyển sang bước tiếp theo.
Bước 2: Xử lý thao tác
Dịch vụ phải xử lý thao tác như được chỉ định trong các tham số URL cũng như thông tin bổ sung được thu thập từ người dùng.
Thông tin bổ sung từ người dùng nằm trong nội dung của yêu cầu và được mã hoá bằng cách mã hoá x-www-form-urlecoded. Thông tin được đặt trong các thuộc tính có tên tương ứng với các thuộc tính của Thao tác. Ví dụ: ConfirmAction có thuộc tính confirmed.
Bước 3: Trả về mã phản hồi
Sau khi xử lý và ghi lại thao tác thành công, dịch vụ sẽ trả về mã phản hồi 200 (OK). Bạn có thể sử dụng các mã phản hồi sau đây trong trường hợp xảy ra lỗi:
| Mã phản hồi | Xử lý |
|---|---|
| 400 (Yêu cầu không hợp lệ) | Google sẽ không thực hiện được thao tác. |
| 401 (Không được phép) | Google sẽ không thực hiện được thao tác. |
| 404 (Không tìm thấy) | Google sẽ không thực hiện được thao tác. |
| 408 (Yêu cầu hết thời gian chờ) | Google sẽ thử lại sau. |
Trong trường hợp lỗi vĩnh viễn, Google sẽ thông báo cho người dùng rằng thao tác không thành công và người dùng nên làm theo hướng dẫn thay thế trong email.