透過 Fleet Engine 隨選乘車和 Deliveries API 管理行程 以及行程和訂單進度應用程式的車輛狀態 這個程式庫可處理驅動程式 SDK、Consumer SDK 與 與 Fleet Engine 通訊 gRPC 或 REST 呼叫
必要條件
進行開發作業時,請務必安裝 SDK (gcloud),並經過驗證 。
殼層
gcloud auth login
您應該會看到如下成功訊息:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
確認隨選乘車和運送服務 Solution Fleet Engine API 設定正確。
殼層
gcloud --project=project-id services enable fleetengine.googleapis.com
如果這個指令導致錯誤,請與專案管理員聯絡 與您的 Google 支援代表聯絡,以取得存取權。
記錄
Fleet Engine 可以針對收到的 API 呼叫寫入記錄訊息 「Google Cloud Platform 記錄檔」 。 請參閱 Cloud Logging 說明文件,瞭解 概略說明如何閱讀及分析記錄檔
下列時間前建立的專案可能不會預設啟用記錄功能 2022 年 2 月 10 日。詳情請參閱 記錄功能 ,掌握更多詳細資訊。
用戶端程式庫
我們發布多種常見程式設計語言的用戶端程式庫。這些 程式庫將有助於提供比原始 REST 或 gRPC 更出色的開發人員體驗。 如需取得伺服器應用程式用戶端程式庫的操作說明, 看 用戶端程式庫。
本說明文件中的 Java 範例假設您已熟悉 gRPC。
驗證及授權
你可以設定「行程」和「訂單進度」提供的功能 Google Cloud 控制台這些 API 和 SDK 需要使用 JSON Web Token 已使用服務帳戶建立的服務帳戶完成簽署 Cloud 控制台
Cloud 專案設定
如要設定雲端專案,請先建立專案,然後 可以建立服務帳戶
如要建立 Google Cloud 專案,請按照下列步驟操作:
- 使用 Google Cloud 控制台建立 Google Cloud 專案。
- 使用 API 和服務資訊主頁 Local Rides and Deliveries API。
服務帳戶與一或多個角色相關聯。用途是 JSON Web Token 會依照 角色。一般而言,為減少濫用行為 或每個帳戶都有最低限度的必要角色組合
Trip 和 Order Progress 使用下列角色:
角色 | 說明 |
---|---|
Fleet Engine Consumer SDK 使用者
roles/fleetengine.consumerSdkUser |
可授予搜尋車輛和擷取資訊的權限 提供車輛和行程資訊服務帳戶透過這項機制建立的權杖 角色通常用於代僱駕駛服務或貨物外送應用程式的行動裝置上。 |
Fleet Engine 驅動程式 SDK 使用者
roles/fleetengine.driverSdkUser |
授予更新車輛位置、路線和 ,擷取車輛和行程的相關資訊。已建立的權杖 通常由具備這個角色的服務帳戶 共乘/代僱駕駛服務或外送司機應用程式的行動裝置。 |
Fleet Engine 隨選管理員
roles/fleetengine.ondemandAdmin |
授予所有車輛和行程資源的讀取及寫入權限。 具備這個角色的主體不需要使用 JWT,而是應該改用 JWT 使用應用程式預設憑證。系統會忽略自訂 JWT 憑證附加資訊。 這個角色應限制在受信任的環境 (客戶後端) 範圍內。 |
roles/fleetengine.serviceSuperUser |
授予所有車輛和行程 API 的權限。建立的權杖數量
由具備這個角色的服務帳戶
通常會從後端使用
伺服器這個角色已淘汰。偏好
請改為使用「roles/fleetengine.ondemandAdmin 」。 |
舉例來說,您可以為這三個角色分別建立服務帳戶 各自的角色
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
驅動程式和消費者 SDK 是根據這些標準角色建構而成。
您也可以建立自訂角色 要組合的任意權限組合 Driver 和 Consumer SDK 會在 缺少必要權限。因此,我們強烈建議 使用上述的標準角色組合,而非使用自訂角色。
為了方便起見,如果您需要為不受信任的用戶端建立 JWT 符記, 授予服務帳戶權杖建立者角色的使用者,可讓對方建立符記 使用 gcloud 指令列工具進行操作。
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
其中 my-user@example.com
是用於以下敘述的電子郵件:
透過 gcloud 進行驗證 (gcloud auth list
--format='value(account)'
)。
Fleet Engine 驗證程式庫
Fleet Engine 使用 JSON Web Token (JWT) 限制存取 Fleet Engine API新的 Fleet Engine 驗證程式庫 前往 GitHub 取得, 可簡化 Fleet Engine JWT 的建構程序,並以安全的方式簽署 Fleet Engine JWT。
這個程式庫提供以下優點:
- 簡化建立 Fleet Engine 權杖的程序。
- 提供使用憑證檔案以外的憑證簽署機制 (例如 模擬服務帳戶)
- 將簽署權杖附加至從 gRPC 虛設常式或 GAPIC 用戶端。
建立授權的 JSON Web Token (JWT)
不使用 Fleet Engine 驗證程式庫時,您必須建立 JSON Web Token (JWT) 直接在程式碼集中處理為此,您必須同時具備 瞭解 JWT 及其與 Fleet Engine 之間的關係。正因如此 強烈建議您使用 Fleet Engine 驗證程式庫。
在 Fleet Engine 中,JSON Web Token (JWT) 提供短期驗證 並確保裝置只能修改車輛、行程或工作 取得與授權相關的憑證JWT 含有標頭和憑證附加資訊區段。 header 區段則包含 要使用的私密金鑰 (由服務帳戶取得) 和加密功能 演算法。著作權聲明部分包含 權杖的建立時間、權杖存留時間 主張存取權,以及要限定範圍的其他授權資訊 存取;例如車輛 ID
JWT 標頭區段包含下列欄位:
欄位 | 說明 |
---|---|
Alg | 要使用的演算法。`RS256`。 |
typ | 權杖類型。「JWT」。 |
兒童 | 服務帳戶的私密金鑰 ID。您可以在 服務帳戶 JSON 檔案的「private_key_id」欄位中 請務必使用具備正確權限層級的服務帳戶金鑰。 |
JWT 憑證附加資訊區段包含下列欄位:
欄位 | 說明 |
---|---|
iss | 服務帳戶的電子郵件地址。 |
替補球員 | 服務帳戶的電子郵件地址。 |
aud | 服務帳戶的 SERVICE_NAME,在本範例中為 https://fleetengine.googleapis.com/ |
iat | 權杖建立時間的時間戳記 (從過去幾秒內指定) ,時間為世界標準時間 1970 年 1 月 1 日 00:00:00請等候 10 分鐘,讓系統進行偏差。如果 時間戳記距離現在太久,或在未來,伺服器可能會回報錯誤。 |
exp | 權杖到期時間的時間戳記 (以秒數為單位) ,時間為世界標準時間 1970 年 1 月 1 日 00:00:00如果時間戳記為 未來一小時以上。 |
授權 | 視用途而定,可能包含 `vehicleid` 或 `tripid`。 |
建立 JWT 權杖是指簽署該權杖。如需操作說明和程式碼範例 如需建立及簽署 JWT,請參閱 不使用 OAuth 的服務帳戶授權。 然後您可以將已簽署的憑證附加至 gRPC 呼叫,或附加至其他使用的方法 存取 Fleet Engine。
JWT 憑證附加資訊
建立 JWT 酬載時,請在授權中新增其他憑證附加資訊
鍵 vehicleid
或 tripid
設為
來電時使用的車輛 ID 或行程 ID。
Driver SDK 一律使用 vehicleid
憑證詞 (無論其在
行程或車輛。Fleet Engine 後端會確保
與要求的行程相關聯。
Consumer SDK 一律使用 tripid
宣告。
代僱駕駛服務或快遞服務供應商應使用 vehicleid
或 tripid
,並以「*」結尾到
符合所有「交通工具」和「行程」。請注意,JWT 可同時包含這兩種符記
這可能會簡化權杖簽署實作。
JWT 用途
以下是「供應商伺服器」的權杖範例:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
以下是「消費者應用程式」的權杖範例:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
以下是驅動程式應用程式的憑證範例:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- 針對標頭中的
kid
欄位,指定服務帳戶的私密金鑰 編號。您可以在服務的private_key_id
欄位找到這個值 帳戶 JSON 檔案 - 在
iss
和sub
欄位中,指定服務帳戶的電子郵件地址。 您可以在服務帳戶的client_email
欄位中找到這個值 JSON 檔案 - 在
aud
欄位中,指定 https://SERVICE_NAME/。 - 在
iat
欄位中,使用憑證建立時的時間戳記。 則是從世界標準時間 1970 年 1 月 1 日 00:00:00 算起的秒數。 請等候 10 分鐘,讓系統進行偏差。如果時間戳記在過去太久 或日後,伺服器可能會回報錯誤。 - 在
exp
欄位中,使用符記到期時的時間戳記。 指定為秒數,自世界標準時間 1970 年 1 月 1 日 00:00:00 起計算。最大值 允許的值為iat
+ 3600。
簽署要傳遞至行動裝置的 JWT 時,請務必使用 驅動程式或 Consumer SDK 角色的服務帳戶。否則,行動裝置 裝置能夠變更不應出現的狀態。
同樣地,在簽署用於特殊權限呼叫的 JWT 時,請確認 以具備「超級使用者」角色的服務帳戶使用服務帳戶否則, 也會失敗。
產生測試用 JWT
在測試期間,從終端機產生權杖會很有幫助。
您必須使用者 帳戶必須具備「服務帳戶權杖建立者」角色:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
建立名為 unsigned_token.json
的新檔案,並在其中加入以下內容。iat
屬性是 Epoch 紀元後目前時間 (單位為秒)
在終端機中執行 date +%s
即可擷取。exp
屬性是
到期時間,單位為 Epoch 紀元時間後以秒為單位
在 iat
中新增 3600。到期時間不得超過
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
接著執行下列 gcloud 指令,為您的 Super 專案簽署憑證 使用者服務帳戶:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
現在,已簽署的 Base64 編碼 JWT 應該儲存在檔案中
signed_token.jwt
。權杖有效期限為一小時。
您現在可以對清單車輛執行 curl
指令以測試權杖
REST 端點:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
車輛及其生命週期
車輛是代表駕駛車組合的實體。目前, 你無法分別追蹤駕駛與車輛。共乘/代僱駕駛服務供應商 使用提供者 ID (必須與 Google Cloud 專案 (包含服務帳戶) 的專案 ID 以及共乘/貨運供應商自有車輛 ID,以及 Fleet Engine API。
七天後仍未透過 UpdateVehicle
更新的車輛將會
自動刪除,而指派給行程的行程 (如有) 則會標示為
未指定。建議讓車輛持續可用
是 Fleet Engine 定期更新位置更新時間上限
Vehicle
實體中的其他欄位也會延長資料生命週期,前提是:
新欄位值與現有欄位值不同
注意:Vehicle
實體中的部分欄位 (例如 device_settings
) 僅適用於偵錯作業
資訊,不會由 Fleet Engine 保存。更新容器無法
延長 Vehicle
實體的生命週期。
如果使用CreateVehicle
已有相同的提供者 ID/車輛 ID 組合。如果有
經常更新,無法經常更新:經常呼叫
將 CreateVehicle
替換為預期的提供者 ID/車輛 ID 組合,並予以捨棄
如果車輛已存在,就會發生錯誤;或是在以下事件後呼叫 CreateVehicle
:
UpdateVehicle
傳回 NOT_FOUND
錯誤。
車輛位置更新
為確保 Fleet Engine 發揮最佳效能,請提供車流 位置更新。請使用下列其中一種方式提供這些更新:
- 使用 Driver SDK: Android、 iOS 是最簡單的選項。
- 使用自訂程式碼 -- 如果商家地點有 或是透過後端轉送位址,或者您使用 Android 或 Android 以外的裝置 iOS 裝置。
交通工具類型
車輛實體含有 VehicleType
的必填欄位,其中包含
Category
列舉,可以指定為 AUTO
、TAXI
、TRUCK
、
TWO_WHEELER
、BICYCLE
或 PEDESTRIAN
。交通工具類型可做為
SearchVehicles
和 ListVehicles
中的篩選條件。
所有車輛路線都會使用對應的 RouteTravelMode
類別設定為 AUTO
、TWO_WHEELER
、BICYCLE
或 PEDESTRIAN
。
如果類別設為「TAXI
」或「TRUCK
」,系統會將路線視為
AUTO
模式。
車輛屬性
車輛實體包含 VehicleAttribute
重複欄位。這些
屬性則不會由 Fleet Engine 解譯。SearchVehicles
API 包含一個欄位,要求相符的 Vehicles
必須包含所有
加入的屬性設為指定值
請注意,屬性欄位不是其他幾個支援的欄位
,例如 vehicle_type
和 supported_trip_types
。Vehicle
車輛其餘路線控點
車輛實體包含 TripWaypoint
的重複欄位 (RPC | REST),
呼叫 waypoints
(RPC | REST)。
此欄位會依序包含行程中剩餘的路點
並讓車輛靠近車輛Fleet Engine 會在行程期間
,且隨著行程變更狀態而更新路線。
這些路線控點可透過 TripId
欄位和 WaypointType
欄位識別。
擴大車輛的配對資格
一般而言,代僱駕駛服務或貨品交付服務供應商會負責比對行程
對車輛發出的要求服務可以使用交通工具屬性
搜尋量更是驚人例如,供應商可以
對應福利等級
例如車輛舉例來說,有三個層級可能是一組採用布林值的屬性。
值:is_bronze_level
、is_silver_level
和 is_gold_level
。車輛
這些都能滿足這三項條件機群引擎收到要求
需要銀級能力的行程,搜尋範圍包含該車。
透過這種方式使用屬性包括提供各式各樣屬性的車輛
即便沒有技術背景,也能因這些工具的功能而受益
更新車輛屬性的方法有兩種。第一個是UpdateVehicle
也能使用 Google Cloud CLI 或
Compute Engine API使用這個 API 時,整組交通工具屬性為
設為這個值。無法只更新單一屬性。
另一個方法是 UpdateVehicleAttributes
API。這個方法只需要
要更新的屬性。要求中包含的屬性將會是
設為新的值或加入的;系統不會修改未指定的屬性。
教學示範:組建車輛
你必須為要追蹤的每輛車建立 Vehicle
實體。
使用 CreateVehicle
端點搭配 CreateVehicleRequest
來建立
交通工具。
Vehicle
的 provider_id
必須是專案 ID
(例如 my-on-demand-project) 所屬 Google Cloud 專案,其中含有
用於呼叫 Fleet Engine 的服務帳戶。請注意,
多個服務帳戶可以存取 Fleet Engine 存取同一個代僱駕駛服務
或傳送服務供應商,Fleet Engine 目前不支援
多項 Google Cloud 專案存取同一個 Vehicles
。
您可以在 OFFLINE
或 ONLINE
狀態中建立 Vehicle
。如果
已建立 ONLINE
,回應 SearchVehicles
可立即傳回。
舉個簡單的例子,您可以定義情境
並指示 AI 如何回應服務中心查詢
CreateVehicle
呼叫中可包含初始 last_location
。
在允許的情況下,不應在沒有回應的情況下,以 ONLINE
狀態建立 Vehicle
一個 last_location
。
如要進一步瞭解車輛,請參閱「交通工具類型」一文 類型。
詳情請參閱車輛屬性 屬性都一樣
從 CreateVehicle
傳回的值是已建立的 Vehicle
實體。
範例
殼層
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
詳情請見 providers.vehicles.create 參照。
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
用來建立車輛的 Google Cloud 平台記錄檔
Fleet Engine API 會透過 Google Cloud Platform 記錄檔寫入一個記錄項目
則接收對 CreateVehicle
端點的呼叫。記錄項目包含
CreateVehicle
要求中值的相關資訊。如果來電
也會包含 Vehicle
相關資訊
。
殼層
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
輸出的記錄應與下列內容類似:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
車輛建立作業的 Cloud Pub/Sub 通知
Fleet Engine API 會透過 Cloud Pub/Sub 發布新的通知 車輛建立完成。如要接收這類通知,請按照 如需操作說明,請參閱這篇文章。
操作說明:更新車輛位置
如果你未使用 Driver SDK 更新車輛位置資訊, 直接呼叫 Fleet Engine 所在位置。對於任何使用中的車輛, Fleet Engine 預計每分鐘更新至少一次位置,最多不超過一次 每 5 秒執行一次這些更新作業只需要 Fleet Engine 驅動程式 SDK 使用者 權限。
範例
殼層
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
詳情請見 providers.vehicles.update 參照。
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
HOW-TO:更新其他車輛欄位
車輛狀態其他屬性的更新頻率少於
位置更新。如要更新 last_location
以外的屬性,就需要
Fleet Engine 超級使用者權限。
UpdateVehicleRequest
包含 update_mask
,用於指出要記錄哪些欄位
更新。欄位的行為與
欄位遮罩
如車輛屬性所述,更新
attributes
欄位需要編寫所有要保留的屬性。這項服務
無法只更新
UpdateVehicle
呼叫。如要更新特定屬性的值,請在
UpdateVehicleAttributes
API
範例
這個範例會啟用 back_to_back
。
殼層
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
詳情請見 providers.vehicles.update 參照。
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
車輛最新動態的 Google Cloud 平台記錄檔
Fleet Engine API 會透過 Google Cloud Platform 記錄檔寫入一個記錄項目
則接收對 UpdateVehicle
端點的呼叫。記錄項目包含
UpdateVehicle
要求中值的相關資訊。如果來電
也會包含 Vehicle
相關資訊
。
殼層
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
車輛更新的 Cloud Pub/Sub 通知
Fleet Engine API 透過 Cloud Pub/Sub 發布通知,而且現有 已更新車輛。如要接收這類通知,請按照 如需操作說明,請參閱這篇文章。
操作說明:搜尋車輛
Fleet Engine 支援搜尋車輛。SearchVehicles
透過 API 找出附近最適合執行特定工作的驅動程式,例如:
為行程或外送要求提供服務。SearchVehicles
API 會傳回
根據
艦隊若需更多資訊,請參閲
尋找附近的駕駛。
範例
搜尋有貨時,Fleet Engine 會排除 根據預設,目前有效的行程。代僱駕駛服務或快遞服務供應商的服務必須 明確地將這類網址加入搜尋要求以下範例說明如何 在這些車輛中搜尋與大地車相符的車輛時 印尼東購物中心 (Balai Sidang Jakarta Convention Center)。
殼層
首先,請更新我們在先前步驟中建立的車輛位置 符合資格。實際執行時,由執行驅動程式 SDK 的驅動程式 SDK 在車上的 Android 或 iOS 裝置上。
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
系統至少應傳回該車型。
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
詳情請見 providers.vehicles.search 參照。
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
車輛篩選查詢
SearchVehicles
和 ListVehicles
支援篩選車輛屬性
篩選查詢如需篩選查詢語法,請參閱
AIP-160。
請注意,篩選查詢「只能」篩選車輛屬性,而且
不得用於其他欄位篩選查詢會以 AND
子句的形式呈現
與其他限制,例如 minimum_capacity
或 vehicle_types
SearchVehiclesRequest
。
HOW-TO:刊登車輛清單
SearchVehicles
已經過最佳化調整,可尋找排名中的少數車輛
快速點餐,主要用來尋找附近最適合的司機
加入一項任務不過,有時您會想找出符合某些條件的所有車輛
條件。ListVehicles
是
專為該用途而設計
ListVehicles
API 可讓您找到符合某些特定條件的所有車輛
要求選項。ListVehicles
API 會傳回分頁形式的車輛清單
符合某些需求的專案
如要篩選車輛屬性,請參閱 車輛篩選查詢:
範例
此範例使用vehicle_type
filter
字串。
殼層
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
詳情請見 providers.vehicles.list 參照。
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
行程及其生命週期
Trip API 和生命週期與 Vehicle API 和生命週期類似。
共乘服務供應商負責使用 Fleet Engine 建立行程
存取 APIFleet Engine 提供 RPC 服務
TripService
。
和 REST 資源、provider.trips
,直接在 Google Cloud 控制台實際操作。這些介面可讓您建立行程實體、建立資訊要求、搜尋行程
以及更新功能
Trip
具有狀態欄位,用於追蹤其在生命週期中的進度。
值從 NEW
移至 COMPLETE
,以及 CANCELED
和 UNKNOWN_TRIP_STATUS
,直接在 Google Cloud 控制台實際操作。請參閱「適用於遠端程序呼叫的 trip_status
」
或 REST 的 TripStatus。
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
你的服務可以從以下任一狀態更新前往CANCELED
的行程。
當服務建立行程時,引擎會將狀態設為 NEW
。A 罩杯
vehicle_id
為選用項目,和車輛一樣,服務會自動刪除未分配的行程
沒有更新如果服務嘗試以
ID 已存在,系統會傳回錯誤。如果行程符合以下條件,系統就會將該行程視為「進行中」
狀態是 COMPLETE
或 CANCELED
以外的狀態。這種區別在於
請務必前往車輛實體和 SearchTripsRequest
的 active_trips
欄位。
你的服務只能在行程時變更指派給行程的 vehicle_id
已啟用。舉例來說,假設駕駛人在車上取消行程
並將行程重新指派至其他車輛。
在實作反向導入時,狀態是重要 行程支援。這項支援服務可讓供應商指派新的行程到車輛 車輛正在行駛中。程式碼 建立返回行程的方式與單一行程相同,且使用 車輛 ID。Fleet Engine 會將新行程的起點和目的地 車輛的路線控點如要進一步瞭解返回行程,請參閱 建立多路線行程。
行程其餘路線控點
行程實體包含 TripWaypoint
的重複欄位 (RPC | REST),
稱為 remainingWaypoints
(RPC | REST)。
這個欄位包含車輛必須按照順序行駛的所有路線控點
直到這趟行程的最終停靠點之前。計算依據為
車輛剩餘的路線控點。
在「返回」和「共乘」應用實例中,這份清單包含
其他行程,但不包含任何路線控點
。清單中的路線控點可透過 TripId
來識別
和 WaypointType
。
行程狀態與車輛剩餘路線控點之間的關係
車輛的其餘路線控點 (RPC | REST) 會
Fleet Engine 收到行程狀態變更要求時更新。
系統就會從車輛的其餘路線控點清單中,移除
tripStatus
(RPC | REST)
已從其他狀態變更為 ENROUTE_TO_XXX。也就是說
行程狀態已從 ENROUTE_TO_PICKUP 變更為 ARRIVED_AT_PICKUP,行程的
上車地點仍會顯示在車輛其他路線控點清單中,不過當行程時
狀態已變更為 ENROUTE_TO_INTERMEDIATE_DESTINATION 或 ENROUTE_TO_DROPOFF,
,系統就會將該上車地點從車輛其餘的路線控點中移除。
該規則也適用於 ARRIVED_AT_INTERMEDIATE_DESTINATION 和 ENROUTE_TO_INTERMDEDIATE_DESTINATION.當 ARRIVED_AT_INTERMEDIATE_DESTINATION 時, 目前的中繼目的地不會從車輛剩餘空間中移除 路線控點清單,直到車輛回報轉送至下一個路線點為止。
行程狀態變更為 COMPLETED
後,這趟行程就不會有任何路線控點
。
操作說明:建立行程
您必須建立 Trip
實體,才能追蹤每個行程要求,
。搭配 CreateTripRequest
使用 CreateTrip
端點
即可建立行程
必須提供下列屬性才能建立行程:
parent
- 包含提供者 ID 的 已建立 Cloud 專案。trip_id
- 代僱駕駛服務提供者建立的字串。trip
- 提供行程的基本中繼資料的容器。
建立行程時,您可以提供 number_of_passengers
、dropoff_point
和 vehicle_id
。雖然這些欄位並非必要,但如果您提供這些欄位
這些資料都會保留系統會忽略所有其他行程欄位。舉例來說,所有行程
開頭為 trip_status
/NEW
,即使傳入 trip_status
CANCELED
。
範例
以下範例會建立前往大印尼東購物中心的行程。旅程
專屬於兩位乘客。Trip
的 provider_id
必須是
與專案 ID 相同在這個例子中,共乘服務供應商建立了
Google Cloud 專案:project-id。這項專案必須具備
用於呼叫 Fleet Engine 的服務帳戶。行程的狀態為 NEW
。
稍後,服務與車輛比對相符後,服務就能呼叫
將行程指派給車輛時,請 UpdateTrip
並變更 vehicle_id
。
殼層
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
詳情請見 providers.trips.create 參照。
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
用於建立行程的 Google Cloud Platform 記錄檔
Fleet Engine API 會使用 Google Cloud Platform 記錄檔寫入記錄項目,而且
則接收對 CreateTrip
端點的呼叫。記錄項目包含
CreateTrip
要求中值的相關資訊。如果來電
就會包含傳回的 Trip
相關資訊。
操作說明:更新行程
Trip 實體包含的欄位可用來追蹤服務及
透過 Driver SDK 回報行程進度,以及
Consumer SDK。如要更新屬性,請使用 UpdateTripRequest
撰寫新的電子郵件訊息這會根據要求的 field_mask
更新行程欄位。
請參閱 UpdateTripRequest。
代僱駕駛服務提供者負責更新下列屬性:
- 行程狀態。
- 車輛 ID。建立時或將車輛與 。
- 上車、下車或路線控點有所變更。
使用 透過驅動程式 SDK 或消費者 SDK 分享歷程功能:
- 路徑
- 預計抵達時間
- 剩餘距離
- 車輛位置
- 其餘路線控點
請參閱 RPC 中的 Trip
;或
REST 中的 Resource.Trip
。
行程更新的 Google Cloud Platform 記錄檔
Fleet Engine API 會使用 Google Cloud Platform 記錄檔寫入記錄項目,而且
則接收對 UpdateTrip
端點的呼叫。記錄項目包含
UpdateTrip
要求中值的相關資訊。如果呼叫成功
也會包含傳回的 Trip
相關資訊。
操作說明:搜尋行程
Fleet Engine 支援搜尋行程。如先前所說,行程是
系統會在七天後自動刪除,因此 SearchTrips
不會
可查看所有行程的完整記錄。
雖然 SearchTrips
是可彈性調整的 API,下列清單仍會考量兩種用途。
判斷車輛的主動行程:供應商可以判斷車輛目前正在進行的行程。在
SearchTripsRequest
中,vehicle_id
已設為考慮使用的車輛,active_trips_only
應設為true
。協調供應商和 Fleet Engine 狀態:提供者可以使用
SearchTrips
確保其 Trip 狀態與 Fleet Engine 相符。 這對 TripStatus 尤其重要。如果獲派行程的狀態 車輛的正確設定未正確設為COMPLETE
或CANCELED
,這輛車 未包含在「SearchVehicles
」中。
如要以這種方式使用 SearchTrips
,請將 vehicle_id
留空,請將 active_trips_only
設為
設為 true
,並將 minimum_staleness
設為大於大多數行程時間長度的時間。
例如設定一小時。搜尋結果會包含未排除的行程
完成或已取消,且一小時內未更新。提供者
應檢查這些行程,確保 Fleet Engine 的狀態
正確更新。
疑難排解
如果發生 DEADLINE_EXCEEDED
錯誤,Fleet Engine 的狀態為
未知。提供者應再次呼叫 CreateTrip
,這個方法會傳回
201 (CREATED) 或 409 (CONFLICT)。在第二種情況中,先前的要求已順利完成
DEADLINE_EXCEEDED
前。詳情請參閱 Consumer API 指南
如何處理行程錯誤:Android
或 iOS。
共乘行程支援
您可以將多個 SHARED
行程指派給支援 TripType.SHARED
的車輛。
對於指派給下列客戶的所有行程,您必須指定所有未傳遞的路線控點順序
當您指派 Trip.vehicle_waypoints
共用行程中的車輛
共用行程的 vehicle_id
(在 CreateTrip
或 UpdateTrip
要求中)。
請參閱「適用於遠端程序呼叫的 vehicle_waypoints
」
或 vehicleWaypoints
代表 REST。
支援多個目的地
識別中繼目的地
intermediateDestinations
欄位和 intermediateDestinationIndex
欄位
行程期間 (RPC | REST)
,則用來表示目的地。
更新中繼目的地
您可以透過 UpdateTrip
更新中繼目的地。更新時
您必須提供中繼目的地的完整清單,
包括造訪過的頁面,而不只是最近
「服務」會自動新增或修改。
當 intermediateDestinationIndex
指向索引位置之後
新增/修改過的中繼目的地、新的/更新過的中繼目的地
目的地不會新增至車輛的 waypoints
或行程的 remainingWaypoints
。
這是因為 intermediateDestinationIndex
之前的任何中繼目的地
會視為造訪過的網站。
行程狀態變更
欄位 intermediateDestinationsVersion
(RPC | REST)
要求傳送至 Fleet Engine 的 Trip 狀態更新要求時,要求為必填
傳遞到中繼目的地指定的中繼目的地
是透過 intermediateDestinationIndex
欄位指定。
當 tripStatus
(RPC | REST) 為 ENROUTE_TO_INTERMEDIATE_DESTINATION 時,介於
[0..N-1] 表示車輛接下來會跨越的中繼目的地。
當 tripStatus
為 ARRIVED_AT_INTERMEDIATE_DESTINATION 時,介於
[0..N-1] 表示車輛目前所在的中繼目的地。
範例
以下程式碼範例示範如何將行程狀態更新為接收路徑 並附加至第一個中繼目的地 (假設您已建立) 行程,且行程已超過上車地點。
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
操作說明:訂閱 Fleet Engine API 的通知訊息
Fleet Engine API 使用 Google Cloud Pub/Sub 針對消費者 Google Cloud 建立的主題發布通知 專案。Google Cloud 的 Fleet Engine 預設未啟用 Pub/Sub 專案。請提交客服案件,或是與客戶工程師聯絡,啟用 Pub/Sub。
如要在 Cloud 專案中建立主題,請按照這些說明操作。 主題 ID 必須為「fleet_engine_notifications」。
主題必須在呼叫 Fleet Engine 的 Cloud 專案中建立 相互整合
建立主題後,您必須授予 Fleet Engine API
有權在主題上發布。方法很簡單,只要按一下您訂閱的主題
並加入新權限您可能需要按一下「顯示資訊面板」,才能開啟權限編輯器。
主體應為 geo-fleet-engine@system.gserviceaccount.com
而角色應為 Pub/Sub publisher
。
如要設定 Cloud 專案以訂閱通知, 請按照這些步驟操作
Fleet Engine API 會在兩種不同的資料中發布每則通知
格式,protobuf
和
json
。各項通知的資料格式都位於
PubsubMessage 屬性
索引鍵為 data_format
,值為 protobuf
或 json
。
通知結構定義:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}