设置 Route Optimization API

本文档介绍了开始使用 Route Optimization API 所需的步骤。

前提条件

此过程将指导您设置 Google Cloud 账号和启用了结算功能的 Google Cloud 项目。 您还应熟悉使用 Route Optimization API 的收费方式。

  1. 查看用量结算和费用，请参阅 Route Optimization API 用量和结算。

  2. 验证您是否拥有 Google Cloud 账号。

    登录 Google Cloud 控制台

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

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

    2. 在结算页面上：

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

启用 API

您必须先使用 Google Cloud 控制台或 gcloud 命令在 Google Cloud 项目中启用 Route Optimization API，然后才能使用该 API。

如需启用 API，请执行以下操作：

控制台

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

    启用 Route Optimization API

  2. 点击启用按钮。

gcloud

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

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

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

创建 OAuth 令牌

Route Optimization API 支持使用 OAuth 2.0 进行身份验证。Google 支持常见的 OAuth 2.0 场景，例如 Web 服务器场景。

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

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

OAuth 概览

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

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

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

OAuth 范围

如需将 OAuth 与 Route Optimization API 搭配使用，您必须为 OAuth 令牌分配以下范围：

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

配置角色

本文档介绍了 Route Optimization 的 Identity and Access Management (IAM) 角色和权限。借助 IAM，您可以授予对特定 Route Optimization 资源的精细访问权限，并防止对其他资源的访问。借助 IAM，您可以应用最小权限安全原则，该原则要求任何人都不应拥有超出实际所需数量的权限。

主账号（用户、群组或服务账号）调用 Google Cloud API 时，该主账号必须具有适当的 IAM 权限才能使用资源。如需向主账号授予所需的权限，您可以向主账号授予 IAM 角色。

如需大致了解 Google Cloud 中的访问权限管理，请参阅 IAM 概览。

允许主账号访问 Route Optimization 的预定义 IAM 角色如下：

  • Route Optimization Editor (roles/routeoptimization.editor)：向用户或服务账号授予对项目中 Route Optimization 资源的读写权限。这包括调用 OptimizeTours 和 BatchOptimizeTours 以及使用 GetOperation 检索长时间运行的操作的能力。
  • Route Optimization Viewer (roles/routeoptimization.viewer)：授予对项目中 Route Optimization 资源的只读权限。此角色可以调用 OptimizeTours，并使用 GetOperation 访问长时间运行的操作。
您可以使用 Cloud SDK 为主账号创建绑定来分配角色： 
gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

如需了解详情，请参阅 使用 Google Cloud 控制台授予 IAM 角色。

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

如果您没有生成令牌的环境，并且想要使用 OAuth 令牌试用 Route Optimization API，请按照本部分中的步骤操作。

此示例介绍了如何使用应用默认凭证 (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 令牌调用 Route Optimization API，请完成以下步骤：

  1. 在以下代码示例中，将 PROJECT_NUMBER_OR_ID 替换为您的 Google Cloud 项目编号或 ID：

    curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data-binary @- << EOM
{
"model": {
"shipments": [
  {
    "pickups": [
      {
        "arrivalLocation": {
          "latitude": 37.73881799999999,
          "longitude": -122.4161
        }
      }
    ],
    "deliveries": [
      {
        "arrivalLocation": {
          "latitude": 37.79581,
          "longitude": -122.4218856
        }
      }
    ]
  }
],
"vehicles": [
  {
    "startLocation": {
      "latitude": 37.73881799999999,
      "longitude": -122.4161
    },
    "endLocation": {
      "latitude": 37.73881799999999,
      "longitude": -122.4161
    }
  }
],
"globalStartTime": "2023-01-13T16:00:00-08:00",
"globalEndTime": "2023-01-14T16:00:00-08:00"
}
}
EOM

  2. 如需复制 curl 命令，请点击代码示例中的复制。

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

该响应是一个 JSON 对象：

{
  "routes": [
    {
      "vehicleStartTime": "2023-01-14T00:00:00Z",
      "vehicleEndTime": "2023-01-14T00:39:22Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2023-01-14T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2023-01-14T00:19:53Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1193s",
          "travelDistanceMeters": 9007,
          "waitDuration": "0s",
          "totalDuration": "1193s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1169s",
          "travelDistanceMeters": 9546,
          "waitDuration": "0s",
          "totalDuration": "1169s",
          "startTime": "2023-01-14T00:19:53Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2362s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2362s",
        "travelDistanceMeters": 18553
      }
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2362s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2362s",
      "travelDistanceMeters": 18553
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2023-01-14T00:00:00Z",
    "latestVehicleEndTime": "2023-01-14T00:39:22Z"
  }
}

问题排查

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