Route Optimization API einrichten

In diesem Dokument werden die Schritte beschrieben, die Sie ausführen müssen, um die Route Optimization API zu verwenden.

Vorbereitung

In diesem Verfahren werden Sie durch die Einrichtung eines Google Cloud-Kontos und eines Google Cloud-Projekts mit aktivierter Abrechnung geführt. Außerdem sollten Sie wissen, wie die Nutzung der Route Optimization API abgerechnet wird.

1. Informationen zur Abrechnung und zu den Kosten für die Nutzung finden Sie unter Route Optimization API – Nutzung und Abrechnung.

2. Prüfen Sie, ob Sie ein Google Cloud-Konto haben.

   Melden Sie sich in der Google Cloud Console an.

3. Prüfen Sie, ob Sie ein Google Cloud-Projekt mit aktivierter Abrechnung haben.

   Zur Seite „Abrechnung“
1. Wählen Sie Ihr Projekt aus, um die Seite Abrechnung zu öffnen.

2. Auf der Seite Abrechnung:

   • Wenn die Abrechnung für das ausgewählte Projekt bereits aktiviert ist und Sie nur ein einziges Rechnungskonto haben, wird die Seite Abrechnung geöffnet.
   • Wenn Sie mehrere Rechnungskonten haben, wählen Sie Zum verknüpften Rechnungskonto aus, um die Details zum Rechnungskonto aufzurufen, das mit dem Projekt verknüpft ist.
   • Wenn ein Rechnungskonto vorhanden, aber nicht mit dem Projekt verknüpft ist, werden Sie aufgefordert, ein Rechnungskonto mit dem Projekt zu verknüpfen.
   • Wenn kein Rechnungskonto vorhanden ist oder Sie ein neues Rechnungskonto erstellen möchten, wählen Sie Rechnungskonten verwalten aus, um ein neues Rechnungskonto zu erstellen. Weitere Informationen finden Sie unter Neues Selfservice-Cloud-Rechnungskonto erstellen.

API aktivieren

Bevor Sie die Route Optimization API verwenden können, müssen Sie sie in Ihrem Google Cloud-Projekt über die Google Cloud Console oder den Befehl gcloud aktivieren.

So aktivieren Sie die API:

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

Für Google Maps Platform-Produkte ist ein OAuth-Token erforderlich, um die nicht autorisierte Nutzung zu verhindern.

OAuth-Token erstellen

Die Route Optimization API unterstützt OAuth 2.0 für die Authentifizierung. Google unterstützt gängige OAuth 2.0-Szenarien, z. B. Szenarien für einen Webserver.

In diesem Dokument wird beschrieben, wie Sie ein OAuth-Token an einen Route Optimization API-Aufruf in Ihrer Entwicklungsumgebung übergeben. Weitere Informationen zur Verwendung von OAuth in einer Produktionsumgebung finden Sie unter Authentifizierungsmethoden bei Google.

Sie können Google Maps APIs direkt aufrufen, indem Sie API-Anfragen an den Server senden, oder Sie können Clientbibliotheken verwenden, um Ihren Code zu vereinfachen. Google Maps bietet Clientbibliotheken für Go, Java, Node.js und Python. Weitere Informationen finden Sie unter Route Optimization API-Clientbibliotheken.

OAuth-Übersicht

Je nach Bereitstellungsumgebung können Sie Zugriffstokens mit OAuth auf verschiedene Arten erstellen und verwalten.

Sie können OAuth 2.0 für Server-zu-Server-Interaktionen zwischen Ihrer Anwendung und einem Google-Dienst verwenden. In diesem Szenario verwenden Sie ein Dienstkonto, das mit Ihrer Anwendung und nicht mit einem einzelnen Nutzer verknüpft ist. Sie können API-Anfragen mit dem Dienstkonto stellen, ohne Nutzer direkt einzubeziehen. Weitere Informationen zu Authentifizierungsmethoden finden Sie unter Authentifizierungsmethoden bei Google.

Alternativ können Sie die Route Optimization API in eine mobile Android- oder iOS-App einbinden. Weitere Informationen zur Verwendung von OAuth und zur Verwaltung von Zugriffstokens für verschiedene Bereitstellungsumgebungen finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

OAuth-Bereiche

Wenn Sie OAuth mit der Route Optimization API verwenden möchten, müssen Sie dem OAuth-Token den folgenden Bereich zuweisen:

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

Rollen konfigurieren

