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 những nội dung cập nhật mà bạn không thể dự đoán trướ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ư thời gian dự kiến đến). 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 nhập hàng loạt nguồn cấp dữ liệu. Thông tin cập nhật theo thời gian thực được xử lý trong vòng tối đa 5 phút.

Thiết lập Google Cloud Platform

Thiết lập một dự án GCP. Bạn cần có một dự án trên Google Cloud Platform (GCP) để truy cập vào RTU API.
- Cấp quyền chỉnh sửa cho 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 của bạn trên Trung tâm hành động để thông tin 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 ("Google Maps Booking API (Dev)") rồi nhấp vào Bật
  - Tìm phiên bản Production ("Google Maps Booking API") rồi nhấp vào Enable (Bật)
  - Tạo một tài khoản dịch vụ có vai trò 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ụ.
  - Đả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 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ẫu mã bên dưới sử dụng những thư viện này. Nếu không, bạn sẽ cần xử lý các hoạt động 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 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ụ để thực hiện các yêu cầu HTTPS đã xác thực đối với 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 trê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 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 Tuỳ chọn khác > 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 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

Real-time updates API hỗ trợ 2 loại thao tác: Cập nhật và Xoá. Chúng tôi không hỗ trợ việc thêm các thực thể mới thông qua API cập nhật theo thời gian thực. Bạn có thể gộp các nội dung cập nhật theo thời gian thực nếu đưa nhiều nội dung cập nhật vào một yêu cầu API duy nhất. Bạn có thể gửi hàng loạt tối đa 1.000 nội dung cập nhật trong một lệnh gọi API duy nhất. 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 thông tin cập nhật thông qua RTU (tức là khi dữ liệu thay đổi trong hệ thống, hãy kích hoạt thông tin 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ứ X phút, hãy quét hệ thống để tìm 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 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 sản xuất để cập nhật nội dung mà người dùng Đặt hàng toàn diện nhìn thấy.

Hộp cát – partnerdev-mapsbooking.googleapis.com
Sản xuất – 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ảng không quảng cáo đến:

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 tham 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 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, các URL hoàn chỉnh để gửi yêu cầu API trong hộp cát và môi trường phát hành chính thức sẽ giống như trong các ví dụ bên dưới.

Bản 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á 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 hàng, hãy sử dụng điểm cuối update trong yêu cầu HTTP POST. Mỗi yêu cầu POST phải bao gồm tham số 10000001 cùng với một 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 không còn mớ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. 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: Đảm bảo bạn thêm dấu thời gian của thời điểm thực thể được tạo 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 sẽ đượ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ệ.

Phần nội dung của tải trọng không được vượt quá 5 MB.
Xoá 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 cập nhật ngay lập tức thời gian dự kiến đến 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"
	}
}

Sau đây là nội dung cập nhật theo thời gian thực bằng yêu cầu POST qua HTTP (phần nội dung yêu cầu được in khá 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 duy nhất, hãy thêm nhiều bản ghi vào trường proto_record của phần 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 hàng, hãy sử dụng điểm cuối DELETE trong yêu cầu HTTP POST. 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ể mà 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 nhập dữ liệu theo lô 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ể

Khô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 sự không nhất quán về dữ liệu. Thay vào đó, hãy sử dụng nguồn cấp dữ liệu theo lô.

Xác thực và mã phản hồi API

Có 2 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 đều chứa các 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 đã hoàn tất 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 sẽ 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ì 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 đều được xác thực dựa trên 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 API. Những thông tin 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 truyền tải thành công.

Hạn mức API

API theo thời gian thực có hạn mức là 1.500 yêu cầu sau 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ý việc này, hãy thử lại lệnh gọi theo các khoảng thời gian lớn dầ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 thêm nhiều thực thể vào một yêu cầu API. Bạn có thể thêm tối đa 1.000 thực thể trong 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.