Giải pháp cuối cùng của đội xe hiện chỉ dành cho một số khách hàng. Liên hệ với bộ phận bán hàng để tìm hiểu thêm.

Bắt đầu với SDK Trình điều khiển dành cho Android

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.

Yêu cầu tối thiểu về hệ thống

Thiết bị di động phải chạy Android 5.0 (API cấp 21) trở lên.

Điều kiện tiên quyết

Hướng dẫn này giả định ứng dụng của bạn đã triển khai SDK điều hướng và phần phụ trợ Fleet Engine đã được thiết lập và sẵn có.

SDK trình điều khiển cho Android được phát hành lên kho lưu trữ Maven của Artifact Registry. Kho lưu trữ bao gồm các tệp Mô hình đối tượng dự án (.pom) của SDK và Javadocs ngoại tuyến.

Nhận quyền truy cập

Nếu bạn là khách hàng Google Workspace, hãy tạo một Nhóm Workspace (chẳng hạn như google-maps-platform-sdk-users@workspacedomain.com) trong quá trình giới thiệu và cung cấp tên cho Google. Chúng tôi đề xuất phương pháp này. Sau đó, Nhóm Workspace của bạn sẽ được thêm vào danh sách cho phép cấp quyền truy cập vào kho lưu trữ Maven gmp-artifacts/transportation. Xác nhận rằng email người dùng và email tài khoản dịch vụ cần quyền truy cập có trong danh sách này.

Nếu tổ chức của bạn không thể tạo Nhóm Workspace, hãy gửi cho Google một danh sách email tài khoản người dùng và dịch vụ cần quyền truy cập vào các cấu phần phần mềm này.

Phát triển địa phương

Để phát triển cục bộ, bạn chỉ cần đăng nhập bằng SDK SDK.

đám mây

gcloud auth login

Email dùng để đăng nhập phải là một thành viên của Nhóm Workspace.

Tự động hoá (hệ thống xây dựng hoặc tích hợp liên tục)

Thiết lập máy chủ lưu trữ tự động theo các phương pháp hay nhất:

  • Nếu quy trình chạy trong môi trường Google Cloud, hãy sử dụng tính năng phát hiện thông tin xác thực tự động.

  • Nếu không, hãy lưu trữ tệp khoá tài khoản dịch vụ ở một vị trí an toàn trên hệ thống tệp của máy chủ và đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS cho phù hợp.

Email của tài khoản dịch vụ liên kết với thông tin xác thực phải là một thành viên của Nhóm Workspace.

Cấu hình

Định cấu hình Maven hoặc Gradle để tự động phát hiện thông tin đăng nhập của người dùng hoặc dịch vụ.

Gradle

