Developer

Online services

Request Access
Version: 0.5.0

介绍

本教程将指导您完成访问管理的配置过程。
要访问 TomTom Online Services，ANA 需要一个 JSON Web Token (JWT)。
TomTom 的访问管理服务（AMS）通过这些访问令牌管理对 TomTom Online Services 的访问。

前提条件

在设置访问管理之前，请确保：

  1. 您已将以下完全限定域名（FQDN）列入白名单，以允许与 TomTom 服务通信：

    • api.tomtom.com
    • .hosteddelivery.tomtom.com（hosteddelivery.tomtom.com 的所有子域）
    • dcas.tomtom.com
    • dcas-hub-01-westeu-prd.azure-devices.net
    • 您从 TomTom 代表处获得的 AMS 部署的 FQDN（见下文）

  2. 您已开放以下出站端口：

    • 443 – 用于 REST API 的安全 HTTPS 通信。
    • 8883 – 用于安全 MQTT 通信。

选择访问管理方式

根据您的开发阶段，您可以选择使用评估访问令牌，或连接您的身份和访问管理（IAM）服务来生成 JWT 令牌。
以下章节详细说明了这两种方案。

使用评估访问令牌

AMS 提供了一个专用的评估部署用于评估目的。
该部署允许您使用预定义的评估访问令牌。

如果您正在评估 ANA，请联系您的 TomTom 代表以获取评估访问令牌和 AMS 评估部署的 FQDN。
获得评估访问令牌后，您可以使用 Vehicle Integration Test App 将令牌和 AMS FQDN 配置到 ANA。

Access Management - Evaluation

集成您的身份和访问管理服务

如果您将 ANA 嵌入到车载信息娱乐系统中，则需要为每辆车或用户管理身份。
并且，一旦认证成功，颁发带有所需声明集的 JWT 令牌。

AMS 的专用部署将与您的 IAM 服务集成，并使用此令牌对 TomTom Online Services 的请求进行身份验证。

Access Management - Development

请联系您的 TomTom 代表以：

  • 将您的身份提供者接入我们的访问管理服务。
  • 获取专用 AMS 部署的 FQDN。
  • 了解 JWT 令牌中所需的声明，以满足汽车导航应用的要求。

向 ANA 配置访问令牌

Vehicle Integration Library (VIL) 提供了设置访问令牌和 AMS FQDN 到 ANA 的方法。
请参阅 Vehicle integration basics 了解如何将 VIL 集成到您的应用中。

集成 VIL 后，使用其 OnlineServicesManager 配置访问令牌和 AMS FQDN。

第 1 步：创建 OnlineServicesTokenParameters 实例

使用您的访问令牌创建 OnlineServicesTokenParameters 实例：

1import com.tomtom.automotive.integration.vehicle.client.api.onlineServices.authentication.OnlineServicesTokenParameters
2

3val tokenParameters = OnlineServicesTokenParameters(
4    authenticationToken = "your.access.token"
5)
第 2 步：创建 OnlineServicesConfigurationParameters 实例

使用 AMS 部署的 FQDN 创建 OnlineServicesConfigurationParameters 实例：

1import com.tomtom.automotive.integration.vehicle.client.api.onlineServices.configuration.OnlineServicesConfigurationParameters
2

3val configParameters = OnlineServicesConfigurationParameters(
4    onlineServicesFQDN = "your.ams.fqdn"
5)
第 3 步：设置访问令牌

使用 vilClient 设置访问令牌：

1vilClient.getOnlineServicesManager().setAuthenticationToken(
2    tokenParameters,
3    object : OnlineServicesCallback {
4        override fun onResult(result: Result<VehicleSpecsParameters, VehicleSpecsFailure>) {
5            if (result is Result.Failure) {
6                if (result.reason == OnlineServicesFailure.FAILED_TO_SET_TOKEN) {
7                    // 处理令牌设置失败
8                } else {
9                    // 处理其他失败情况
10                }
11            } else {
12                // 访问令牌设置成功
13            }
14        }
15    })

设置认证令牌时，可能出现以下错误：

  • FAILED_TO_SET_TOKEN：令牌无法设置。可能由于网络问题或令牌格式无效等原因。
  • UNHANDLED：发生了意外错误。

请确保在回调实现中妥善处理这些错误。

第 4 步：设置 FQDN

使用 vilClient 设置 FQDN：

1vilClient.getOnlineServicesManager().setOnlineServicesConfiguration(
2    configParameters,
3    object : OnlineServicesCallback {
4        override fun onResult(result: Result<VehicleSpecsParameters, VehicleSpecsFailure>) {
5            if (result is Result.Failure) {
6                if (result.reason == OnlineServicesFailure.FAILED_TO_SET_CONFIGURATION) {
7                    // 处理 FQDN 设置失败
8                } else {
9                    // 处理其他失败情况
10                }
11            } else {
12                // FQDN 设置成功
13            }
14        }
15    })

设置 FQDN 时，可能出现以下错误：

  • FAILED_TO_SET_CONFIGURATION：配置无法设置。可能由于网络问题。
  • INVALID_FQDN_FORMAT：提供的 FQDN 格式无效。
  • UNHANDLED：发生了意外错误。

请确保在回调实现中妥善处理这些错误。

最佳实践和注意事项

在开发身份访问管理（IAM）客户端与汽车导航应用之间的集成时，
请考虑以下最佳实践，以确保顺畅且高效的体验：

  • 确保车辆 IAM 客户端能够成功通过您的 IAM 服务对车辆进行身份验证，以请求有效的令牌。理想情况下，该令牌应在设备启动时生成，并可随时供我们的应用使用。
  • 有效管理令牌过期，确保汽车导航应用中使用的令牌保持有效。实现检查机制，防止在令牌刷新过程中出现竞态条件，尤其是在与 IAM 服务交互时。
  • 确保 API 异步运行，以提升响应速度。

通过遵循这些关键注意事项，您可以提升集成的可靠性和效率，确保最终用户获得无缝的体验。