開始使用 Android 版 Driver SDK

最低系統需求

行動裝置必須搭載 Android 5.0 (API 級別 21) 以上版本。

Maven 設定

您可以透過 Google Maven 存放區取得驅動程式 SDK 4.99 以上版本。

Gradle

請將以下內容新增到 build.gradle 檔案中:

repositories {
    ...
    google()
}

Maven

請將以下內容新增到 pom.xml 檔案中:

<project>
  ...
  <repositories>
    <repository>
      <id>google-maven-repository</id>
      <url>https://maven.google.com</url>
    </repository>
  </repositories>
  ...
</project>

專案設定

如要使用 Driver SDK,應用程式必須指定 minSdkVersion 21 以上版本。詳情請參閱「版本資訊」。

如要執行透過驅動程式 SDK 建構的應用程式,Android 裝置必須安裝 Google Play 服務

設定開發專案

如要在 Google Cloud 控制台中設定開發專案並取得專案的 API 金鑰,請按照下列步驟操作:

  1. 建立新的 Google Cloud 控制台專案,或選取現有專案,以便與 Driver SDK 搭配使用。請稍待幾分鐘,直到新的專案顯示在 Google Cloud 控制台中。

  2. 如要執行試用版應用程式,您的專案必須存取 Maps SDK for Android。在 Google Cloud 控制台中,選取「API 和服務」>「程式庫」,然後搜尋並啟用 Maps SDK for Android。

  3. 依序選取「APIs & Services」(API 和服務) >「Credentials」(憑證) >「Create credentials」(建立憑證) >「API key」(API 金鑰),以取得專案的 API 金鑰。如要進一步瞭解如何取得 API 金鑰,請參閱「取得 API 金鑰」一文。

在應用程式中新增驅動程式 SDK

驅動程式 SDK 可透過私人 Maven 存放區取得。存放區包含 SDK 的專案物件模型 (.pom) 檔案和 Javadocs。如何將 Driver SDK 新增至應用程式:

  1. 將下列依附元件新增至 Gradle 或 Maven 設定,將 VERSION_NUMBER 預留位置替換為所需 Driver SDK 版本的預留位置。

    Gradle

    將以下內容新增到 build.gradle

    dependencies {
      ...
      implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:[VERSION_NUMBER]'
    }
    

    Maven

    將以下內容新增到 pom.xml

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.libraries.mapsplatform.transportation.driver</groupId>
        <artifactId>transportation-driver</artifactId>
        <version>[VERSION_NUMBER]</version>
      </dependency>
    </dependencies>
    

在應用程式中加入 API 金鑰

在應用程式中加入 Driver SDK 後,請將 API 金鑰加進應用程式。您必須使用在設定開發專案時取得的專案 API 金鑰。

本節將說明如何儲存 API 金鑰,讓應用程式以更安全的方式參照金鑰。您不應在版本管控系統中登錄 API 金鑰。這個檔案應儲存在位於專案根目錄的 local.properties 檔案中。如要進一步瞭解 local.properties 檔案,請參閱「Gradle 屬性檔案」。

如要簡化這項工作,請使用 Secrets Gradle Plugin for Android。請按照這項程序安裝 Secrets Gradle 外掛程式,並安全地儲存 API 金鑰。

  1. 開啟根層級的 build.gradle 檔案,然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

    Groovy

    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
    

    Kotlin

    buildscript {
        dependencies {
            // ...
            classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
        }
    }
    
  2. 開啟應用程式層級的 build.gradle 檔案,然後將下列程式碼加進 plugins 元素。

    Groovy

    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. 將專案與 Gradle 同步處理

  4. 在專案層級目錄中開啟 local.properties 並新增下列程式碼,請務必將 YOUR_API_KEY 替換成您的 API 金鑰。

    MAPS_API_KEY=YOUR_API_KEY
    
  5. 在您的 AndroidManifest.xml 檔案中,前往 com.google.android.geo.API_KEY 並依照下列方式更新 android:value 屬性:

    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
    

以下範例顯示範例應用程式的完整資訊清單:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.driverapidemo" >
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/_AppTheme" >

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${MAPS_API_KEY}" />

        <activity android:name=".MainActivity" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

在應用程式中加入必要的作者資訊

如果您在應用程式中使用 Driver SDK,就必須在應用程式的「法律聲明」一節中加入歸因文字和開放原始碼授權。建議您將歸因納入獨立的選單項目或「關於」選單項目中。

您可以在 Driver SDK ZIP 檔案中找到必要的作者資訊文字和開放原始碼授權:

  • NOTICE.txt
  • LICENSES.txt

