RTU chủ yếu dành cho các nội dung cập nhật mà bạn không thể đoán trước được, chẳng hạn như việc đóng cửa khẩn cấp hoặc siêu dữ liệu thay đổi định kỳ (chẳng hạn như ETA). Nếu thay đổi của bạn chưa cần được phản ánh ngay lập tức, thì bạn có thể sử dụng tính năng nhập nguồn cấp dữ liệu hàng loạt. Bản cập nhật theo thời gian thực được xử lý trong không quá 5 phút.
Thiết lập Google Cloud Platform
- Thiết lập dự án GCP. Bạn cần có một dự án GCP để truy cập vào API RTU.
- Cấp quyền truy cập của người chỉnh sửa food-support@google.com
- Thông báo cho đầu mối liên hệ của Google về số dự án GCP.Dự án GCP của bạn phải được liên kết với tài khoản Actions Center thì các bản cập nhật theo thời gian thực mới có thể hoạt động.
- Bật API Đặt chỗ trên Maps:
- Trong GCP, hãy chuyển đến phần API và Dịch vụ > Thư viện.
- Tìm "API Đặt chỗ trên Google Maps".
- Tìm phiên bản Hộp cát (“API Đặt chỗ của Google Maps (Nhà phát triển)”) rồi nhấp vào Bật
- Tìm phiên bản chính thức (“API Đặt chỗ của Google Maps”) rồi nhấp vào Bật
- Tạo một tài khoản dịch vụ có vai trò người chỉnh sửa đối với dự án GCP của bạn. Để biết thêm thông tin, hãy xem phần Thiết lập tài khoản dịch vụ.
- Đảm bảo rằng bạn tải nguồn cấp dữ liệu hàng loạt lên môi trường mà bạn đang xử lý việc cập nhật theo thời gian thực.
- Để xác thực API, bạn nên cài đặt Thư viện ứng dụng Google bằng ngôn ngữ mà bạn chọn. Sử dụng “https://www.googleapis.com/auth/mapsbooking” làm phạm vi OAuth. Các mã mẫu bên dưới sử dụng các thư viện này. Nếu không, bạn sẽ cần xử lý các hoạt động đổi mã thông báo theo cách thủ công như mô tả trong bài viết Sử dụng OAuth 2.0 để truy cập các API của Google.
Thiết lập tài khoản dịch vụ
Bạn cần có một tài khoản dịch vụ để gửi các yêu cầu HTTPS đã xác thực tới các API của Google, chẳng hạn như API cập nhật theo thời gian thực.
Để thiết lập tài khoản dịch vụ, hãy làm như sau:
- Truy cập vào bảng điều khiển Google Cloud Platform.
- Tài khoản của bạn trên Actions Center cũng liên kết với một dự án trên Google Cloud. Chọn dự án đó nếu chưa chọn.
- Nhấp vào Tài khoản dịch vụ trên trình đơn bên trái.
- Nhấp vào Tạo tài khoản dịch vụ.
- Nhập tên cho tài khoản dịch vụ rồi nhấp vào Tạo.
- Đối với phần Chọn vai trò, hãy chọn Dự án > Trình chỉnh sửa.
- Nhấp vào Tiếp tục.
- Không bắt buộc: Thêm người dùng để cấp cho họ quyền truy cập vào tài khoản dịch vụ rồi nhấp vào Xong.
- Nhấp vào thêm > Tạo khoá cho tài khoản dịch vụ mà bạn vừa tạo.
- Chọn JSON làm định dạng rồi nhấp vào Create (Tạo).
- Sau khi cặp khoá công khai/riêng tư mới của bạn được tạo, hãy tải cặp khoá đó xuống máy của bạn.
Làm việc với API
API Cập nhật theo thời gian thực hỗ trợ 2 loại thao tác: Cập nhật và Xoá. Chưa hỗ trợ thêm các thực thể mới qua API cập nhật theo thời gian thực. Các bản cập nhật theo thời gian thực có thể được phân theo lô nếu bạn đưa nhiều nội dung cập nhật vào một yêu cầu API. Bạn có thể tạo nhóm tối đa 1.000 bản cập nhật trong một lệnh gọi API. Nếu có thể, bạn nên sử dụng phương pháp dựa trên điều kiện kích hoạt để gửi bản cập nhật qua RTU (tức là khi dữ liệu trong hệ thống của bạn thay đổi sẽ kích hoạt bản cập nhật theo thời gian thực) thay vì phương thức dựa trên tần suất (tức là cứ X phút một lần để quét tìm các thay đổi trên hệ thống của bạn).
API cập nhật theo thời gian thực hoạt động trong cả môi trường hộp cát và môi trường thực tế. Môi trường hộp cát được dùng để kiểm thử các yêu cầu API và môi trường sản xuất để cập nhật nội dung hiển thị cho người dùng đặt hàng hai đầu.
- Hộp cát –
partnerdev-mapsbooking.googleapis.com - Phát hành công khai –
mapsbooking.googleapis.com
Điểm cuối
API cập nhật theo thời gian thực cung cấp 2 điểm cuối để xử lý các yêu cầu cập nhật kho hàng được gửi đến:
- CẬP NHẬT –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - XÓA –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Bạn có thể tìm thấy tham số PARTNER_ID trong Trung tâm hành động trên trang Tài khoản và người dùng, như trong ảnh chụp màn hình dưới đây.
Trong ảnh chụp màn hình ở trên, nếu lấy 10000001 làm giá trị của PARTNER_ID, thì các URL hoàn chỉnh để gửi yêu cầu API trong hộp cát và phiên bản chính thức sẽ trông giống như trong các ví dụ dưới đây.
Cập nhật Sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
XOÁ Hộp cát
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Thông tin cập nhật về kênh phát hành công khai
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Xoá bản phát hành công khai
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Đang cập nhật thực thể
Để cập nhật các thực thể trong khoảng không quảng cáo của bạn, hãy sử dụng điểm cuối cập nhật trong yêu cầu POST qua HTTP. Mỗi yêu cầu POST phải bao gồm tham số 10000001 cùng với tải trọng JSON chứa thực thể bạn muốn cập nhật.
Lưu ý: Hãy đảm bảo nguồn cấp dữ liệu hằng ngày của bạn cũng chứa mọi nội dung thay đổi được gửi qua API nội dung cập nhật theo thời gian thực. Nếu không, dữ liệu của bạn có thể đã lỗi thời hoặc lỗi thời.
Cập nhật tải trọng của yêu cầu
Nội dung yêu cầu là một đối tượng JSON có một danh sách các bản ghi. Mỗi bản ghi tương ứng với một thực thể đang được cập nhật. Lớp này bao gồm trường proto_record và generation_timestamp cho biết thời gian cập nhật thực thể:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: Bản dịch proto hoặc JSON của thực thể ServiceData mà bạn đang cập nhật.UPDATE_TIMESTAMP: Nhớ thêm dấu thời gian về thời điểm tạo thực thể trong các hệ thống phụ trợ của bạn. Nếu bạn không thêm trường này, trường này sẽ được đặt thành thời điểm Google nhận được yêu cầu. Khi cập nhật một thực thể thông qua yêu cầubatchPush, trườnggeneration_timestampsẽ được dùng để tạo phiên bản thực thể. Xem định dạng dự kiến của giá trị thời gian trong giản đồ khoảng không quảng cáo quan hệ.
- Nội dung tải trọng có kích thước không được vượt quá 5 MB.
- Xoá khoảng trắng để giảm kích thước.
- Có thể có tới 1.000 nội dung cập nhật trong một yêu cầu
batchPush.
Ví dụ
Cập nhật thời gian đến dự kiến
Giả sử bạn khẩn cấp cần cập nhật thời gian đến dự kiến của một dịch vụ giao hàng từ 30-60 đến 60-90 phút. Bản cập nhật của bạn phải chứa JSON cho toàn bộ thực thể Dịch vụ.
Hãy xem xét một thực thể dịch vụ có dạng như sau:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
Nội dung cập nhật theo thời gian thực bằng HTTP POST như sau (nội dung yêu cầu được in đẹp để dễ đọc):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
Cập nhật nhiều thực thể
Để cập nhật nhiều thực thể nhà hàng trong một lệnh gọi API, hãy thêm nhiều bản ghi vào trường proto_record của nội dung yêu cầu.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
Xoá thực thể
Để xoá thực thể khỏi khoảng không quảng cáo của bạn, hãy sử dụng điểm cuối DELETE (XOÁ) trong yêu cầu POST qua HTTP. Mỗi yêu cầu POST phải bao gồm tham số PARTNER_ID cùng với tải trọng JSON chứa giá trị nhận dạng của thực thể bạn muốn xoá.
Lưu ý: Hãy đảm bảo nguồn cấp dữ liệu hằng ngày của bạn cũng chứa mọi nội dung thay đổi được gửi qua API cập nhật theo thời gian thực. Nếu không, quy trình nhập hàng loạt hằng ngày sẽ ghi đè những thay đổi theo thời gian thực.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
Thêm thực thể
Đừng sử dụng thông tin cập nhật theo thời gian thực để thêm thực thể mới vì điều này có thể dẫn đến những điểm không thống nhất của dữ liệu. Thay vào đó, hãy sử dụng nguồn cấp dữ liệu hàng loạt.
Xác thực và Mã phản hồi của API
Có hai loại xác thực được thực hiện đối với lệnh gọi API cập nhật theo thời gian thực:
- Cấp yêu cầu – Những quy trình xác thực này kiểm tra để đảm bảo tải trọng tuân thủ giản đồ và mỗi
proto_recordđều chứa một trườngidvàtype. Các quá trình kiểm tra này có tính đồng bộ và kết quả được trả về trong nội dung phản hồi của API. Mã phản hồi 200 và nội dung JSON trống{}có nghĩa là các quy trình xác thực này đã được thông qua và các thực thể trong yêu cầu đó đã được đưa vào hàng đợi xử lý. Mã phản hồi không phải 200 có nghĩa là một hoặc nhiều xác thực trong số này không thành công và toàn bộ yêu cầu bị từ chối (bao gồm tất cả các thực thể trong tải trọng). Ví dụ: nếuproto_recordthiếu@type, thì phản hồi lỗi sau đây sẽ được trả về:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- Cấp thực thể: Mỗi thực thể (proto_record) trong tải trọng được xác thực theo giản đồ. Các vấn đề gặp phải ở giai đoạn xác thực này không được báo cáo trong phản hồi của API. Các trường hợp này chỉ được báo cáo trong trang tổng quan Báo cáo RTU của Trung tâm hành động.
Lưu ý: Mã phản hồi 200 không có nghĩa là tất cả các thực thể đã được nhập thành công.
Hạn mức API
Các bản cập nhật API theo thời gian thực có hạn mức 1.500 yêu cầu mỗi 60 giây hoặc trung bình 25 yêu cầu mỗi giây. Khi vượt quá hạn mức, Google sẽ phản hồi bằng thông báo lỗi sau:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Để xử lý vấn đề này, hãy thử gọi lại với khoảng thời gian lớn hơn theo cấp số nhân cho đến khi thành công. Nếu bạn thường xuyên sử dụng hết hạn mức, hãy cân nhắc thêm nhiều thực thể hơn vào một yêu cầu API. Bạn có thể đưa tối đa 1.000 thực thể vào một lệnh gọi API.
Thông tin cập nhật theo thời gian thực về thời gian xử lý
Một thực thể được cập nhật thông qua quá trình cập nhật theo thời gian thực sẽ được xử lý trong 5 phút.