Thêm mã sau vào tệp build.gradle của mô-đun ứng dụng, không phải tệp build.gradle của mô-đun gốc của dự án:

  plugins {
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
  }
  repositories {
    maven {
      url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
  }

Maven

Thêm nội dung sau vào pom.xml của bạn:

  <repositories>
    <repository>
      <id>gmp-artifacts</id>
      <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
  </repositories>
  <build>
    <extensions>
      <extension>
        <groupId>com.google.cloud.artifactregistry</groupId>
        <artifactId>artifactregistry-maven-wagon</artifactId>
        <version>2.1.0</version>
      </extension>
    </extensions>
  </build>

Để biết thông tin về cách xác minh quyền truy cập, hãy xem phần Quản lý gói Java.

Cấu hình dự án

Để sử dụng SDK trình điều khiển, ứng dụng của bạn phải nhắm đến minSdkVersion 21 trở lên. Để biết thêm thông tin, hãy xem Ghi chú phát hành.

Để chạy một ứng dụng được xây dựng bằng SDK Trình điều khiển, thiết bị Android phải cài đặt Dịch vụ Google Play.

Thiết lập dự án phát triển của bạn

Cách thiết lập dự án phát triển và nhận khoá API cho dự án trên Google Cloud Console:

  1. Tạo một dự án Google Cloud Console mới hoặc chọn một dự án hiện có để sử dụng với SDK Trình điều khiển. Chờ vài phút cho đến khi dự án mới xuất hiện trên Google Cloud Console.

  2. Để chạy ứng dụng minh hoạ, dự án của bạn phải có quyền truy cập vào SDK Maps dành cho Android. Trong Google Cloud Console, hãy chọn API và dịch vụ & gt; Thư viện, sau đó tìm và bật SDK bản đồ dành cho Android.

  3. Tải khoá API cho dự án bằng cách chọn API & Dịch vụ > Thông tin xác thực > Tạo thông tin xác thực > Khoá API. Để biết thêm thông tin về cách nhận khoá API, hãy xem phần Nhận khoá API.

Thêm Trình điều khiển SDK vào ứng dụng của bạn

SDK trình điều khiển có sẵn qua kho lưu trữ Maven riêng tư. Kho lưu trữ bao gồm các tệp Mô hình đối tượng dự án (.pom) của SDK và Javadocs. Cách thêm SDK Trình điều khiển vào ứng dụng:

  1. Thiết lập môi trường để truy cập vào kho lưu trữ Maven lưu trữ như được mô tả trong phần Cấu hình.

  2. Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven của bạn, thay thế phần giữ chỗ VERSION_NUMBER cho phiên bản SDK trình điều khiển mong muốn.

    Gradle

    Thêm nội dung sau vào build.gradle của bạn:

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

    Maven

    Thêm nội dung sau vào pom.xml của bạn:

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

Thêm khoá API vào ứng dụng

Sau khi thêm SDK Trình điều khiển vào ứng dụng, hãy thêm khoá API vào ứng dụng. Bạn phải sử dụng khoá API dự án mà bạn nhận được khi thiết lập dự án phát triển.

Phần này mô tả cách lưu trữ khoá API để ứng dụng có thể tham chiếu một cách an toàn hơn. Bạn không nên kiểm tra khoá API vào hệ thống quản lý phiên bản. Bạn nên lưu trữ tệp này trong tệp local.properties nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp local.properties, hãy xem các tệp thuộc tính Gradle.

Để đơn giản hóa tác vụ này, hãy sử dụng Trình bổ trợ Gradle cho Android. Làm theo quy trình này để cài đặt trình bổ trợ Secrets Gradle và lưu trữ an toàn khoá API của bạn.

  1. Mở tệp build.gradle gốc và thêm mã sau vào phần tử dependencies trong buildscript.

    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. Mở tệp build.gradle cấp ứng dụng và thêm mã sau vào phần tử plugins.

    Groovy

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

    Kotlin

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. Đồng bộ hóa dự án với Gradle.

  4. Mở local.properties trong thư mục cấp dự án, sau đó thêm mã sau. Hãy nhớ thay thế YOUR_API_KEY bằng khoá API.

    MAPS_API_KEY=YOUR_API_KEY
    
  5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY và cập nhật thuộc tính android:value như sau:

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

Ví dụ sau đây cho thấy một tệp kê khai đầy đủ cho một ứng dụng mẫu:

<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>

Cung cấp các thuộc tính bắt buộc trong ứng dụng của bạn

Nếu sử dụng SDK trình điều khiển trong ứng dụng của mình, bạn phải bao gồm văn bản phân bổ và giấy phép nguồn mở như một phần trong phần thông báo pháp lý của ứng dụng. Bạn nên đưa các thuộc tính vào dưới dạng một mục trong trình đơn độc lập hoặc dưới dạng một phần của mục trong trình đơn Giới thiệu.

Bạn có thể tìm thấy văn bản phân bổ bắt buộc và giấy phép nguồn mở trong tệp zip SDK Drive:

  • NOTICE.txt
  • LICENSES.txt

Phần phụ thuộc

SDK của trình điều khiển sử dụng gRPC để giao tiếp với máy chủ Fleet Engine. Nếu chưa đưa gRPC vào, bạn có thể cần khai báo các phần phụ thuộc sau:

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

Nếu không có các phần phụ thuộc này, SDK trình điều khiển sẽ gặp lỗi trong thời gian chạy khi cố gắng giao tiếp với máy chủ Fleet Engine.

Nếu sử dụng ProGuard để tối ưu hoá các bản dựng, bạn có thể cần phải thêm các dòng sau vào tệp cấu hình ProGuard:

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

Cấp độ API tối thiểu được hỗ trợ là 21.

Khởi chạy SDK

Bạn cần có mã nhà cung cấp (thường là Mã dự án trên Google Cloud) để khởi chạy đối tượng DriverContext. Để biết thêm thông tin về việc thiết lập Dự án Google Cloud, hãy xem phần Xác thực và uỷ quyền.

Trước khi sử dụng SDK trình điều khiển, trước tiên, bạn phải khởi chạy SDK điều hướng. Cách khởi chạy SDK:

  1. Lấy một đối tượng Navigator từ NavigationApi.

    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. Tạo một đối tượng DriverContext, điền vào các trường bắt buộc.

    DriverContext driverContext = DriverContext.builder(application)
        .setProviderId(providerId)
        .setVehicleId(vehicleId)
        .setAuthTokenFactory(authTokenFactory)
        .setNavigator(navigator)
        .setRoadSnappedLocationProvider(
            NavigationApi.getRoadSnappedLocationProvider(application))
        .build();
    
  3. Sử dụng đối tượng DriverContext để khởi tạo *DriverApi.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
    
  4. Nhận DeliveryVehicleReporter từ đối tượng API. (DeliveryVehicleReporter mở rộng NavigationVehicleReporter.)

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
    

Xác thực bằng AuthTokenFactory

Khi SDK Trình điều khiển tạo thông báo cập nhật vị trí, SDK phải gửi các bản cập nhật này đến máy chủ Fleet Engine. Để xác thực các yêu cầu này, SDK trình điều khiển sẽ gọi đến bản sao AuthTokenFactory do người gọi cung cấp. Nhà máy chịu trách nhiệm tạo mã xác thực tại thời điểm cập nhật thông tin vị trí.

Chính xác cách tạo mã thông báo sẽ dành riêng cho tình huống của từng nhà phát triển. Tuy nhiên, việc triển khai có thể sẽ cần:

  • tìm nạp mã thông báo xác thực, có thể ở định dạng JSON, từ máy chủ HTTPS
  • phân tích cú pháp và lưu mã thông báo vào bộ nhớ đệm
  • làm mới mã thông báo khi mã hết hạn

Để biết thông tin chi tiết về mã thông báo mà máy chủ Fleet Engine dự kiến, hãy xem bài viết Tạo mã thông báo web JSON (JWT) để uỷ quyền.

Dưới đây là cách triển khai khung cho 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);
    }
  }
}