依附元件

驅動程式 SDK 會使用 gRPC 與 Fleet Engine 伺服器進行通訊。如果您尚未導入 gRPC,可能需要宣告下列依附元件:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

如果沒有這些依附元件,驅動程式 SDK 在嘗試與 Fleet Engine 伺服器通訊時,會在執行階段發生錯誤。

如果您使用 ProGuard 將建構作業最佳化,可能需要在 ProGuard 設定檔中加入下列幾行內容:

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

支援的最低 API 級別為 21。

初始化 SDK

必須提供提供者 ID (通常為 Google Cloud 專案 ID) 才能初始化 DriverContext 物件。如要進一步瞭解如何設定 Google Cloud 專案,請參閱驗證和授權

使用驅動程式 SDK 前,您必須先初始化 Navigation SDK。如要初始化 SDK:

  1. NavigationApi 取得 Navigator 物件。

    NavigationApi.getNavigator(
        this, // Activity
        new NavigationApi.NavigatorListener() {
          @Override
          public void onNavigatorReady(Navigator navigator) {
            // Keep a reference to the Navigator (used to configure and start nav)
            this.navigator = navigator;
          }
        }
    );
    
  2. 建立 DriverContext 物件,填入必填欄位。

    DriverContext driverContext = DriverContext.builder(application)
        .setProviderId(providerId)
        .setVehicleId(vehicleId)
        .setAuthTokenFactory(authTokenFactory)
        .setNavigator(navigator)
        .setRoadSnappedLocationProvider(
            NavigationApi.getRoadSnappedLocationProvider(application))
        .build();
    
  3. 使用 DriverContext 物件初始化 *DriverApi

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
    
  4. 從 API 物件取得 DeliveryVehicleReporter。(DeliveryVehicleReporter 擴充了 NavigationVehicleReporter)。

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
    

透過 AuthTokenFactory 進行驗證

驅動程式 SDK 產生位置更新時,必須將這些更新傳送至 Fleet Engine 伺服器。為了驗證這些要求,驅動程式 SDK 會呼叫呼叫端提供的 AuthTokenFactory 執行個體。工廠會負責在位置更新時產生驗證權杖。

分別產生權杖的方式,具體取決於每位開發人員的情況。不過,導入程序可能需要:

  • 從 HTTPS 伺服器擷取驗證權杖 (可能採用 JSON 格式)
  • 剖析及快取權杖
  • 權杖過期時重新整理

如要進一步瞭解 Fleet Engine 伺服器預期的權杖,請參閱建立 JSON Web Token (JWT) 以進行授權

以下是 AuthTokenFactory 的架構實作:

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // initially null
  private long expiryTimeMs = 0;

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  @Override
  public String getToken(AuthTokenContext authTokenContext) {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(vehicleId);
    }
    if (ServiceType.VEHICLE.equals(authTokenContext.getServiceType)) {
      return vehicleServiceToken;
    } else {
      throw new RuntimeException("Unsupported ServiceType: " + authTokenContext.getServiceType());
    }
  }

  private void fetchNewToken(String vehicleId) {
    String url = "https://yourauthserver.example/token/" + vehicleId;

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      vehicleServiceToken = obj.get("VehicleServiceToken").getAsString();
      expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      // The expiry time could be an hour from now, but just to try and avoid
      // passing expired tokens, we subtract 10 minutes from that time.
      expiryTimeMs -= 10 * 60 * 1000;
    } catch (IOException e) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw new RuntimeException("Could not get auth token", e);
    }
  }
}

這個特定實作使用內建的 Java HTTP 用戶端,從開發人員的驗證伺服器擷取 JSON 格式的權杖。憑證會保存起來,以便重複使用。如果舊權杖在過期後的 10 分鐘內,系統就會重新擷取權杖。

實作程序可能會採取不同做法,例如透過背景執行緒重新整理權杖。

AuthTokenFactory 中的例外狀況只要重複發生,就會視為暫時。經過多次嘗試後,驅動程式 SDK 會假設該項錯誤永久存在,且將停止嘗試傳送更新。

StatusListener」的狀態和 Error Reporting

由於驅動程式 SDK 在背景執行動作,請使用 StatusListener 在特定事件 (例如錯誤、警告或偵錯訊息) 發生時觸發通知。這些錯誤可能是暫時性的 (例如 BACKEND_CONNECTIVITY_ERROR),也可能使位置更新永久停止 (例如 VEHICLE_NOT_FOUND,表示設定錯誤)。

您可以選擇提供選用的 StatusListener 實作,如下所示:

