设置 Navigation Connect

欧洲经济区 (EEA) 开发者

本文档介绍了开始使用 Navigation Connect 所需执行的步骤。

前提条件

本指南介绍了如何设置 Google Cloud 账号和 Google Cloud 云项目并启用结算功能。您还应熟悉 Navigation Connect API 的收费方式。

  1. 在导航连接用量和结算中查看用量的结算和费用。
  2. 验证您是否拥有 Google Cloud 账号。

    登录 Google Cloud 控制台
  3. 验证您是否拥有已启用结算功能的 Google Cloud 项目。

    前往“结算”页面
    1. 选择您的项目以打开结算页面。
    2. 在结算页面上:

      • 如果所选项目已启用结算功能,并且您只有一个结算账号,则系统会打开结算页面。
      • 如果您有多个结算账号,请选择转至关联的结算账号,查看与项目关联的结算账号的相关详情。
      • 如果存在结算账号,但未与项目关联,系统会提示您将结算账号与项目关联。
      • 如果不存在结算账号,或者您想创建新的结算账号,请选择管理结算账号以创建新的结算账号。如需了解详情,请参阅创建新的自助 Cloud Billing 账号。

启用 API 并验证应用

本指南介绍了在 Google Cloud 控制台中启用 Navigation Connect API 并验证应用的过程,以便您的应用能够安全地与 Google 地图和 Waze 交互。您必须完成此流程才能使用 Navigation Connect API。

1. 启用 Navigation Connect API

使用 Google Cloud 控制台或 gcloud 命令在 Google Cloud 云项目中启用 Navigation Connect API。

如需启用 API,请执行以下步骤:

控制台

  1. 在 Google Cloud 控制台中打开产品页面:

    启用 Navigation Connect API
  2. 点击启用按钮。

gcloud

gcloud services enable \
    --project "PROJECT" \
    "navigationconnect.googleapis.com"

详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令:

2. 启动应用验证流程

启用 API 后,您必须验证应用才能激活 Navigation Connect API。 仅启用 API 并不意味着您已获得访问权限;您必须提供商家和应用详细信息以供审核,然后才能使用 Navigation Connect API。

如需启动验证流程,请使用以下任一方法:

  • API Marketplace:
    1. 在 API Marketplace 中,找到 Navigation Connect API 卡片。
    2. 点击蓝色的 需要验证图标,开始验证流程。
  • Google Cloud 控制台中的“密钥和凭证”:
    1. 在 Google Cloud 控制台中,前往密钥和凭据页面。
    2. 点击 Navigation Connect 密钥和凭证。
    3. 在横幅中,点击开始验证。

3. 提供应用、数据收集和隐私权详细信息

下表介绍了您必须为应用验证提供的详细信息:

字段 说明
应用详细信息

请提供以下详细信息,以确保您的应用在 Google 地图和 Waze 中正确显示。

商家或应用名称 输入要在 Google 地图和 Waze 中向用户显示的名称。
应用标识符 提供您的 Android 软件包名称或 iOS 软件包 ID。
iOS 通用链接 提供可让用户返回您的应用的 iOS 通用链接(仅适用于 Waze)。
应用徽标(仅限 Waze) (可选)上传 PNG 或 JPG 格式的徽标(32x32 到 128x128 像素),以便在导航期间在 Waze 中显示您的应用徽标。
数据收集和隐私权详情

请输入以下详细信息,以确保透明度、司机信任度和数据安全。

隐私权政策链接 提供指向您应用的隐私权政策的网址。此链接会显示在权限请求页面上。
其他数据控制方(可选) 提供任何第三方数据管理者(例如 ISV)的商业名称和隐私权政策链接。这些详细信息会显示在权限请求页面上。
数据合规性 如果您的应用在美国境内运营,请选中此应用将用于处理美国境内的行程复选框,以确保符合当地法规。

4. 检查并提交

在提交应用进行验证之前,请先查看您提供的信息摘要。

  1. 仔细检查应用名称、平台、ID 和链接。

  2. 选中所有信息均准确无误复选框。
  3. 点击提交。

提交应用进行验证后,审核阶段即会开始。

  • 时间安排:验证通常需要 1-3 个工作日。
  • 通知:当验证状态发生变化时,您会收到一封邮件。您还会收到一封电子邮件,要求您提供支付资料 ID 或 Android 开发者 ID。如果您需要 Android 开发者 ID,请参阅创建开发者账号。
  • 状态跟踪:在 Google Cloud 控制台的密钥和凭证页面上监控您的进度。
  • 支持:如需在获得批准后更新配置而不影响生产环境,请创建支持服务工单。

验证通过后,您的应用便有权使用 Navigation Connect API 生成行程令牌,这些令牌可授权访问导航会话,并让您能够从 Google 地图和 Waze 接收行程详情。