Cách triển khai cụ thể này sử dụng ứng dụng HTTP Java tích hợp sẵn để tìm nạp mã thông báo ở định dạng JSON từ máy chủ xác thực của nhà phát triển. Mã thông báo được lưu để sử dụng lại. Mã thông báo này sẽ được tìm nạp lại nếu mã thông báo cũ nằm trong vòng 10 phút kể từ khi hết hạn.

Quá trình triển khai có thể làm khác, chẳng hạn như sử dụng luồng trong nền để làm mới mã thông báo.

Các ngoại lệ trong AuthTokenFactory sẽ được coi là tạm thời, trừ khi ngoại lệ đó lặp lại nhiều lần. Sau một số lần thử, SDK trình điều khiển sẽ giả định rằng lỗi đó có hiệu lực vĩnh viễn và sẽ ngừng cố gắng gửi các bản cập nhật.

Báo cáo trạng thái và lỗi bằng StatusListener

Vì SDK trình điều khiển thực hiện các hành động trong nền, hãy sử dụng StatusListener để kích hoạt thông báo khi một số sự kiện xảy ra, chẳng hạn như lỗi, cảnh báo hoặc thông báo gỡ lỗi. Các lỗi có thể có tính chất tạm thời (chẳng hạn như BACKEND_CONNECTIVITY_ERROR) hoặc có thể khiến thông tin cập nhật vị trí bị dừng vĩnh viễn (chẳng hạn như VEHICLE_NOT_FOUND, cho biết lỗi cấu hình).

Bạn có thể triển khai StatusListener không bắt buộc như sau:

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.
  }
}