In diesem Dokument finden Sie Informationen zu IAM-Rollen (Identity and Access Management) und Berechtigungen für die Routenoptimierung. Mit IAM können Sie detaillierte Zugriffsberechtigungen auf bestimmte Ressourcen der Routenoptimierung gewähren und unerwünschten Zugriff auf andere Ressourcen verhindern. Sie haben mit IAM die Möglichkeit, das Sicherheitsprinzip der geringsten Berechtigung anzuwenden, das besagt, dass niemand mehr Berechtigungen haben sollte, als er tatsächlich benötigt.

Wenn ein Hauptkonto (ein Nutzer, eine Gruppe oder ein Dienstkonto) eine Google Cloud API aufruft, muss dieses Hauptkonto die entsprechenden IAM-Berechtigungen für die Verwendung der Ressource haben. Um einem Hauptkonto die erforderlichen Berechtigungen zu gewähren, weisen Sie dem Hauptkonto eine IAM-Rolle zu.

Weitere Informationen zur Verwaltung des Zugriffs in Google Cloud im Allgemeinen finden Sie in der IAM-Übersicht.

Die vordefinierten IAM-Rollen, mit denen Hauptkonten auf die Routenoptimierung zugreifen können, sind:

• Route Optimization Editor (roles/routeoptimization.editor): Gewährt dem Nutzer oder Dienstkonto Lese- und Schreibzugriff auf Ressourcen zur Routenoptimierung im Projekt. Dazu gehört die Möglichkeit, OptimizeTours und BatchOptimizeTours aufzurufen sowie Vorgänge mit langer Ausführungszeit mit GetOperation abzurufen.
• Route Optimization Viewer (roles/routeoptimization.viewer): Gewährt Lesezugriff auf Ressourcen zur Routenoptimierung im Projekt. Diese Rolle ermöglicht das Aufrufen von OptimizeTours und den Zugriff auf Vorgänge mit langer Ausführungszeit über GetOperation.

gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

Weitere Informationen finden Sie unter IAM-Rolle mithilfe der Google Cloud Console gewähren.

Beispiel: REST API-Aufrufe in Ihrer lokalen Entwicklungsumgebung testen

Wenn Sie keine Umgebung haben, die Tokens generiert, und die Route Optimization API mit einem OAuth-Token ausprobieren möchten, folgen Sie der Anleitung in diesem Abschnitt.

In diesem Beispiel wird beschrieben, wie Sie das OAuth-Token verwenden, das von Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bereitgestellt wird, um den Aufruf auszuführen. Weitere Informationen zur Verwendung von ADC zum Aufrufen von Google APIs mit Clientbibliotheken finden Sie unter Mit Clientbibliotheken authentifizieren.

Verwenden Sie das folgende REST-Verfahren nur für die Entwicklung oder für Tests, nicht für die Produktion.

Vorbereitung

Bevor Sie eine REST-Anfrage mit ADC stellen, verwenden Sie die gcloud-Befehlszeile, um Anmeldedaten für ADC bereitzustellen:

1. Installieren und initialisieren Sie gcloud CLI. Weitere Informationen finden Sie unter gcloud CLI installieren.

2. Authentifizieren Sie sich mit der gcloud-Befehlszeile:

   gcloud auth application-default login

3. Schließen Sie die Anmeldung ab, um Ihre Anmeldedaten in der lokalen Anmeldedatendatei für ADC zu speichern.

Weitere Informationen finden Sie unter Standardanmeldedaten für Anwendungen für eine lokale Entwicklungsumgebung einrichten.

REST-Anfrage stellen

In diesem Beispiel übergeben Sie zwei Anfrageheader:

• Übergeben Sie das OAuth-Token im Authorization-Header. Verwenden Sie dazu den folgenden Befehl, um das Token zu generieren:

  gcloud auth application-default print-access-token

  Das zurückgegebene Token hat den Bereich https://www.googleapis.com/auth/cloud-platform.

• Übergeben Sie die ID oder den Namen Ihres Google Cloud-Projekts, für das die Abrechnung im Header X-Goog-User-Project aktiviert ist.

So rufen Sie die Route Optimization API mit einem OAuth-Token auf:

1. Ersetzen Sie im folgenden Codebeispiel PROJECT_NUMBER_OR_ID durch die Nummer oder ID Ihres Google Cloud-Projekts:

   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. Klicken Sie im Codebeispiel auf Kopieren, um den Befehl curl zu kopieren.

3. Fügen Sie den Befehl in ein Terminalfenster ein und führen Sie ihn aus.

Die Antwort ist ein JSON-Objekt:

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

Fehlerbehebung

Wenn Ihre Anfrage eine Fehlermeldung zurückgibt, die angibt, dass diese API keine Endnutzeranmeldedaten unterstützt, finden Sie weitere Informationen unter Fehlerbehebung für die ADC-Einrichtung.