Google Maps Platform 产品要求 API 调用包含 OAuth 令牌,以防止未经授权的使用。

创建 OAuth 令牌

Navigation Connect 支持使用 OAuth 2.0 进行身份验证。Google 支持常见的 OAuth 2.0 场景,例如 Web 服务器场景。

本文档介绍了如何在开发环境中将 OAuth 令牌传递给 Navigation Connect 调用。如需详细了解如何在生产环境中使用 OAuth,请参阅 Google 的身份验证方法。

您可以直接通过向服务器发出 API 请求来调用 Google 地图 API,也可以使用客户端库来简化代码。Google 地图提供适用于 Go、Java、Node.js 和 Python 的客户端库。如需了解详情,请参阅Navigation Connect 客户端库。

OAuth 概览

您可以通过多种方式使用 OAuth 创建和管理访问令牌,具体取决于您的部署环境。

您可以使用 OAuth 2.0 在应用与 Google 服务之间进行服务器到服务器的交互。对于此场景,您使用的是与应用(而非个别用户)关联的服务账号。您可以使用服务账号发出 API 请求,而无需用户直接参与。如需详细了解身份验证方法,请参阅 Google 的身份验证方法。

或者,您也可以将 Navigation Connect 集成到 Android 或 iOS 移动应用中。如需详细了解如何使用 OAuth 以及如何管理不同部署环境的访问令牌,请参阅使用 OAuth 2.0 访问 Google API。

OAuth 范围

如需将 OAuth 与 Navigation Connect 搭配使用,您必须为 OAuth 令牌分配以下范围:

https://www.googleapis.com/auth/cloud-platform

示例:在本地开发环境中尝试 REST API 调用

如果您没有生成令牌的环境,并且想要尝试使用 OAuth 令牌进行 Navigation Connect,请使用本部分中的过程。

此示例介绍了如何使用应用默认凭证 (ADC) 提供的 OAuth 令牌进行调用。如需详细了解如何使用 ADC 通过客户端库调用 Google API,请参阅使用客户端库进行身份验证。

请仅在开发或测试过程中使用以下 REST 过程,不要在生产环境中使用。

前提条件

在使用 ADC 发出 REST 请求之前,请使用 gcloud CLI 向 ADC 提供凭据:

  1. 安装并初始化 gcloud CLI。如需了解详情,请参阅安装 gcloud CLI。

  2. 使用 gcloud CLI 进行身份验证:

    gcloud auth application-default login
  3. 完成登录流程,将您的凭据保存在 ADC 使用的本地凭据文件中。

如需了解详情,请参阅为本地开发环境设置 ADC。

发出 REST 请求

在此示例中,您传递了两个请求标头:

  • 使用以下命令生成令牌,并在 Authorization 标头中传递 OAuth 令牌:

    gcloud auth application-default print-access-token

    返回的令牌的作用域为 https://www.googleapis.com/auth/cloud-platform。

  • 在 X-Goog-User-Project 标头中传递已启用结算功能的 Google Cloud 云项目的 ID 或名称。

如需使用 OAuth 令牌调用 Navigation Connect,请完成以下步骤:

  1. 在以下代码示例中,将占位符替换为您的值:

    • PROJECT_ID:您的 Google Cloud 项目 ID
    • ANDROID_APP_ID:应用的 Android 软件包名称(如果适用)
    • IOS_APP_ID:应用的 iOS 软件包 ID(如果适用)
    #!/bin/bash
    trip_id="$(uuidgen)"
    access_token="$(gcloud auth application-default print-access-token)"
    curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
    -H "Authorization: Bearer ${access_token}" \
    -H "Content-Type: application/json" \
    -d '{
    "androidAppId": "ANDROID_APP_ID",
    "iosAppId": "IOS_APP_ID",
    }'
  2. 如需复制 curl 命令,请点击代码示例中的复制。

  3. 将该命令粘贴到终端窗口中,然后运行。

该响应是一个 JSON 对象:

{
  "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z",
}

此响应包含以下值:

  • PROJECT_NUMBER:项目的唯一长整数标识符
  • TRIP_ID:后端生成的 UUIDv4 行程 ID
  • BASE64_ENCODED_TRIP_TOKEN:createTrip 方法返回的经过身份验证的令牌,用于在 Google 地图或 Waze 中启动跟踪的精细导航

问题排查

如果您的请求返回错误消息,指出此 API 不支持最终用户凭据,请参阅排查 ADC 设置问题。

后续步骤

接下来,为 Navigation Connect API 配置服务账号,以支持后端基础设施、Google 地图和 Waze 之间的安全服务器到服务器通信。

设置服务账号