Scegliere un endpoint

L'API Route Optimization ha i seguenti endpoint:

  • OptimizeTours: un endpoint di blocco per 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 elevati.
  • BatchOptimizeTours: un endpoint non bloccante per più richieste elaborate contemporaneamente.

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

Confronta gli endpoint

Utilizza la tabella seguente per identificare l'endpoint più adatto alle tue esigenze:

Endpoint OptimizeTours OptimizeToursLongRunning OptimizeToursUri BatchOptimizeTours
Tipo di esecuzione Blocco Non bloccante Non bloccante Non bloccante
Richieste elaborate Single Single Single Multiplo
Dimensioni massime 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. Ne esistono due tipi:
    • Endpoint di blocco: mantengono la connessione aperta finché l'API non restituisce una risposta.
    • Endpoint non bloccanti: elaborano le richieste in background. L'API restituisce immediatamente un ID operazione a lunga esecuzione (LRO) di cui esegui il polling 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.
  • Dimensioni massime della richiesta: le richieste di piccole e medie dimensioni vengono inviate direttamente in linea e hanno limiti lato server. Le richieste di grandi dimensioni bypassano 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 per quanto tempo una connessione deve rimanere aperta, la scelta dell'endpoint dipende dai limiti di timeout. Per saperne di più, consulta Configura timeout e deadline.
  • 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 passi 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 in linea fino a circa 4 MB.

Guarda un'OptimizeToursesempio di richiesta

{
  "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.

Visualizza una richiesta di esempio 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 elevati (oltre 8 MB). Restituisce un ID operazione a lunga esecuzione (LRO). Puoi eseguire il polling di questo ID utilizzando l'endpoint GetOperation per verificare lo stato della richiesta.

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

Guarda un'OptimizeToursUriesempio di richiesta

{
  "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 in linea, carichi più OptimizeToursRequest su 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.

Visualizza 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"
      }
    }
  ]
}