In diesem Dokument erfahren Sie, wie Sie Ihre erste Anfrage an die Route Optimization API anhand eines realen Anwendungsfalls stellen.
Der Einfachheit halber werden in diesem Beispiel HTTP und JSON verwendet, um die REST API zu demonstrieren. Für Ihre Produktionsumgebung wird jedoch generell die Verwendung von gRPC empfohlen, da es Leistungsvorteile bietet. Für gRPC ist jedoch eine Installation erforderlich. Weitere Informationen finden Sie unter Route Optimization API-Clientbibliotheken.
Szenario
Sie betreiben in San Francisco eine Hundetagesstätte, die von 7:00 bis 19:00 Uhr geöffnet ist. Heute Morgen möchten Sie drei Hunde von verschiedenen Orten in der Stadt abholen und in Ihre Tagesstätte bringen.
Der Berner Sennenhund und der Chihuahua sind Stammkunden, die ihre Termine letzte Woche gebucht haben. Der Deutsche Schäferhund ist eine neue, kurzfristige Anfrage. Sie möchten den Schäferhund nach Möglichkeit aufnehmen, aber nicht auf Kosten Ihrer Stammkunden.
Sie haben einen Lieferwagen für den Auftrag und zahlen dem Fahrer 27 $ pro Stunde. Der Fahrer und der Transporter beginnen den Tag um 7:00 Uhr in Ihrer Kindertagesstätte und müssen bis Mittag von den morgendlichen Abholungen zurück sein, um eine Mittagspause einzulegen.
Heute ist der 13. Februar 2024. Alle Zeitangaben in diesem Szenario sind Ortszeit San Francisco, also Pacific Standard Time (UTC-8) im Februar. Der Treiber hat die folgenden Aufgaben:
- Hol den Berner Sennenhund in der Nähe des Coit Tower ab. Der Eigentümer hat ein enges Zeitfenster für die Abholung zwischen 8:00 Uhr und 8:20 Uhr angefordert.
- Hol den Chihuahua im South Sunset Playground Park ab. Der Eigentümer hat ein flexibleres Abholfenster zwischen 7:30 Uhr und 9:30 Uhr angeboten.
- Hol den Deutschen Schäferhund am Land's End ab. Der Eigentümer hat außerdem ein enges Zeitfenster für die Abholung zwischen 8:00 Uhr und 8:20 Uhr angefordert.
- Bringe die Hunde zur Tagesstätte im Mission Dolores Park. Die Kindertagesstätte verlangt, dass die Kinder zwischen 9:30 Uhr und 11:30 Uhr gebracht werden.
Das Ein- und Ausladen des Hundes dauert jeweils 5 Minuten.
Da Land's End weit vom Coit Tower entfernt ist und sich die Abholzeitfenster überschneiden, kann der Fahrer nicht alle drei Abholungen durchführen. Der Optimierer muss entscheiden, welcher Hund übersprungen werden soll, um die Gesamtkosten (Fahrerlöhne und Strafen für das Überspringen) zu minimieren.
Hinweis
Wenn Sie den Code in diesem Beispielszenario ausführen möchten, müssen Sie zuerst die Anleitung unter Route Optimization API einrichten ausführen.
1. Ansatz für die Routenoptimierung auswählen
Die Route Optimization API bietet mehrere Methoden, aus denen Sie je nach Komplexität Ihres Optimierungsproblems auswählen können.
Da es sich bei diesem Szenario um eine kleine und einfache Anfrage handelt, verwenden Sie eine blockierende Methode wie optimizeTours, die schnell Ergebnisse für kleine Anfragen liefert. Weitere Informationen zu den Endpunkten der Route Optimization API finden Sie unter Endpunkt auswählen.
Verwenden Sie die folgende URL, um eine HTTP-POST-Anfrage an die Methode optimizeTours zu senden:
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
Außerdem müssen Sie die Zeitlimit- und Fristeinstellungen kurz halten, um unnötige Wartezeiten zu vermeiden. Für dieses Szenario mit der Hundetagesstätte benötigt der Optimierer nicht viel Zeit, um auf Ihre Anfrage zu antworten. Verwenden Sie daher die folgenden Einstellungen:
- Legen Sie für den Parameter
timeoutden Wert 2 Sekunden fest. - Behalten Sie die Standardeinstellungen für die Frist bei. Diese beträgt 60 Sekunden für REST-Anfragen.
2. Anfragenachrichtentext erstellen
Nachdem Sie die Blockierungsmethode optimizeTours ausgewählt und die Einstellungen für Zeitüberschreitung und Frist definiert haben, müssen Sie als Nächstes den Text der Anfragenachricht erstellen.
In diesem Szenario ist die Anfrage eine OptimizeToursRequest-Nachricht, die in der REST API als JSON codiert ist.
So erstellen Sie die Anfragenachricht:
Beginnen Sie mit der grundlegenden Anfragestruktur:
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }Weitere Informationen zur Struktur finden Sie im Leitfaden zu den wichtigsten Konzepten für die Basisstruktur (ShipmentModel, Shipment und Vehicle).
Sendungen definieren. Fügen Sie im Feld
shipmentsfür jeden Hund, der morgens abgeholt und wieder zurückgebracht werden muss, eineShipment-Nachricht hinzu. Hier definieren Sie die bevorzugten Abholorte und -zeiten der Hundebesitzer sowie den Ort und die Zeiten, zu denen die Hunde in der Tagesstätte abgegeben werden sollen.Erstellen Sie für jeden Hund einen
VisitRequestfür die Abholung und einen weiteren für die Lieferung, die in diesem Szenario als Abgabe in der Tagesstätte bezeichnet wird.Legen Sie in „pickups“ die
arrivalWaypointauf den Abholort des Hundes fest (Coit Tower für den Berner Sennenhund, South Sunset Playground Park für den Chihuahua oder Land's End für den Deutschen Schäferhund). Legen Sie fürtimeWindowsdie vom Besitzer gewünschte Abholzeit fest (8:00 Uhr bis 8:20 Uhr für den Berner Sennenhund und den Deutschen Schäferhund und 7:30 Uhr bis 9:30 Uhr für den Chihuahua).Legen Sie in den Lieferungen den
arrivalWaypointauf die Kindertagesstätte und dietimeWindowsauf die erforderliche Ausstiegszeit (9:30 Uhr bis 11:30 Uhr) fest.Legen Sie für alle Abholungen und Lieferungen die
durationauf 5 Minuten (300s) fest, um das Ein- und Ausladen der Hunde zu berücksichtigen.
Weitere Informationen zu Zeitfenstern finden Sie unter Zeitfenster.
Um Stammkunden zu priorisieren, legen Sie für den Berner Sennenhund und den Chihuahua den
penaltyCostauf1000und für den Deutschen Schäferhund auf100fest. Wenn Strafkosten festgelegt sind, kann der Optimierer einen der Hunde überspringen. Er zieht jedoch zuerst in Betracht, den Deutschen Schäferhund (der eine niedrigere Strafe hat) zu überspringen, wenn Einschränkungen es unmöglich machen, alle Abholungen durchzuführen.Im Feld
labelkönnen Sie für jede Sendung eine Kennung hinzufügen, z. B. „Berner Sennenhund“, „Chihuahua“ und „Deutscher Schäferhund“. So können Sie die Sendungen in der Antwort leichter identifizieren.
Weitere Informationen zum Definieren von Sendungen finden Sie unter Shipment.
Fahrzeuge definieren Fügen Sie im Feld
vehicleseineVehicle-Nachricht für den einen Transporter hinzu, mit der Kindertagesstätte als Start- und Endpunkt, den Kosten für den Fahrer und den Öffnungszeiten des Transporters.Legen Sie die
startWaypointundendWaypointfür den Lieferwagen auf den Start- und Endort des Tages fest, also die Kindertagesstätte in der Nähe des Mission Dolores Park.Um die Betriebskosten zu minimieren, müssen Sie die Kosteneinschränkungen Ihres Unternehmens definieren. Legen Sie für den Kostenparameter
costPerHourden Wert27fest. Das ist der Betrag, den Sie dem Fahrer für die Fahrt mit dem Transporter der Hundetagesstätte zahlen. Weitere Informationen zu Kostenparametern finden Sie unter Kostenmodell.Damit der Optimierer eine Route innerhalb der Betriebszeiten des Lieferwagens erstellt, definieren Sie ein Betriebszeitfenster für das Fahrzeug. In diesem Fenster werden die Start- und Endzeitbeschränkungen für die Route festgelegt. Wenn Sie nur eine Hälfte jedes Zeitfensters definieren, geben Sie dem Optimierer die Flexibilität, die Route später zu beginnen oder früher zu beenden:
Wenn Sie
startTimeinstartTimeWindowsauf 07:00 Uhr festlegen, kann der Fahrer seine Schicht bereits um 07:00 Uhr beginnen. Er kann auch später beginnen, wenn es keine Abholungen am frühen Morgen gibt.Wenn Sie
endTimeinendTimeWindowsauf Mittag festlegen, muss der Fahrer seine Schicht bis Mittag beenden. Sie können ihre Schicht auch beenden, sobald sie die letzte Lieferung abgeschlossen haben.
Wenn die andere Hälfte der Zeitfenster weggelassen wird, werden die Warte- und Umwegzeiten des Fahrers minimiert. Weitere Informationen zu Zeitfenstern finden Sie unter Zeitfenster.
Weitere Informationen zum Definieren von Fahrzeugen finden Sie unter Fahrzeug.
Globales Zeitfenster festlegen Das globale Zeitfenster stellt den Zeitraum dar, in dem der Transporter den ganzen Tag über Abholungen und Abgaben für Ihre Kindertagesstätte durchführen kann. Legen Sie in diesem Szenario
globalStartTimeauf 7:00 Uhr undglobalEndTimeauf 19:00 Uhr für den 13. Februar 2024 fest. Das sind die Öffnungszeiten Ihrer Hundetagesstätte.
3. Anfrage senden
Im Folgenden finden Sie eine einfache curl-Anfrage, die auf dem Szenario der Hundetagesstätte basiert und die blockierende Methode optimizeTours verwendet.
Ersetzen Sie vor dem Senden der Anfrage PROJECT_NUMBER_OR_ID im Beispielcode durch Ihre Google Cloud-Projekt-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 @- << EOM
{
"timeout": "2s",
"model": {
"shipments": [
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.802395,
"longitude": -122.405822
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Bernese mountain dog",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00-08:00",
"endTime": "2024-02-13T09:30:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Chihuahua",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.78018,
"longitude": -122.51194
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "German shepherd",
"penaltyCost": 100
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00-08:00"
}
],
"endTimeWindows": [
{
"endTime": "2024-02-13T12:00:00-08:00"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00-08:00",
"globalEndTime": "2024-02-13T19:00:00-08:00"
}
}
EOM
In der Anfrage verwendete Anfrageparameter
In der folgenden Tabelle werden die Anfrageparameter beschrieben, die im Anfragetext des Beispielszenarios verwendet werden. Sie können die Inhalte nach übergeordnetem Element oder per Textsuche filtern.
| Elternteil | Parameter | Property-Typ | Beschreibung |
|---|---|---|---|
OptimizeToursRequest |
model |
Objekt (ShipmentModel) |
Das ist der Kern Ihrer Anfrage. Es ist ein einzelnes Objekt, in dem Sie das gesamte Problem definieren, einschließlich aller Hunde, die Sie abholen und absetzen müssen (shipments), und des Lieferwagens in Ihrer Flotte (vehicles). Stellen Sie sich das als den vollständigen Plan für das Problem vor, das Sie optimieren müssen. |
timeout |
Dauer | Dieser Parameter gibt die maximale Zeit an, die der Server an einer Anfrage arbeitet, bevor er eine Antwort zurückgibt. Verwenden Sie diesen Parameter, um die Wartezeit zu verkürzen. Legen Sie diesen Wert für kleine und schnelle Anfragen, wie in diesem Szenario mit der Hundetagesstätte, auf 2 Sekunden fest. | |
ShipmentModel |
shipments[] |
Array von Objekten (Shipment) |
Dies ist ein Array von Objekten, wobei jedes Objekt einen Hund darstellt, der abgeholt oder abgesetzt werden muss. |
vehicles[] |
Array von Objekten (Vehicle) |
Dies ist ein Array von Objekten, wobei jedes Objekt ein Fahrzeug in Ihrer Flotte definiert. Hier beschreiben Sie Ihre Ressourcen, z. B. den Lieferwagen, der die Abholungen und Lieferungen durchführt. Sie müssen mindestens ein Fahrzeug definieren, um eine optimierte Route zu erhalten. | |
globalStartTime |
Zeitstempel | Dies ist der frühestmögliche Zeitpunkt für ein Ereignis in Ihrem gesamten Modell. Dieser Parameter schränkt das Optimierungsproblem zeitlich ein, was für genaue Verkehrs- und Routenberechnungen entscheidend ist. Legen Sie für dieses Szenario mit der Hundetagesstätte die früheste Uhrzeit fest, zu der der Fahrer den Transporter an diesem Tag fahren kann. Das ist der 13. Februar 2024 um 7:00 Uhr. | |
globalEndTime |
Zeitstempel | Dies ist der späteste mögliche Zeitpunkt für ein Ereignis in Ihrem gesamten Modell. In diesem Szenario für die Hundetagesstätte legen Sie hier fest, wann der Transporter voraussichtlich seinen Betrieb beendet. Das ist der 13. Februar 2024 um 19:00 Uhr. | |
Shipment |
pickups[] |
Array von Objekten (VisitRequest) |
Dies ist eine Liste aller möglichen Abholoptionen für die Sendung. Der Optimierer wählt die beste Methode aus, um Ihr Problem zu lösen. Listen Sie für dieses Szenario mit der Hundetagesstätte die Abholorte und Zeitfenster auf, die jeder Besitzer für jeden Hund angegeben hat. |
deliveries[] |
Array von Objekten (VisitRequest) |
Dies ist eine Liste aller möglichen Abgabeoptionen für die Sendung. Der Optimierer wählt die beste Methode aus, um Ihr Problem zu lösen. Geben Sie für dieses Szenario mit der Hundetagesstätte den Standort der Hundetagesstätte und das Zeitfenster an, in dem der Fahrer für jeden Hund zum Mittagessen zurückkehren muss. | |
label |
String | Dies ist eine Kennung für eine bestimmte Sendung in Ihrer Anfrage. Sie können in Ihrer Anfrage Labels angeben, um die Antwort leichter lesbar zu machen. Verwenden Sie für dieses Szenario mit der Hundetagesstätte einen beschreibenden String wie „Chihuahua“, „Berner Sennenhund“ oder den Namen des Hundes, um die Lösung mit Ihrer Eingabe abzugleichen, wenn Sie die API-Antwort erhalten. | |
penaltyCost |
double | Dies sind die Strafkosten, die anfallen, wenn der Optimierer diese Sendung überspringt. Standardmäßig sind Sendungen obligatorisch. Der Optimierer priorisiert die Minimierung übersprungener obligatorischer Sendungen und überspringt sie nur, wenn es keine andere Möglichkeit gibt. Wenn Sie Strafkosten festlegen, kann der Optimierer eine Sendung überspringen, wenn sie nicht durchführbar oder zu teuer ist. Außerdem können Sie so Prioritäten zwischen Sendungen abwägen. In diesem Szenario legen Sie für Ihre Stammkunden (Berner Sennenhund und Chihuahua) höhere Strafkosten (1000) und für die kurzfristige Anfrage für den Deutschen Schäferhund niedrigere Strafkosten (100) fest. Dadurch wird der Optimierer angewiesen, die Stammkunden zu priorisieren. Er zieht also zuerst in Betracht, den Schäferhund zu überspringen, wenn er nicht alle Abholungen durchführen kann. |
|
VisitRequest |
arrivalWaypoint |
Objekt (Waypoint) |
Dies ist der Ort eines bestimmten Besuchs auf der Route. Sie können ihn mithilfe von Breiten- und Längengradkoordinaten, einer Orts-ID oder einer Richtung definieren. In diesem Szenario mit der Hundetagesstätte legen Sie den vom Inhaber angegebenen Standort für pickups und die Adresse der Tagesstätte für deliveries fest. |
timeWindows[] |
Array von Objekten (TimeWindow) |
Dies ist ein Array von Objekten, die die Zeitbeschränkungen für eine Abholung oder Lieferung definieren. In diesem Szenario definieren Sie damit das Abholzeitfenster für jeden Hund und das zulässige Zeitfenster für das Abgeben der Hunde in der Tagesstätte. | |
duration |
Dauer | Dieser Parameter gibt die Dauer des Besuchs an (z.B. Lade- oder Entladezeit). In diesem Szenario legen Sie für alle Abholungen und Lieferungen einen Puffer von 5 Minuten (300s) fest, um die Zeit zu berücksichtigen, die der Fahrer zum Ein- und Ausladen der Hunde benötigt. |
|
Vehicle |
startWaypoint |
Objekt (Waypoint) |
Dies ist der Startort der Route des Fahrzeugs, definiert durch Breiten- und Längengradkoordinaten oder eine Orts-ID. Dieser Parameter gibt dem Optimierer an, wo das Fahrzeug die Route beginnen muss. Wenn Sie diesen Wegpunkt nicht definieren, wählt der Optimierer eine der Abholungen oder Lieferungen als Startort aus. In diesem Szenario für die Hundetagesstätte beginnt der Fahrer den Tag in der Tagesstätte. Verwenden Sie daher die Koordinaten für den Mission Dolores Park. |
endWaypoint |
Objekt (Waypoint) |
Dies ist das endgültige Ziel der Route des Fahrzeugs, definiert durch Breiten- und Längengradkoordinaten oder eine Orts-ID. Dieser Parameter gibt dem Optimierer an, wo das Fahrzeug die Route beenden muss. Wenn Sie diesen Wegpunkt nicht definieren, wählt der Optimierer eine der Abholungen oder Lieferungen als Ende der Route aus. In diesem Szenario muss der Fahrer den Tag bei der Hundetagesstätte beenden. Verwenden Sie daher die Koordinaten für den Mission Dolores Park. | |
costPerHour |
Zahl | Dies sind die Kosten, die für jede Stunde anfallen, in der ein Fahrzeug verwendet wird, unabhängig davon, ob es fährt oder steht. In diesem Szenario für die Hundetagesstätte verwenden Sie dies, um den Stundenlohn eines Fahrers zu modellieren. | |
startTimeWindows[] |
Array von Objekten (TimeWindow) |
Dies ist das zulässige Zeitfenster, in dem der Fahrer seine Schicht beginnen kann. In diesem Szenario für die Hundetagesstätte definieren Sie startTime als 7:00 Uhr, lassen aber endTime weg. So kann der Optimierer den Beginn der Schicht verzögern, wenn die erste Abholung später am Morgen erfolgt. Auch wenn Sie keinen endTime für startTimeWindows angeben, wird die Startzeit implizit durch den endTimeWindows begrenzt. Das Fahrzeug muss die Route beginnen, bevor die Route endet. |
|
endTimeWindows[] |
Array von Objekten (TimeWindow) |
Dies ist das zulässige Zeitfenster, in dem der Fahrer die Route beenden muss.
In diesem Szenario für die Hundetagesstätte definieren Sie die endTime als Mittag, lassen aber die startTime weg. So kann der Fahrer sofort nach dem letzten Absetzen zur Kindertagesstätte zurückkehren. |