隨選乘車和外送解決方案目前僅供特定合作夥伴使用。

本頁面由 Cloud Translation API 翻譯而成。

開始使用 Fleet Engine

透過 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 憑證附加資訊。這個角色應限制在受信任的環境 (客戶後端) 範圍內。
~~FleetEngine 服務超級使用者~~ (已淘汰) `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 - 提供行程的基本中繼資料的容器。
- trip_type - 列舉代表行程可能是否有其他乘客搭乘同一輛車上的其他起點和目的地 (SHARED) 或一方限定 (EXCLUSIVE)。
- pickup_point - 代表 Google 起點的起點位置 (TerminalLocation) 行程。請參閱 RPC 參考資料或 REST 參考資料

建立行程時，您可以提供 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"
    }
  }
}