Configurar a API Route Optimization

Este documento descreve as etapas necessárias para começar a usar a API Route Optimization.

Pré-requisitos

Este procedimento orienta você na configuração de uma conta do Google Cloud e de um projeto na nuvem com o faturamento ativado. Também é importante saber como você é cobrado pelo uso da API Route Optimization.

1. Consulte o faturamento e o custo de uso em Uso e faturamento da API Route Optimization.

2. Verifique se você tem uma Conta do Google Cloud.

   Faça login no console do Google Cloud

3. Verifique se você tem um projeto do Google Cloud com o faturamento ativado.

   Acessar a página "Faturamento"
1. Selecione o projeto para abrir a página Faturamento.

2. Na página Faturamento:

   • Se o faturamento já estiver ativado para o projeto selecionado e você tiver apenas uma conta de faturamento, a página Faturamento será aberta.
   • Se você tiver várias contas de faturamento, selecione Acessar a conta de faturamento vinculada para ver os detalhes da conta de faturamento associada ao projeto.
   • Se uma conta de faturamento existir, mas não estiver associada ao projeto, será solicitado que você vincule uma conta de faturamento ao projeto.
   • Se não houver uma conta de faturamento ou se você quiser criar uma nova, selecione Gerenciar contas de faturamento para criar uma nova conta de faturamento. Para mais informações, consulte Criar uma nova conta do Cloud Billing de autoatendimento.

Ativar a API

Antes de usar a API Route Optimization, use o console do Google Cloud ou o comando gcloud para ativá-la no seu projeto na nuvem.

Para ativar a API:

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

Os produtos da Plataforma Google Maps exigem que as chamadas de API incluam um token OAuth para evitar o uso não autorizado.

Criar um token OAuth

A API Route Optimization é compatível com o OAuth 2.0 para autenticação. O Google é compatível com cenários comuns do OAuth 2.0, como os de um servidor da Web.

Neste documento, descrevemos como transmitir um token OAuth para uma chamada de API Route Optimization no seu ambiente de desenvolvimento. Para mais informações sobre como usar o OAuth em um ambiente de produção, consulte Métodos de autenticação no Google.

É possível chamar as APIs Google Maps diretamente fazendo solicitações de API ao servidor ou usar bibliotecas de cliente para simplificar seu código. O Google Maps oferece bibliotecas de cliente para Go, Java, Node.js e Python. Para mais informações, consulte Bibliotecas de cliente da API Route Optimization.

Visão geral do OAuth

É possível criar e gerenciar tokens de acesso com o OAuth de várias maneiras, dependendo do seu ambiente de implantação.

É possível usar o OAuth 2.0 para interações de servidor para servidor entre seu aplicativo e um serviço do Google. Nesse cenário, você usa uma conta de serviço associada ao aplicativo, em vez de um usuário individual. É possível fazer solicitações de API usando a conta de serviço sem envolver os usuários diretamente. Para mais informações sobre métodos de autenticação, consulte Métodos de autenticação no Google.

Como alternativa, é possível integrar a API Route Optimization a um app para dispositivos móveis Android ou iOS. Para mais informações sobre como usar o OAuth e gerenciar tokens de acesso para diferentes ambientes de implantação, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Escopos do OAuth

Para usar o OAuth com a API Route Optimization, atribua ao token OAuth o seguinte escopo:

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

Configurar papéis

Neste documento, você encontra informações sobre papéis e permissões do Identity and Access Management (IAM) para a Route Optimization. O IAM permite conceder acesso granular a recursos específicos da Route Optimization e ajuda a impedir o acesso a outros recursos. O IAM permite aplicar o princípio de menor privilégio de segurança, que indica que ninguém precisa ter mais permissões do que o realmente necessário.

Quando um principal (um usuário, grupo ou uma conta de serviço) chama uma API do Google Cloud, ele precisa ter as permissões apropriadas do IAM para usar o recurso. Para conceder as permissões necessárias a um principal, atribua um papel do IAM a ele.

Para se familiarizar com o gerenciamento do acesso no Google Cloud em geral, consulte a visão geral do IAM.

Os papéis predefinidos do IAM para permitir que os principais acessem a Route Optimization são:

• Route Optimization Editor (roles/routeoptimization.editor): concede ao usuário ou à conta de serviço acesso de leitura e gravação aos recursos da Route Optimization no projeto. Isso inclui a capacidade de chamar OptimizeTours e BatchOptimizeTours, além de recuperar operações de longa duração usando GetOperation.
• Route Optimization Viewer (roles/routeoptimization.viewer): concede acesso somente leitura aos recursos de otimização de rotas no projeto. Esse papel permite chamar OptimizeTours e acessar operações de longa duração usando GetOperation.

gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

Para mais informações, consulte Conceder um papel do IAM usando o console do Google Cloud.

Exemplo: testar chamadas de API REST no ambiente de desenvolvimento local

Se você não tiver um ambiente que gere tokens e quiser testar a API Route Optimization com um token OAuth, use o procedimento nesta seção.

Este exemplo descreve como usar o token OAuth fornecido pelo Application Default Credentials (ADC) para fazer a chamada. Para mais informações sobre como usar o ADC para chamar APIs do Google com bibliotecas de cliente, consulte Autenticar usando bibliotecas de cliente.

Use o procedimento REST a seguir apenas para desenvolvimento ou teste, não para produção.

Pré-requisitos

Antes de fazer uma solicitação REST usando o ADC, use a CLI gcloud para fornecer credenciais ao ADC:

1. Instale e inicialize a CLI gcloud. Para mais informações, consulte Instalar a CLI gcloud.

2. Faça a autenticação com a gcloud CLI:

   gcloud auth application-default login

3. Conclua o processo de login para salvar suas credenciais no arquivo de credenciais local usado pelo ADC.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

Fazer uma solicitação REST

Neste exemplo, você transmite dois cabeçalhos da solicitação:

• Transmita o token OAuth no cabeçalho Authorization usando o seguinte comando para gerar o token:

  gcloud auth application-default print-access-token

  O token retornado tem um escopo de https://www.googleapis.com/auth/cloud-platform.

• Transmita o ID ou o nome do projeto na nuvem do Google Cloud com o faturamento ativado no cabeçalho X-Goog-User-Project.

Para chamar a API Route Optimization usando um token OAuth, siga estas etapas:

1. No exemplo de código a seguir, substitua PROJECT_NUMBER_OR_ID pelo número ou ID do projeto do Google Cloud:

   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. Para copiar o comando curl, clique em Copiar no exemplo de código.

3. Cole o comando em uma janela do terminal e execute-o.

A resposta é um objeto 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"
  }
}

Solução de problemas

Se a solicitação retornar uma mensagem de erro informando que essa API não é compatível com credenciais de usuário final, consulte Resolver problemas de configuração do ADC.