Scegliere un endpoint

L'API Route Optimization ha i seguenti endpoint:

  • OptimizeTours: un endpoint di blocco per le singole richieste.
  • OptimizeToursLongRunning: un endpoint non bloccante per singole richieste con tempi di risoluzione lunghi.
  • OptimizeToursUri: un endpoint non bloccante per singole richieste con requisiti di dati di grandi dimensioni.
  • BatchOptimizeTours: Un endpoint non bloccante per più richieste elaborate contemporaneamente.

L'endpoint che scegli dipende dal caso d'uso, dalle dimensioni della richiesta, dal tempo di risoluzione previsto e dalla necessità di elaborare più richieste contemporaneamente.

Confrontare gli endpoint

Utilizza la tabella seguente per identificare l'endpoint giusto per le tue esigenze:

Endpoint OptimizeTours OptimizeToursLongRunning OptimizeToursUri BatchOptimizeTours
Tipo di esecuzione Blocco Non bloccante Non bloccante Non bloccante
Richieste elaborate Single Single Single Multiplo
Dimensione massima della richiesta Piccolo Medium Grande Grande
Tempo di risoluzione Breve Lungo Lungo Lungo
Richiede Google Cloud Storage No No Sì Sì

Comprendere le caratteristiche dell'endpoint

La tabella precedente elenca le seguenti caratteristiche per aiutarti a scegliere l'endpoint giusto:

  • Tipo di esecuzione: determina il modo in cui l'applicazione gestisce la connessione di rete durante l'attesa di una risposta. Esistono due tipi:
    • Endpoint di blocco: mantieni aperta la connessione finché l'API non restituisce una risposta.
    • Endpoint non bloccanti: elabora le richieste in background. L'API restituisce immediatamente un ID operazione a lunga esecuzione (LRO) che interroghi in un secondo momento per recuperare i risultati.
  • Richieste elaborate: determina se l'endpoint gestisce una singola richiesta di routing o elabora più richieste contemporaneamente.
  • Dimensione massima della richiesta: le richieste piccole e medie vengono inviate direttamente in linea e hanno limiti lato server. Le richieste di grandi dimensioni aggirano questi limiti utilizzando Google Cloud Storage. Trova i limiti esatti delle dimensioni delle richieste nelle sezioni dei dettagli degli endpoint.
  • Tempo di risoluzione: le richieste semplici possono essere risolte in breve tempo, mentre quelle complesse richiedono più tempo. Poiché il tempo di risoluzione determina la durata di apertura di una connessione, la scelta dell'endpoint dipende dai limiti di timeout. Per saperne di più, consulta Configura timeout e scadenze.
  • Richiede Google Cloud Storage: gli endpoint che elaborano richieste e risposte di grandi dimensioni leggono e scrivono i dati direttamente in Google Cloud Storage. Anziché inviare i dati nella richiesta HTTP, carichi la richiesta in un bucket Cloud Storage e trasmetti l'URI all'API.

Dettagli endpoint

L'API Route Optimization ha quattro endpoint. Le sezioni seguenti spiegano come funziona ogni endpoint e includono una richiesta di esempio.

OptimizeTours

OptimizeTours è un endpoint di blocco destinato a singole richieste con tempi di risoluzione brevi. Restituisce un percorso ottimizzato direttamente nella risposta. Poiché si tratta di un endpoint di blocco, devi mantenere aperta la connessione di rete finché l'API non termina l'elaborazione della richiesta per restituire una risposta. Questo endpoint accetta richieste inline fino a circa 4 MB.

Vedi un esempio di richiesta OptimizeTours

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ],
        "deliveries":[
          {
            "arrivalLocation": {
              "latitude": 37.424215,
              "longitude": -122.095260
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}

OptimizeToursLongRunning

OptimizeToursLongRunning è un endpoint non bloccante per singole richieste con tempi di risoluzione lunghi. Restituisce un ID operazione a lunga esecuzione (LRO). Puoi eseguire il polling di questo ID utilizzando l'endpoint GetOperation per controllare lo stato della richiesta e recuperare i percorsi ottimizzati finali. Questo endpoint accetta richieste inline fino a circa 8 MB.

Vedi un esempio di richiesta OptimizeToursLongRunning

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}

OptimizeToursUri

OptimizeToursUri è un endpoint non bloccante destinato a singole richieste con tempi di risoluzione lunghi e requisiti di dati di grandi dimensioni (oltre 8 MB). Restituisce un ID operazione a lunga esecuzione (LRO). Puoi eseguire il polling di questo ID utilizzando l'endpoint GetOperation per controllare lo stato della richiesta.

Anziché inviare il payload inline, carichi il OptimizeToursRequest in Google Cloud Storage. Quindi, trasmetti gli URI di Cloud Storage sia per la richiesta di input sia per la destinazione di output all'API. Il server legge i dati dall'URI di input e scrive l'OptimizeToursResponse finale direttamente nell'URI di output. Una volta completata l'operazione, puoi leggere i percorsi ottimizzati da questo URI di output.

Vedi un esempio di richiesta OptimizeToursUri

{
  "input": {
    "uri": "gs://your-bucket/path/input/object.json"
  },
  "output": {
    "uri": "gs://your-bucket/path/output/object.json"
  }
}

BatchOptimizeTours

BatchOptimizeTours è un endpoint non bloccante destinato a più richieste di ottimizzazione indipendenti elaborate contemporaneamente. Restituisce un ID operazione a lunga esecuzione (LRO). Puoi eseguire il polling di questo ID utilizzando l'endpoint GetOperation per controllare lo stato della richiesta e recuperare i percorsi ottimizzati finali.

Anziché inviare il payload inline, carichi più OptimizeToursRequest in Google Cloud Storage. Quindi, passi gli URI Cloud Storage all'API. Il server legge i dati dagli URI di input e scrive un OptimizeToursResponse per ogni richiesta direttamente negli URI di output.

Vedi un esempio di richiesta BatchOptimizeTours

{
  "modelConfigs": [
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_1.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_1.json"
        },
        "dataFormat": "JSON"
      }
    },
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_2.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_2.json"
        },
        "dataFormat": "JSON"
      }
    }
  ]
}