Ghi chú về SSL/TLS

Trong nội bộ, quá trình triển khai SDK trình điều khiển sử dụng SSL/TLS để giao tiếp an toàn với máy chủ Fleet Engine. Các phiên bản Android cũ (API phiên bản 21 trở xuống) có thể cần một bản vá SecurityProvider để có thể giao tiếp với máy chủ. Bạn nên xem bài viết này để biết thêm thông tin về cách làm việc với SSL trong Android. Bài viết này cũng chứa các mã mẫu để vá nhà cung cấp dịch vụ bảo mật.

Đang bật cập nhật vị trí

Sau khi bạn có một phiên bản *VehicleReporter, việc bật tính năng cập nhật vị trí sẽ đơn giản:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Các bản cập nhật vị trí sẽ được gửi định kỳ, nếu có thể. Mỗi lượt cập nhật vị trí cũng sẽ cho biết xe đang kết nối mạng.

Theo mặc định, khoảng thời gian báo cáo là 10 giây. Bạn có thể thay đổi khoảng thời gian báo cáo bằng reporter.setLocationReportingInterval(long, TimeUnit). Khoảng thời gian cập nhật tối thiểu được hỗ trợ là 5 giây. Việc thường xuyên cập nhật có thể dẫn đến yêu cầu và lỗi chậm hơn.

Tắt thông báo cập nhật vị trí

Khi tài xế đã chuyển xong, bạn có thể dừng cập nhật vị trí bằng cách gọi DeliveryVehicleReporter.disableLocationTracking.

Các trường hợp sử dụng mô hình đáng tin cậy

Phần này mô tả cách sử dụng SDK trình điều khiển để triển khai các trường hợp sử dụng phổ biến khi sử dụng mô hình tin cậy.

Tạo xe

Bạn có thể tạo xe từ SDK trình điều khiển.

Trước khi tạo xe, hãy nhớ khởi chạy API Trình điều khiển phân phối. Bạn phải tạo mã xe với mã xe và mã nhà cung cấp dùng trong quá trình khởi chạy SDK trình điều khiển. Sau đó, hãy tạo xe như trong ví dụ sau:

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

Tạo nhiệm vụ nhận hàng

Bạn có thể tạo nhiệm vụ đến lấy hàng từ SDK trình điều khiển.

Trước khi tạo tác vụ, hãy nhớ khởi chạy API Trình điều khiển phân phối. Tác vụ phải được tạo bằng mã nhà cung cấp đã chỉ định trong quá trình khởi chạy SDK trình điều khiển. Sau đó, tạo nhiệm vụ đến lấy hàng theo cách như trong ví dụ sau. Để biết thông tin về mã việc cần làm, hãy xem Ví dụ về mã việc cần làm.

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.
}

Tạo nhiệm vụ giao hàng

Bạn có thể tạo nhiệm vụ phân phối lô hàng từ SDK trình điều khiển.

Trước khi tạo tác vụ, hãy nhớ khởi chạy API Trình điều khiển phân phối. Sau đó, tạo nhiệm vụ giao hàng như trong ví dụ sau. Để biết thông tin về mã tác vụ, hãy xem Ví dụ về mã tác vụ.

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.
}

Tình trạng không có sẵn theo lịch

Bạn có thể tạo một nhiệm vụ cho biết tình trạng không hoạt động (ví dụ: đối với điểm ngắt trình điều khiển hoặc khi tiếp nhiên liệu xe) từ SDK trình điều khiển. Nhiệm vụ không có sẵn theo lịch không được bao gồm mã theo dõi. Bạn có thể cung cấp vị trí nếu muốn.

Trước khi tạo tác vụ, hãy nhớ khởi chạy API Trình điều khiển phân phối. Sau đó, tạo nhiệm vụ không có sẵn như trong ví dụ sau. Để biết thông tin về mã tác vụ, hãy xem Ví dụ về mã tác vụ.

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.
}

Điểm dừng đã lên lịch

Bạn có thể tạo một nhiệm vụ dừng đã lên lịch từ SDK Trình điều khiển. Nhiệm vụ dừng đã lên lịch có thể không bao gồm mã theo dõi.

