RTU chủ yếu dành cho các nội dung cập nhật mà bạn không thể biết trước, chẳng hạn như tình trạng đó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 nội dung thay đổi không cần được phản ánh ngay lập tức, bạn có thể sử dụng phương thức nhập nguồn cấp dữ liệu hàng loạt. Nội dung cập nhật theo thời gian thực sẽ được xử lý trong vòng không quá 5 phút.
Thiết lập Google Cloud Platform
- Thiết lập một dự án GCP. Bạn cần có 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.Bạn phải liên kết dự án GCP với tài khoản Trung tâm hành động để nội dung cập nhật theo thời gian thực hoạt động.
- Bật Maps Booking API:
- Trong GCP, hãy chuyển đế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ỗ Google Maps (Nhà phát triển)") rồi nhấp vào Bật
- Tìm phiên bản phát hành công khai ("API Đặt chỗ trên 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. Để biết thêm thông tin, hãy xem bài viết Thiết lập tài khoản dịch vụ.
- Hãy nhớ 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ý các bản 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 của Google bằng ngôn ngữ bạn chọn. Sử dụng “https://www.googleapis.com/auth/mapsbooking” làm phạm vi OAuth. Các mã mẫu dưới đây sử dụng các thư viện này. Nếu không, bạn sẽ cần phải xử lý các hoạt động trao đổ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 API Google.
Thiết lập tài khoản dịch vụ
Bạn cần có tài khoản dịch vụ để gửi các yêu cầu HTTPS đã xác thực đến 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 có một dự án Google Cloud liên kết với tài khoản đó. Chọn dự án đó (nếu chưa chọn).
- Nhấp vào Tài khoản dịch vụ trong 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 > Người 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 biểu tượng thêm > Tạo khoá cho tài khoản dịch vụ bạn vừa tạo.
- Chọn JSON làm định dạng rồi nhấp vào Tạo.
- Sau khi cặp khoá công khai/riêng tư mới đượ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ợ hai loại thao tác: Cập nhật và Xoá. Không hỗ trợ thêm 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 thành lô nếu bạn đưa nhiều bản cập nhật vào một yêu cầu API. Bạn có thể tạo lô cho tối đa 1.000 bản cập nhật trong một lệnh gọi API. 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 có thay đổi về dữ liệu trong hệ thống của bạn, kích hoạt bản cập nhật theo thời gian thực cho Google) thay vì phương pháp dựa trên tần suất (tức là mỗi X phút quét hệ thống để phát hiện các thay đổi) nếu có thể.
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 phát hành chính thức. Môi trường hộp cát dùng để kiểm thử các yêu cầu API và môi trường phát hành chính thức để cập nhật nội dung mà người dùng hai đầu trong giao dịch Đặt hàng nhìn thấy.
- Hộp cát –
partnerdev-mapsbooking.googleapis.com - Phát hành công khai -
mapsbooking.googleapis.com
Thiết bị đầu cuối
API cập nhật theo thời gian thực hiển thị hai điểm cuối để xử lý các yêu cầu đến về việc cập nhật kho hàng:
- CẬP NHẬT -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - XOÁ –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Bạn có thể tìm thấy thông số PARTNER_ID trong Actions Center trên trang Tài khoản và người dùng, như trong ảnh chụp màn hình dưới đây.
Lấy 10000001 làm giá trị của PARTNER_ID làm ví dụ từ ảnh chụp màn hình ở trên, 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ẽ có dạng như trong các ví dụ dưới đây.
Cập nhật hộp cát
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ề bản phát hành công khai
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
XOÁ phiên bản phát hành công khai
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
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 chứa 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 ý:Đảm bảo nguồn cấp dữ liệu hằng ngày của bạn cũng chứa mọi thay đổi được gửi qua API cập nhật theo thời gian thực. Nếu không, dữ liệu của bạn có thể đã cũ hoặc lỗi thời.
Cập nhật tải trọng yêu cầu
Nội dung yêu cầu là một đối tượng JSON có 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. Tệ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ớ cung cấp dấu thời gian khi thực thể được tạo trong các hệ thống phụ trợ của bạn. Nếu bạn không thêm trường này, thì 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 không được vượt quá 5 MB.
- Hãy tách khoảng trắng để giảm kích thước.
- Có thể có tối đa 1.000 nội dung cập nhật trong một yêu cầu
batchPush.
Ví dụ
Cập nhật ETA
Giả sử bạn cần khẩn cấp cập nhật ETA của một dịch vụ giao hàng từ 30-60 phút thành 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 theo yêu cầu POST qua HTTP như sau (nội dung yêu cầu được in rõ ràng để 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 đưa 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 trong yêu cầu POST qua HTTP. Mỗi yêu cầu POST phải bao gồm thông 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 ý:Đảm bảo rằng nguồn cấp dữ liệu hằng ngày của bạn cũng chứa mọi thay đổi được gửi qua API cập nhật theo thời gian thực. Nếu không, quá trình nhập hàng loạt hằng ngày sẽ ghi đè các 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ì việc này có thể khiến dữ liệu không nhất quán. Thay vào đó, hãy sử dụng nguồn cấp dữ liệu hàng loạt.
Mã 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 trong lệnh gọi API cập nhật theo thời gian thực:
- Cấp yêu cầu – Các quy trình xác thực này kiểm tra để đảm bảo rằng tải trọng tuân theo giản đồ và mỗi
proto_recordđều chứa một trườngidvàtype. Các bước kiểm tra này mang 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 lần 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 trong giai đoạn xác thực này sẽ không được báo cáo trong phản hồi của API. Các sự kiện đó 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 việc đưa 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ời gian xử lý cập nhật theo thời gian thực
Thực thể được cập nhật thông qua bản cập nhật theo thời gian thực sẽ được xử lý trong 5 phút.