Stellen Sie Ihre erste Routenoptimierungsanfrage.

Entwickler im Europäischen Wirtschaftsraum (EWR)

In diesem Dokument erfahren Sie, wie Sie Ihre erste Anfrage an die Route Optimization API mit einem realen Anwendungsfallszenario stellen.

Zur Vereinfachung wird in diesem Beispiel HTTP und JSON verwendet, um die REST API zu veranschaulichen. Für Ihre Produktionsumgebung empfehlen wir jedoch gRPC, da es eine bessere Leistung bietet. Für gRPC ist jedoch eine Installation erforderlich. Weitere Informationen finden Sie unter Route Optimization API-Clientbibliotheken.

Szenario

Eine Karte von San Francisco mit Markierungen für den Coit Tower, den Mission Dolores Park und den South Sunset Playground Park

Sie betreiben eine Hundetagesstätte in San Francisco, die von 7:00 Uhr bis 19:00 Uhr geöffnet ist. Heute Morgen müssen Sie zwei Hunde von verschiedenen Orten in der Stadt abholen. Beide Hundehalter haben dir ein Abholzeitfenster zwischen 7:30 Uhr und 9:30 Uhr angegeben.

Sie haben einen Transporter 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 12:00 Uhr von den morgendlichen Abholungen zurück sein, um eine Mittagspause einzulegen.

Heute ist der 13. Februar 2024 und der Fahrer hat die folgenden Aufgaben:

  • Hole den Berner Sennenhund in der Nähe des Coit Tower ab.
  • Hole den Chihuahua im South Sunset Playground Park ab.
  • Bring beide Hunde zur Hundetagesstätte am Mission Dolores Park.

Sie benötigen eine Route, die die Zeit, die die Hunde im Transporter verbringen, minimiert und gleichzeitig die Anforderungen für die Abholung und den Transport erfüllt.

Hinweis

Wenn Sie den Code in diesem Beispielszenario ausführen möchten, müssen Sie zuerst die Anleitung unter Route Optimization API einrichten befolgen.

1. Ansatz zur 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 mit der Hundetagesstätte um eine kleine und unkomplizierte Anfrage handelt, verwenden Sie eine blockierende Methode wie optimizeTours, die schnell Ergebnisse für kleine Anfragen liefert. Weitere Informationen zu den Methoden der Route Optimization API finden Sie unter Synchrone und asynchrone Endpunkte.

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 so kurz wie möglich festlegen, um unnötige Wartezeiten zu vermeiden. In diesem Szenario mit der Hundetagesstätte benötigt das Optimierungstool nicht viel Zeit, um auf Ihre Anfrage zu reagieren. Verwenden Sie daher die folgenden Einstellungen:

  • Legen Sie den Parameter timeout auf 2 Sekunden fest.
  • Lassen Sie die Fristeinstellungen auf dem Standardwert, der für REST-Anfragen 60 Sekunden beträgt.

2. Nachrichtentext der Anfrage erstellen

Nachdem Sie die optimizeTours-Blockierungsmethode ausgewählt und die Einstellungen für Zeitüberschreitung und Frist festgelegt haben, besteht der nächste Schritt darin, den Text der Anforderungsnachricht zu erstellen.

In diesem Szenario ist die Anfrage eine OptimizeToursRequest-Nachricht, die in der REST API als JSON codiert ist.

So erstellen Sie die Anfragenachricht:

  1. Beginnen Sie mit der grundlegenden Anfragestruktur, die so aussieht:

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Weitere Informationen zur Struktur finden Sie im Leitfaden zu den Schlüsselkonzepten für die Basisstruktur (ShipmentModel, Shipment und Vehicle).

  2. Sendungen definieren: Fügen Sie im Feld shipments für jeden Hund, der morgens abgeholt und abgesetzt werden muss, eine Shipment-Nachricht hinzu. Hier definieren Sie die bevorzugten Abholorte und ‑zeiten des Hundehalters sowie den Ort und die Zeiten der Hundetagesstätte, an denen die Hunde abgegeben werden können.

    1. Erstellen Sie für jeden Hund einen VisitRequest für die Abholungen und einen weiteren für die Lieferungen, die in diesem Szenario als Abgabe in der Hundetagesstätte bezeichnet werden.

      • Legen Sie bei Abholungen den arrivalWaypoint auf den Abholort des Hundes fest (Coit Tower für den Berner Sennenhund oder South Sunset Playground Park für den Chihuahua) und den timeWindows auf die vom Besitzer gewünschte Abholzeit (7:30 bis 9:30 Uhr).

      • Legen Sie bei Lieferungen arrivalWaypoint auf die Kindertagesstätte und timeWindows auf die erforderliche Abgabezeit (9:30 bis 11:30 Uhr) fest.

      Weitere Informationen zu Zeitfenstern finden Sie unter Zeitfenster.

    2. Mit dem Feld label können Sie jeder Sendung eine Kennung hinzufügen, z. B. „Berner Sennenhund“ und „Chihuahua“. So können Sie die Sendungen in der Antwort identifizieren.

    Weitere Informationen zum Definieren von Sendungen finden Sie unter Sendung.

  3. Fahrzeuge definieren: Fügen Sie im Feld vehicles eine Vehicle-Nachricht für Ihren einen Van mit der Kindertagesstätte als Start- und Endpunkt, den Kosten für den Fahrerlohn und den Betriebszeiten des Vans hinzu.

    1. Legen Sie startWaypoint und endWaypoint für den Van auf die Start- und Endpunkte des Tages fest, also auf die Kindertagesstätte in der Nähe des Mission Dolores Park.

    2. Um Ihre Betriebskosten zu minimieren, müssen Sie die Kostenbeschränkungen Ihres Unternehmens definieren. Legen Sie den Kostenparameter costPerHour auf 27 fest. 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.

    3. Damit der Optimierer eine Route innerhalb der Betriebszeiten des Transporters erstellt, definieren Sie startTimeWindows als den akzeptablen Zeitraum für den Fahrer, um den Transporter zu starten, und endTimeWindows als den akzeptablen Zeitraum für die Rückkehr des Fahrers zur Kindertagesstätte. Weitere Informationen zu Zeitfenstern finden Sie unter Zeitfenster.

  4. Globalen Zeitraum festlegen: Das globale Zeitfenster gibt den Zeitraum an, in dem der Kleinbus den ganzen Tag über Kinder für Ihre Kindertagesstätte abholen und absetzen kann. Legen Sie für dieses Szenario globalStartTime auf 7:00 Uhr und globalEndTime auf 19:00 Uhr für den 13. Februar 2024 fest. Das sind die Öffnungszeiten Ihrer Hundetagesstätte.