Trước khi tạo tác vụ, hãy nhớ khởi chạy API Trình điều khiển phân phối. Sau đó, tạo việc cần làm đã dừng theo lịch như trong ví dụ sau. Để biết thông tin về mã tác vụ, hãy xem Ví dụ về mã tác vụ.

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.
}

Cập nhật thứ tự việc cần làm

Bạn có thể cập nhật thứ tự thực thi của các nhiệm vụ được giao cho xe từ SDK trình điều khiển.

Khi cập nhật thứ tự tác vụ, bạn cũng sẽ chỉ định tác vụ cho một xe nếu trước đây chưa được giao cho xe. Nó cũng đóng các tác vụ đã được chỉ định trước đó cho một xe và không còn trong thứ tự cập nhật. Việc giao một nhiệm vụ cho một xe khác nếu trước đó đã được giao cho một xe khác sẽ gây ra lỗi. Trước khi giao việc cần làm cho xe mới, hãy đóng thao tác hiện có rồi tạo việc cần làm mới.

Bạn có thể cập nhật thứ tự việc cần làm bất cứ lúc nào.

Trước khi cập nhật thứ tự nhiệm vụ cho xe, hãy đảm bảo rằng xe và các nhiệm vụ đã được tạo trong Fleet Engine. Sau đó, hãy cập nhật thứ tự tác vụ cho xe như trong ví dụ sau.

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.
}

Một ngoại lệ có thể xảy ra có thể ngăn cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu điều này xảy ra, hãy giải quyết vấn đề rồi gọi lại setVehicleStops cho đến khi cuộc gọi thành công.

Các vấn đề tiềm ẩn có thể bao gồm:

  • Các Điểm dừng xe đã chỉ định không tuân theo mẫu hợp lệ. Chỉ Xe Stop đầu tiên có thể nằm ở bất kỳ xe nào StopStates: NEW, ENROUTE hoặc Destination. Các Điểm dừng Xe sau điểm dừng hiện tại phải ở trong Trạng thái Xe mới.

  • Việc cần làm không tồn tại hoặc việc đó thuộc về một phương tiện khác.

  • Xe này không tồn tại.

Xe đang trên đường đến điểm dừng tiếp theo

Fleet Engine phải được thông báo khi một phương tiện khởi hành từ điểm dừng và khi bắt đầu đi theo chỉ dẫn. Bạn có thể thông báo cho Fleet Engine từ SDK Driver.

Trước khi thông báo cho Fleet Engine rằng một phương tiện đã khởi hành từ điểm dừng, hãy đảm bảo rằng xe đó đã được tạo và đặt xong. Sau đó, hãy thông báo cho Fleet Engine về việc khởi hành của xe như trong ví dụ sau.

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.
}

Một ngoại lệ có thể xảy ra có thể ngăn cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu cách này xảy ra, hãy giải quyết vấn đề rồi gọi lại enrouteToNextStop cho đến khi thành công.

Các vấn đề tiềm ẩn có thể bao gồm:

  • Không có VehicleStops còn lại nào được đặt trong SDK trình điều khiển.

Xe dừng tại một điểm dừng

Bạn phải thông báo cho Fleet Engine khi xe dừng lại ở một trạm dừng. Bạn có thể thông báo cho Fleet Engine từ SDK Driver.

Trước khi thông báo cho Fleet Engine rằng xe đã đến điểm dừng, hãy đảm bảo rằng bạn đã đặt xe dừng. Sau đó, hãy thông báo cho Fleet Engine về đích đến của xe tại điểm dừng như trong ví dụ sau.

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.
}

Một ngoại lệ có thể xảy ra có thể ngăn cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu cách này xảy ra, hãy giải quyết vấn đề rồi gọi lại arrivedAtStop cho đến khi thành công.

Các vấn đề tiềm ẩn có thể bao gồm:

  • Không có VehicleStops còn lại nào được đặt trong SDK trình điều khiển.

Xe hoàn thành điểm dừng

Bạn phải thông báo cho Fleet Engine khi một phương tiện đã hoàn thành điểm dừng. Điều này khiến tất cả các tác vụ liên kết với điểm dừng được đặt thành trạng thái ĐÓNG. Bạn có thể thông báo cho Fleet Engine từ SDK Driver.

