Configurare l'API Route Optimization

Questo documento descrive i passaggi necessari per iniziare a utilizzare l'API Route Optimization.

Prerequisiti

Questa procedura ti guida nella configurazione di un account Google Cloud e di un progetto cloud Google con la fatturazione abilitata. Inoltre, devi avere familiarità con il modo in cui ti vengono addebitati i costi per l'utilizzo dell'API Route Optimization.

  1. Esamina la fatturazione e i costi per l'utilizzo in Utilizzo e fatturazione dell'API Route Optimization.

  2. Verifica di avere un account Google Cloud.

    Accedi alla console Google Cloud

  3. Verifica di avere un progetto Google Cloud con la fatturazione abilitata.

    Vai alla pagina Fatturazione
    1. Seleziona il tuo progetto per aprire la pagina Fatturazione.

    2. Nella pagina Fatturazione:

      • Se la fatturazione è già abilitata per il progetto selezionato e hai un solo account di fatturazione, si apre la pagina Fatturazione.
      • Se hai più account di fatturazione, seleziona Vai all'account di fatturazione collegato per visualizzare i dettagli dell'account di fatturazione associato al progetto.
      • Se esiste un account di fatturazione, ma non è associato al progetto, ti verrà chiesto di collegare un account di fatturazione al progetto.
      • Se non esiste un account di fatturazione o se vuoi crearne uno nuovo, seleziona Gestisci account di fatturazione per creare un nuovo account di fatturazione. Per saperne di più, consulta Crea un nuovo account di fatturazione Cloud self-service.

Abilita l'API

Prima di poter utilizzare l'API Route Optimization, devi abilitarla nel tuo progetto Google Cloud utilizzando la console Google Cloud o il comando gcloud.

Per abilitare l'API:

Console

  1. Apri la pagina di prodotto nella console Google Cloud:

    Abilita l'API Route Optimization

  2. Fai clic sul pulsante Abilita.

gcloud

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

Scopri di più su Google Cloud SDK, sull'installazione di Cloud SDK e sui seguenti comandi:

I prodotti Google Maps Platform richiedono che le chiamate API includano un token OAuth per impedire l'utilizzo non autorizzato.

Crea un token OAuth

L'API Route Optimization supporta OAuth 2.0 per l'autenticazione. Google supporta scenari OAuth 2.0 comuni, ad esempio per un server web.

Questo documento descrive come passare un token OAuth a una chiamata API Route Optimization nel tuo ambiente di sviluppo. Per saperne di più sull'utilizzo di OAuth in un ambiente di produzione, consulta Metodi di autenticazione di Google.

Puoi chiamare le API di Google Maps direttamente inviando richieste API al server oppure puoi utilizzare le librerie client per semplificare il codice. Google Maps fornisce librerie client per Go, Java, Node.js e Python. Per saperne di più, consulta Librerie client dell'API Route Optimization.

Panoramica di OAuth

Puoi creare e gestire i token di accesso con OAuth in diversi modi, a seconda dell'ambiente di deployment.

Puoi utilizzare OAuth 2.0 per le interazioni server-to-server tra la tua applicazione e un servizio Google. Per questo scenario, utilizzi un service account associato alla tua applicazione anziché a un singolo utente. Puoi effettuare richieste API utilizzando il service account senza coinvolgere direttamente gli utenti. Per saperne di più sui metodi di autenticazione, consulta Metodi di autenticazione di Google.

In alternativa, puoi integrare l'API Route Optimization in un'app mobile Android o iOS. Per ulteriori informazioni sull'utilizzo di OAuth e sulla gestione dei token di accesso per diversi ambienti di deployment, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Ambiti OAuth

Per utilizzare OAuth con l'API Route Optimization, devi assegnare al token OAuth il seguente ambito:

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

Configura i ruoli

