Ausgewählte Routen erstellen

Auf dieser Seite wird beschrieben, wie Sie mit der Roads Selection API Routen erstellen und benutzerdefinierte Attribute hinzufügen. Die folgenden Abschnitte enthalten weitere Informationen:

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 SelectedRoute-Ressource definiert. Dieses Objekt enthält die folgenden Informationen:

  • Ein dynamicRoute-Objekt mit den folgenden Informationen:
  • Eine eindeutige selectedRouteId. Dieser Wert sollte 4 bis 63 Zeichen umfassen. Gültige Zeichen sind a-z, A-Z, 0-9, - oder _. Wenn keine ID angegeben ist, 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 '
    {
      "dynamicRoute": {
        "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 die selectedRouteId im Feld name. Sie können diese selectedRouteId verwenden, um die SelectedRoute-Ressource abzurufen oder zu 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"
}

Route mit Zwischenwegpunkten erstellen

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

Das folgende Codebeispiel zeigt, wie Sie eine SelectedRoute mit Zwischenwegpunkten erstellen:

curl -X POST -d '
    {
      "dynamicRoute": {
        "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"

Benutzerdefinierte Routenattribute verwenden

Zur Verbesserung des Routenmanagements und der Datenanalyse in Roads Management Insights enthält das SelectedRoute-Objekt ein routeAttributes-Feld.

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 25 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 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.

Diese benutzerdefinierten routeAttributes können Sie dann in Roads Management Insights folgendermaßen 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 mit bestimmten Attributschlüsseln und den entsprechenden Werten übereinstimmen oder nicht übereinstimmen.
  • BigQuery-Analyse verfeinern:In Ihren BigQuery-Tabellen können Sie diese Attribute verwenden, um nach bestimmten Routen anhand des Attributwerts zu filtern. Sie können Routen auch nach einem bestimmten Attributschlüssel gruppieren, um eine gezieltere Datenanalyse zu ermöglichen.

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

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "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"

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 batchCreate-Endpunkt:

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 sein, das ein requests-Array enthält. 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": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "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 batchCreate-Endpunktantwort:

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