Trang này được dịch bởi Cloud Translation API.

Cập nhật theo thời gian thực

Thông tin cập nhật theo thời gian thực

RTU chủ yếu dành cho các nội dung cập nhật mà bạn không thể lường trước được, chẳng hạn như việc đóng đường khẩn cấp hoặc siêu dữ liệu thay đổi định kỳ (chẳng hạn như ETA). Nếu không cần phản ánh thay đổi ngay lập tức, bạn có thể sử dụng tính năng truyền dẫn nguồn cấp dữ liệu hàng loạt. Thông tin cập nhật theo thời gian thực được xử lý trong vòng 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 cho người chỉnh sửa food-support@google.com
- Thông báo cho đầu mối liên hệ (POC) 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 để tính năng cập nhật theo thời gian thực hoạt động.
- Bật API Đặt chỗ trên Maps:
  - 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 thực thể Hộp cát ("Google Maps Booking API (Dev)") rồi nhấp vào Bật
  - Tìm phiên bản Chính thức ("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ò là người chỉnh sửa cho dự án GCP của bạn. Để biết thêm thông tin chi tiết, hãy xem phần Thiết lập tài khoản dịch vụ.
  - Hãy nhớ tải nguồn cấp dữ liệu theo lô lên môi trường mà bạn đang làm 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ý việc trao đổi mã thông báo theo cách thủ công như mô tả trong phần Sử dụng OAuth 2.0 để truy cập vào API của Google.

Thiết lập tài khoản dịch vụ

Bạn cần có tài khoản dịch vụ để tạo các yêu cầu HTTPS đã xác thực cho 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 được liên kết. Chọn dự án đó nếu bạn 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 Project > Editor (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ụ bạn vừa tạo.
Chọn định dạng JSON rồi nhấp vào Tạo.
Sau khi tạo cặp khoá công khai/riêng tư mới, 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 thông qua API cập nhật theo thời gian thực. Bạn có thể gửi nhiều nội dung cập nhật theo thời gian thực cùng một lúc nếu đưa nhiều nội dung cập nhật vào một yêu cầu API. Bạn có thể cập nhật hàng loạt tối đa 1.000 URL 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 nội dung cập nhật qua RTU (tức là khi dữ liệu thay đổi trong hệ thống, hãy kích hoạt nội dung 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à cứ mỗi X phút quét hệ thống để tìm 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 công khai. 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 phát hành chính thức để cập nhật nội dung hiển thị cho người dùng sử dụng tính năng Đặt hàng toàn diện.

Hộp cát – partnerdev-mapsbooking.googleapis.com
Phát hành chính thức – mapsbooking.googleapis.com

Điểm 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 cập nhật khoảng không quảng cáo sắp tới:

UPDATE – /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 (Trung tâm hành động) trên trang Account and users (Tài khoản và người dùng), như trong ảnh chụp màn hình bên dưới.

Mã đối tác trên Cổng thông tin cho đối tác

Lấy 10000001 làm giá trị của PARTNER_ID làm ví dụ trong ảnh chụp màn hình ở trên, URL đầy đủ để gửi yêu cầu API trong hộp cát và phiên bản phát hành chính thức sẽ giống như trong các ví dụ bên dưới.

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

Bản cập nhật chính thức

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

XÓA bản chính thức

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, hãy sử dụng điểm cuối cập nhật trong yêu cầu POST 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ể mà 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 thông 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ể đã lỗi thời hoặc cũ.

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 bản ghi. Mỗi bản ghi tương ứng với một thực thể đang được cập nhật. Nó 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: Hãy nhớ thêm dấu thời gian của thời điểm tạo thực thể trong hệ thống phụ trợ. 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ầu batchPush, trường generation_timestamp đượ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ệ.

Kích thước nội dung tải trọng không được vượt quá 5 MB.
Loại bỏ 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 thời gian đến dự kiến

Giả sử bạn cần khẩn trương cập nhật thời gian dự kiến giao hàng của một dịch vụ giao hàng từ 30 đến 60 phút thành 60 đến 90 phút. Nội dung 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 của bạn bằng HTTP POST như sau (phần 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 đư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á các thực thể khỏi khoảng không quảng cáo, hãy sử dụng điểm cuối DELETE trong yêu cầu POST 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 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 thông qua API cập nhật theo thời gian thực. Nếu không, quá trình truyền dẫn hàng loạt hằng ngày sẽ ghi đè các thay đổi theo thời gian thực của bạn.

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 tính năng cập nhật theo thời gian thực để thêm các thực thể mới vì điều này có thể dẫn đến tình trạng dữ liệu không nhất quán. Thay vào đó, hãy sử dụng nguồn cấp dữ liệu theo lô.

Mã xác thực và phản hồi API

Có hai loại quy trình xác thực được thực hiện trên các 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 chứa một trường id và type. Các bước kiểm tra này là đồng bộ và kết quả được trả về trong phần 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 đã thành công 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 quy trình xác thực này không thành công và toàn bộ yêu cầu bị từ chối (bao gồm cả tất cả các thực thể trong tải trọng). Ví dụ: nếu proto_record thiếu @type, thì hệ thống sẽ trả về phản hồi lỗi sau:

  {
      "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 sẽ không được báo cáo trong phản hồi API. Các lỗi 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ể đều đượ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 là 1.500 yêu cầu mỗi 60 giây, tức là trung bình 25 yêu cầu mỗi giây. Khi bạn 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ử lại lệnh gọ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ể 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 tính năng cập nhật theo thời gian thực sẽ được xử lý trong vòng 5 phút.

Theo dõi chuyển đổi

Cập nhật theo thời gian thực Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.