Questo documento fornisce informazioni sui ruoli e sulle autorizzazioni di Identity and Access Management (IAM) per Route Optimization. IAM ti consente di concedere un accesso granulare a risorse Route Optimization specifiche e aiuta a impedire l'accesso ad altre risorse. IAM ti consente di applicare il principio di sicurezza del privilegio minimo, secondo cui nessuno deve avere più autorizzazioni di quelle di cui ha effettivamente bisogno.

Quando un'entità (un utente, un gruppo o un service account) chiama un'API Google Cloud, deve disporre delle autorizzazioni IAM appropriate per utilizzare la risorsa. Per concedere a un'entità le autorizzazioni richieste, assegna un ruolo IAM all'entità.

Per acquisire familiarità con la gestione degli accessi in Google Cloud in generale, consulta la panoramica di IAM.

I ruoli IAM predefiniti per consentire alle entità di accedere a Route Optimization sono:

  • Route Optimization Editor (roles/routeoptimization.editor): concede all'utente o al service account l'accesso in lettura e scrittura alle risorse di Route Optimization nel progetto. Ciò include la possibilità di chiamare OptimizeTours e BatchOptimizeTours, nonché di recuperare operazioni a lunga esecuzione utilizzando GetOperation.
  • Route Optimization Viewer (roles/routeoptimization.viewer): concede l'accesso di sola lettura alle risorse di Route Optimization nel progetto. Questo ruolo consente di chiamare OptimizeTours e di accedere alle operazioni a lunga esecuzione utilizzando GetOperation.
Puoi assegnare un ruolo creando un'associazione per un'entità utilizzando Cloud SDK: 
gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

Per saperne di più, consulta Concedi un ruolo IAM utilizzando la console Google Cloud.

Esempio: prova le chiamate API REST nel tuo ambiente di sviluppo locale

Se non hai un ambiente che genera token e vuoi provare l'API Route Optimization con un token OAuth, utilizza la procedura descritta in questa sezione.

Questo esempio descrive come utilizzare il token OAuth fornito dalle Credenziali predefinite dell'applicazione (ADC) per effettuare la chiamata. Per saperne di più sull'utilizzo di ADC per chiamare le API di Google con le librerie client, consulta Autenticati utilizzando le librerie client.

Utilizza la seguente procedura REST solo per lo sviluppo o i test, non per la produzione.

Prerequisiti

Prima di effettuare una richiesta REST utilizzando ADC, utilizza l'interfaccia a riga di comando gcloud per fornire le credenziali ad ADC:

  1. Installa e inizializza l'interfaccia a riga di comando gcloud. Per saperne di più, consulta Installa gcloud CLI.

  2. Esegui l'autenticazione con l'interfaccia a riga di comando gcloud:

    gcloud auth application-default login

  3. Completa la procedura di accesso per salvare le tue credenziali nel file delle credenziali locali utilizzato da ADC.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

Effettua una richiesta REST

In questo esempio, passi due intestazioni della richiesta:

  • Passa il token OAuth nell'intestazione Authorization utilizzando il seguente comando per generare il token:

    gcloud auth application-default print-access-token

    Il token restituito ha un ambito di https://www.googleapis.com/auth/cloud-platform.

  • Passa l'ID o il nome del tuo progetto cloud Google Cloud con la fatturazione abilitata nell'intestazione X-Goog-User-Project.

Per chiamare l'API Route Optimization utilizzando un token OAuth, completa i seguenti passaggi:

  1. Nel seguente esempio di codice, sostituisci PROJECT_NUMBER_OR_ID con il numero o l'ID del tuo progetto 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. Per copiare il comando curl, fai clic su Copia nell'esempio di codice.

  3. Incolla il comando in una finestra del terminale, quindi eseguilo.

La risposta è un oggetto 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"
  }
}

Risoluzione dei problemi

Se la richiesta restituisce un messaggio di errore che indica che questa API non supporta le credenziali dell'utente finale, consulta Risolvi i problemi di configurazione di ADC.