Thông báo cho Fleet Engine rằng chiếc xe này đã hoàn tất công cụ XeStop như trong ví dụ sau.

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.
}

Một ngoại lệ có thể xảy ra có thể ngăn cập nhật trạng thái nội bộ của SDK trình điều khiển. Nếu cách này xảy ra, hãy giải quyết vấn đề rồi gọi lại completedStop cho đến khi thành công.

Các vấn đề tiềm ẩn có thể bao gồm:

  • Không có VehicleStops còn lại nào được đặt trong SDK trình điều khiển.

Đóng một việc cần làm

Để đóng một nhiệm vụ đã được chỉ định cho một xe, hãy thông báo cho Fleet Engine rằng xe đó đã hoàn tất điểm dừng nơi nhiệm vụ diễn ra hoặc xoá nó khỏi danh sách điểm dừng của xe. Để thực hiện việc này, bạn có thể đặt danh sách các phương tiện còn lại dừng tương tự như khi cập nhật thứ tự nhiệm vụ cho một xe.

Nếu một tác vụ chưa được giao cho xe và cần đóng, hãy cập nhật tác vụ thành trạng thái ĐÃ KHOÁ. Tuy nhiên, bạn không thể mở lại một việc cần làm ĐÃ ĐÓNG CỬA.

Đóng một nhiệm vụ không cho biết kết quả thành công hay không. Nó cho biết tác vụ không còn được xem xét đang tiến hành. Đối với tính năng theo dõi quá trình vận chuyển, điều quan trọng là bạn phải cho biết kết quả thực tế của một nhiệm vụ để có thể hiển thị kết quả phân phối.

Một nhiệm vụ phải được giao cho một xe để có thể sử dụng SDK trình điều khiển để đóng nhiệm vụ đó. Để đóng một nhiệm vụ đã được giao cho một phương tiện, hãy thông báo cho Fleet Engine rằng phương tiện đó đã hoàn tất điểm dừng thực hiện nhiệm vụ.

Ngoài ra, bạn có thể cập nhật thứ tự việc cần làm của xe được giao việc cần làm, sau đó xóa việc cần làm mà bạn muốn khỏi danh sách điểm dừng.

Đặt kết quả tác vụ và vị trí kết quả

Đóng một nhiệm vụ không cho biết kết quả thành công hay không. Nó cho biết tác vụ không còn được xem xét đang tiến hành. Để theo dõi quá trình vận chuyển, điều quan trọng là phải cho biết kết quả thực tế của một nhiệm vụ để có thể hiển thị kết quả phân phối, cũng như để quy trình này có thể thanh toán đúng cách cho các dịch vụ. Sau khi đặt, bạn không thể thay đổi kết quả tác vụ. Tuy nhiên, bạn có thể sửa đổi thời gian và kết quả của nhiệm vụ sau khi đã đặt.

Kết quả của những tác vụ đang ở trạng thái ĐÃ ĐÓNG có thể được đặt thành Metadata hoặc CHƯA. Chỉ những tác vụ đến lấy hàng và giao hàng có trạng thái ISRC mới được thanh toán.

Khi đánh dấu kết quả của một nhiệm vụ, Fleet Engine sẽ tự động điền vị trí kết quả nhiệm vụ bằng vị trí xe đã biết gần đây nhất. Bạn có thể ghi đè hành vi này.

Ví dụ sau đây cho bạn biết cách sử dụng SDK trình điều khiển để đặt kết quả tác vụ và dấu thời gian. Bạn không thể đặt vị trí kết quả của việc cần làm bằng SDK Trình điều khiển.

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.
}

Nhìn lên xe

Bạn có thể tra cứu xe từ SDK trình điều khiển. Trước khi tìm xe, hãy đảm bảo rằng bạn khởi chạy API Trình điều khiển phân phối. Sau đó, bạn có thể tra cứu xe như trong ví dụ sau.

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 chỉ có thể tra cứu DeliveryVehicle cho mã xe được cung cấp trong quá trình khởi chạy API Trình điều khiển phân phối.