class MyStatusListener implements StatusListener {
  /** Called when background status is updated, during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

SSL/TLS 注意事項

驅動程式 SDK 實作在內部使用 SSL/TLS,與 Fleet Engine 伺服器安全地進行通訊。舊版 Android (API 版本 21 以下) 可能需要 SecurityProvider 修補程式,才能與伺服器通訊。如要進一步瞭解如何在 Android 中使用 SSL,請參閱這篇文章。此外,本文也會提供程式碼範例,用於修補安全性提供者。

啟用位置更新功能

建立 *VehicleReporter 執行個體後,啟用位置更新非常簡單:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

位置更新會盡可能定期傳送。每次更新位置時,系統也會顯示車輛已連上網路。

根據預設,報表間隔時間為 10 秒。您可以使用 reporter.setLocationReportingInterval(long, TimeUnit) 變更報表間隔。支援的更新間隔下限為 5 秒。更新頻率越高,要求和錯誤可能會變慢。

停用位置更新功能

駕駛作業結束時,您可以呼叫 DeliveryVehicleReporter.disableLocationTracking 來停止位置更新通知。

受信任的模型用途

本節說明如何在使用受信任的模型時,使用驅動程式 SDK 實作常見用途。

建立車輛

您可以透過 Driver SDK 建立車輛。

建立車輛前,請務必初始化 Delivery Driver API。建立車輛 ID 時,必須使用在驅動程式 SDK 初始化期間使用的車輛和供應商 ID。然後建立車輛,如以下範例所示:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

建立運送取貨工作

您可以透過 Driver SDK 建立運送取貨工作。

建立工作之前,請務必初始化 Delivery Driver API。您必須使用驅動程式 SDK 初始化期間指定的提供者 ID 來建立工作。然後建立運送取貨工作,如以下範例所示。如需工作 ID 相關資訊,請參閱工作 ID 範例

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_PICKUP)
   .build();

try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

建立運送任務

你可以透過 Driver SDK 建立運送任務。

建立工作之前,請務必初始化 Delivery Driver API。然後建立出貨工作,如以下範例所示。如需工作 ID 相關資訊,請參閱工作 ID 範例

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

預定無法使用

您可以透過 Driver SDK 建立工作,以指明無法使用 (例如駕駛人故障或車輛輔助)。排定的無法使用時間工作不得包含追蹤 ID。您可以選擇提供地點。

建立工作之前,請務必初始化 Delivery Driver API。然後建立無法使用的工作,如以下範例所示。如需工作 ID 相關資訊,請參閱工作 ID 範例

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
   .setTaskType(TaskType.UNAVAILABLE)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

已排定的停靠站

您可以透過 Driver SDK 建立排定的停止工作。已排定的停止工作可能不包含追蹤 ID。

建立工作之前,請務必初始化 Delivery Driver API。然後建立排定的停止工作,如以下範例所示。如需工作 ID 相關資訊,請參閱工作 ID 範例

static final String TASK_ID = "task-8241890"; //  Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

更新工作排序

您可以從 Driver SDK 更新指派給車輛的執行工作順序。

更新工作排序作業時,也會將先前未指派給車輛的工作指派給車輛。系統也會關閉先前指派給車輛,但未更新訂單的工作。如果某輛車先前已指派給其他車輛,則該工作指派到其他車輛時會發生錯誤。將工作指派給新車輛前,請先關閉現有工作,然後建立新工作。

而且隨時可以更新工作排序。

更新車輛的工作排序之前,請確認已在 Fleet Engine 中建立車輛和工作。然後更新車輛的工作排序,如以下範例所示。

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
try {
   List<VehicleStop> stops = reporter.setVehicleStops(
     ImmutableList.of(
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.ARRIVED)
             .setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
             .setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
             .build(),
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
             .setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
             .setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
             .build(),
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.NEW)
             .setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
             .setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
             .build())).get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
   // errors.
}

可能會發生例外狀況,導致驅動程式 SDK 內部狀態無法更新。在這種情況下,請解決問題,然後再次呼叫 setVehicleStops,直到呼叫成功為止。

潛在問題可能包括:

  • 指定的 VehicleStops 未遵循有效的圖案。只有第一個 CarStop 可以位於任何 VehicleStopStates:NEW、ENROUTE 或 ARRIVED 中。 目前停靠站後的車輛停靠站必須位於新的 VehicleStopState。

  • 工作可能不存在,或是屬於其他車輛。

  • 車輛不存在。

車輛正在前往下一個停靠站

當車輛從停靠站及開始導航時,Fleet Engine 必須收到通知。您可以透過 Driver SDK 通知 Fleet Engine。

在通知 Fleet Engine 有車輛從停靠站出發之前,請確保車輛已經建立及設定停靠站。然後通知 Fleet Engine 車輛的離站,如以下範例所示。

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.

navigator.setDestination(vehicleStop.getWaypoint());
try {
   List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ENROUTE state.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

可能會發生例外狀況,導致驅動程式 SDK 內部狀態無法更新。如果發生這種情況,請解決問題,然後再次呼叫 enrouteToNextStop,直到成功為止。

潛在問題可能包括:

  • 驅動程式 SDK 中未設定剩餘的 VehicleStops

車輛抵達停靠站

當車輛抵達停靠站時,Fleet Engine 必須收到通知。您可以透過 Driver SDK 通知 Fleet Engine。

通知 Fleet Engine 有車輛抵達停靠站前,請確認您已設定車輛停靠站。接著,通知 Fleet Engine 車輛抵達停靠站,如以下範例所示。

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.

try {
   List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ARRIVED state.
   navigator.clearDestinations();
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

可能會發生例外狀況,導致驅動程式 SDK 內部狀態無法更新。如果發生這種情況,請解決問題,然後再次呼叫 arrivedAtStop,直到成功為止。

可能的問題包括:

  • 驅動程式 SDK 中未設定剩餘的 VehicleStops

車輛完成停靠站

當車輛完成停靠站時,Fleet Engine 必須收到通知。這會導致所有與停靠站相關聯的工作都設為「已關閉」狀態。您可以透過 Driver SDK 通知 Fleet Engine。

通知 Fleet Engine 車輛已完成 VehicleStop,如以下範例所示。

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// After completing the tasks at the VehicleStop, remove it from the
// the current list of VehicleStops.

try {
   List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
   // Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
   // Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

可能會發生例外狀況,導致驅動程式 SDK 內部狀態無法更新。如果發生這種情況,請解決問題,然後再次呼叫 completedStop,直到成功為止。

潛在問題可能包括:

  • 驅動程式 SDK 中未設定剩餘的 VehicleStops

關閉工作

如要關閉已指派給車輛的工作,請通知 Fleet Engine 車輛已完成工作的停靠站,或將其從車輛停靠站清單中移除。如要這麼做,您可以將剩餘的車輛清單設為停靠站清單,就像更新車輛的工作排序時一樣。

如果工作尚未指派車輛且必須關閉,請將工作更新為「已關閉」狀態。不過,您無法重新開啟已關閉的工作。

關閉工作不代表作業成功或失敗。這表示工作不再視為進行中。運送追蹤時,請務必指出工作的實際結果,以便顯示運送結果。

您必須為車輛指派工作,才能使用 Driver SDK 關閉工作。如要關閉已指派給車輛的工作,請通知 Fleet Engine 車輛已完成工作的停靠站。

或者,您也可以更新獲派工作的車輛工作排序,然後從停靠站清單中移除需要的工作。

設定工作結果和結果位置

關閉工作不代表作業成功或失敗。這表示工作不再視為進行中。運送追蹤時,請務必指出工作的實際結果,以便顯示運送結果,並為服務提供適當的費用。設定完成後,工作結果即無法變更。不過,您可以在設定工作結果時間和工作結果位置後修改這些資訊。

狀態為「已關閉」的工作可將結果設定為「成功」或「失敗」。Fleet Engine 只會針對狀態為「成功」的傳遞工作收取費用。

標記工作的結果時,Fleet Engine 會將工作結果位置自動填入最後已知車輛位置。您可以覆寫這個行為。

以下範例說明如何使用 Driver SDK 設定工作結果和時間戳記。您無法使用 Driver SDK 設定工作結果位置,

static final String TASK_ID = "task-8241890";

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();

// Updating an existing DeliveryTask which is already CLOSED. Manually
// setting TaskOutcomeLocation with Driver SDK is not supported at this time.
UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
    .setTaskOutcome(TaskOutcome.SUCCEEDED)
    .setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
    .build();

try {
   DeliveryTask updatedTask = taskManager.updateTask(req);
   // Handle UpdateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle UpdateTaskRequest error.
}

查詢車輛

您可以透過 Driver SDK 查詢車輛,查詢車輛之前,請務必初始化 Delivery Driver API。接著,您就可以按照以下範例查詢車輛。

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
   DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
   // Handle GetVehicleRequest DeliveryVehicle response.
} catch (Exception e)  {
   // Handle GetVehicleRequest error.
}

DeliveryVehicleManager 只能查詢 DeliveryVehicle 來尋找在推送驅動程式 API 初始化期間提供的車輛 ID。