Ausgewählte Routen erstellen

Auf dieser Seite wird beschrieben, wie Sie mit der Roads Selection API Routen erstellen und benutzerdefinierte Attribute hinzufügen.

Route erstellen

Senden Sie zum Erstellen einer Route eine POST-Anfrage an den Endpunkt create.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

Der Anfragetext muss ein JSON-Objekt sein, das die Ressource SelectedRoute definiert. Dieses Objekt enthält die folgenden Informationen:

  • Ein dynamicRoute-Objekt mit den folgenden Informationen:
  • Eine eindeutige selectedRouteId. Dieser Wert muss zwischen 4 und 63 Zeichen lang sein und nur alphanumerische Zeichen enthalten. Wenn Sie keine ID angeben, generiert das System eine eindeutige ID für die ausgewählte Route.

Das folgende Codebeispiel zeigt die Struktur einer POST-Anfrage an den Endpunkt create.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Bei Erfolg gibt die API die Ressource SelectedRoute zurück. Die Antwort enthält selectedRouteId im Feld name. Mit diesem selectedRouteId können Sie die SelectedRoute-Ressource abrufen oder löschen.

Das folgende Codebeispiel zeigt die Struktur einer erfolgreichen create-Endpunktantwort.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Routen im Batch erstellen

Wenn Sie mehrere Routen in einer einzigen Anfrage erstellen möchten, verwenden Sie den Endpunkt batchCreate. Mit diesem Endpunkt können Sie bis zu 1.000 Routen in einem Aufruf definieren.

Senden Sie eine POST-Anfrage an den Endpunkt batchCreate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

Die URL verwendet die Syntax der gRPC-Transcodierung.

Der Anfragetext muss ein JSON-Objekt mit einem requests-Array sein. Jedes Objekt in diesem Array ist ein CreateSelectedRouteRequest, das eine einzelne SelectedRoute-Ressource definiert.

Das folgende Codebeispiel zeigt die Struktur einer POST-Anfrage an den Endpunkt batchCreate:

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

Bei Erfolg gibt die API eine Antwort mit einem Array der erstellten SelectedRoute-Ressourcen zurück.

Das folgende Codebeispiel zeigt die Struktur einer Antwort des Endpunkts batchCreate:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Route mit Zwischenwegpunkten erstellen

Wenn Sie eine Route erstellen möchten, die bestimmte Punkte zwischen dem Start- und dem Zielpunkt durchläuft, fügen Sie in den Anfragetext ein intermediates-Array in das dynamicRoute-Objekt ein. Jedes Element im Array intermediates ist ein Wegpunkt, der durch seine latitude und longitude definiert wird. Eine Route kann bis zu 25 Wegpunkte haben.

Das folgende Codebeispiel zeigt, wie Sie ein SelectedRoute mit Zwischenzielen erstellen:

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Attribute benutzerdefinierter Routen verwenden

Um die Routenverwaltung und Datenanalyse in Roads Management Insights zu verbessern, enthält das SelectedRoute-Objekt das Feld route_attributes.

Verwenden Sie das Feld routeAttributes, um eigene benutzerdefinierte Eigenschaften für einzelne Routen zu definieren. Jedes Attribut ist ein Schlüssel/Wert-Paar. Sie können bis zu 10 benutzerdefinierte Schlüssel/Wert-Paare pro Route angeben.

Diese Attribute sind nützlich, um bestimmte Routen zu identifizieren oder Routen anhand von Kriterien zu gruppieren, die für Ihre Anforderungen relevant sind.

Hier sind einige Beispiele für Routenattribute, die Sie verwenden können:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

Beachten Sie beim Definieren des Felds routeAttributes die folgenden Richtlinien:

  • Schlüssel dürfen nicht mit dem Präfix goog beginnen.
  • Die Länge jedes Schlüssels und jedes Werts darf 100 Zeichen nicht überschreiten.

Sie können diese benutzerdefinierten routeAttributes dann in Roads Management Insights auf folgende Weise verwenden:

  • Pub/Sub-Benachrichtigungen filtern:Sie können Filter für Ihre Pub/Sub-Abos festlegen, um nur Updates für Routen zu erhalten, die bestimmten Attributschlüsseln und den entsprechenden Werten entsprechen oder nicht entsprechen.
  • BigQuery-Analyse optimieren:In Ihren BigQuery-Tabellen können Sie diese Attribute verwenden, um nach bestimmten Routen basierend auf dem Wert eines Attributs zu filtern. Sie können Routen auch nach einem bestimmten Attributschlüssel gruppieren, um gezieltere Datenanalysen durchzuführen.

Das nächste Codebeispiel zeigt, wie Sie ein SelectedRoute mit benutzerdefinierten routeAttributes erstellen.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"