3. Anfrage senden

Das folgende Beispiel zeigt eine einfache curl-Anfrage basierend auf dem Szenario mit der Hundetagesstätte, bei der die blockierende Methode optimizeTours verwendet wird.

Bevor Sie die Anfrage senden, ersetzen Sie 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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
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.

Hat Kinder Parameter Property-Typ Beschreibung
OptimizeToursRequest model object (ShipmentModel) Das ist der Kern Ihrer Anfrage. Es handelt sich um ein einzelnes Objekt, in dem Sie das gesamte Problem definieren, einschließlich aller Hunde, die Sie abholen und absetzen müssen (shipments), und des Transporters in Ihrer Flotte (vehicles). Es ist sozusagen der vollständige Plan für das Problem, das Sie optimieren müssen.
timeout Dauer Dieser Parameter gibt die maximale Zeit an, die der Server für die Bearbeitung einer Anfrage benötigt, bevor er eine Antwort zurückgibt. Mit diesem Parameter können Sie die Wartezeit verkürzen. Bei kleinen und schnellen Anfragen, wie in diesem Beispiel mit der Hundetagesstätte, sollten Sie diesen Wert auf 2 Sekunden festlegen.
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, mit dem die Abholungen und Zustellungen erfolgen. Sie müssen mindestens ein Fahrzeug definieren, um eine optimierte Route zu erhalten.
globalStartTime Zeitstempel Das ist der frühestmögliche Zeitpunkt für ein Ereignis in Ihrem gesamten Modell. Mit diesem Parameter wird das Optimierungsproblem zeitlich eingegrenzt, was für genaue Berechnungen von Traffic und Routen 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 nutzen kann, also 7:00 Uhr am 13. Februar 2024.
globalEndTime Zeitstempel Das ist der spätestmögliche Zeitpunkt für ein beliebiges Ereignis in Ihrem gesamten Modell. In diesem Beispiel für die Hundetagesstätte legen Sie das Enddatum auf den Zeitpunkt fest, zu dem der Transporter voraussichtlich seine Fahrt beendet, also am 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 den besten aus, um Ihr Problem zu lösen. Geben Sie für dieses Szenario mit der Hundetagesstätte die Abholorte und Zeitfenster an, 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 den besten 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 jedes Tier 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 besser 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 in der API-Antwort an Ihre Eingabe anzupassen.
VisitRequest arrivalWaypoint[] object (Waypoint) Dies ist der Ort eines bestimmten Besuchs auf der Route. Sie können diese mithilfe von Breiten- und Längengradkoordinaten, einer Orts-ID oder einer Überschrift definieren. In diesem Szenario für eine Hundetagesstätte legen Sie für pickups den vom Inhaber angegebenen Standort und für deliveries die Adresse der Tagesstätte fest.
timeWindows[] Array von Objekten (TimeWindow) Dies ist ein Array von Objekten, die die Zeitbeschränkungen für die 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 Kindertagesstätte.
Vehicle startWaypoint[] object (Waypoint) Dies ist der Startort der Route des Fahrzeugs, der durch Breiten- und Längengradkoordinaten oder eine Orts-ID definiert wird. Mit diesem Parameter wird dem Optimierungstool mitgeteilt, wo die Route beginnen muss. Wenn Sie diesen Wegpunkt nicht definieren, wählt das Optimierungstool einen der Abhol- oder Lieferorte als Startort aus. Da der Fahrer in diesem Szenario für die Hundetagesstätte den Tag an der Tagesstätte beginnt, verwenden Sie die Koordinaten für den Mission Dolores Park.
endWaypoint[] object (Waypoint) Das ist das endgültige Ziel der Fahrzeugroute, das mit Breiten- und Längengradkoordinaten oder einer Orts-ID definiert wird. Mit diesem Parameter wird dem Optimierungstool mitgeteilt, wo die Route enden muss. Wenn Sie diesen Wegpunkt nicht definieren, wählt das Optimierungstool einen der Abhol- oder Zustellorte als Ende der Route aus. Da der Fahrer in diesem Szenario für die Hundetagesstätte den Tag in der Einrichtung beenden muss, verwenden Sie 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 eine Hundetagesstätte wird damit der Stundenlohn eines Fahrers modelliert.
startTimeWindows[] Array von Objekten (TimeWindow) Dies ist das zulässige Zeitfenster für den Fahrer, um mit den morgendlichen Hundeabholungen zu beginnen.
endTimeWindows[] Array von Objekten (TimeWindow) Das ist der zulässige Zeitraum, in dem der Fahrer die Fahrt mit dem Transporter beenden und wieder bei der Hundetagesstätte parken muss.

Weiter

Antwort interpretieren