Auswählen, welche Informationen zurückgegeben werden sollen

Wenn Sie eine Methode zum Berechnen einer Route oder zum Berechnen einer Routenmatrix aufrufen, müssen Sie angeben, welche Informationen in der Antwort zurückgegeben werden sollen. Es gibt keine Standardliste der zurückgegebenen Felder. Wenn Sie diese Liste auslassen, geben die Methoden einen Fehler zurück.

Zum Angeben der Feldliste erstellen Sie eine Antwortfeldmaske. Anschließend übergeben Sie die Antwortfeldmaske über den URL-Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask an eine der beiden Methoden.

Die Maskierung von Feldern hat sich bewährt, um sicherzustellen, dass keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und in Rechnung gestellte Kosten vermeiden.

Weitere Informationen zu URL-Parametern finden Sie unter Systemparameter.

Antwortfeldmaske definieren

Die Antwortfeldmaske ist eine durch Kommas getrennte Liste von Pfaden, wobei jeder Pfad ein eindeutiges Feld in der Antwortnachricht angibt. Der Pfad beginnt bei der Antwortnachricht der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.

Konstruieren Sie einen Feldpfad wie folgt:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Feldmaske für Compute-Route
    • REST: Gibt die Felder des Route-Objekts in der zurückzugebenden Antwort mit dem Präfix routes. an, z. B. routes.distanceMeters.
    • gRPC: Gibt die Felder des Route-Objekts in der Antwort an, die zurückgegeben werden sollen.
  • Feldmasken für Compute-Route-Matrix
    • REST: Gibt die Felder des Antworttexts an, die zurückgegeben werden sollen.
    • gRPC: Gibt die Felder des Objekts RouteMatrixElement in der zurückzugebenden Antwort an.

Weitere Informationen zum Erstellen von Feldmasken finden Sie unter field_mask.proto.

Bestimmen, welche Feldmasken verwendet werden

So legen Sie fest, welche Feldmasken Sie verwenden möchten:

  1. Fordern Sie alle Felder mit der Feldmaske * an.
  2. Sehen Sie sich die Hierarchie der Felder in der Antwort an und legen Sie die gewünschten Felder fest.
  3. Erstellen Sie die Feldmaske mithilfe der Feldhierarchie.

Hier ein Beispiel für diese Teilantwort von einer Route mit öffentlichen Verkehrsmitteln:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Wenn Sie nur das Feld distanceMeters zurückgeben möchten, lautet Ihre Feldmaske:

routes.legs.distanceMeters

Ein weiteres Beispiel: Wenn Sie alles unter legs in der Antwort zurückgeben möchten, lautet Ihre Feldmaske:

routes.legs

Feldpfad angeben

Dieser Abschnitt enthält Beispiele dazu, wie Sie einen Feldpfad als Teil einer Antwortfeldmaske angeben.

REST-Aufruf an computeRoutes

Im ersten Beispiel verwenden Sie einen REST-Aufruf an die Methode computeRoutes, um eine Route zu berechnen. In diesem Beispiel geben Sie im Header Feldmasken an, die die Felder Route.distanceMeters und Route.duration in der Antwort zurückgeben. Denken Sie daran, dem Feldnamen routes voranzustellen. 

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

REST-Aufruf an computeRouteMatrix

Geben Sie für die REST-Methode computeRouteMatrix, die zum Berechnen einer Routenmatrix verwendet wird, im Header an, dass für jede Kombination aus Start- und Zielort originIndex, destinationIndex und duration zurückgegeben werden sollen:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC-Aufruf

Legen Sie für gRPC eine Variable fest, die die Antwortfeldmaske enthält. Diese Variable können Sie dann an die Anfrage übergeben.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Überlegungen zu Feldpfaden

Geben Sie nur die Felder an, die in der Antwort erforderlich sind. Geben Sie nur die Felder zurück, die Sie benötigen:

  • Verringert die Verarbeitungszeiten, sodass die Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
  • Sorgt für eine stabile Latenzleistung, wenn die API in Zukunft weitere Antwortfelder hinzufügt und diese neuen Felder zusätzliche Rechenzeit erfordern. Wenn Sie alle Felder oder alle Felder auf der obersten Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn alle neuen Felder automatisch in Ihre Antwort aufgenommen werden.
  • Dies führt zu einer geringeren Antwortgröße, was zu einem höheren Netzwerkdurchsatz führt.
  • Es wird sichergestellt, dass keine unnötigen Daten angefordert werden. So vermeiden Sie unnötige Verarbeitungszeiten und in Rechnung gestellte Kosten.

Routentoken anfordern

Wenn Sie möchten, dass die Routes API Routentokens für generierte Routen zurückgibt, müssen Sie die Anforderungen für die Rückgabe eines Routentokens erfüllen. Verwenden Sie dann die Feldmaske routes.route_token, um das Token anzufordern:

  1. Setzen Sie travel_mode auf DRIVING.
  2. Legen Sie routing_preference auf TRAFFIC_AWARE oder TRAFFIC_AWARE_OPTIMAL fest.
  3. Achten Sie darauf, dass keiner der Wegpunkte der Route via-Wegpunkte ist.
  4. Geben Sie die Feldmaske des Routentokens an: 
    -H X-Goog-FieldMask: routes.route_token

Sie können Ihre geplante Route im Navigation SDK verwenden. Weitere Informationen finden Sie unter Route planen (Android) oder Route planen (iOS).

Beispiel für Routentoken

Hier sehen Sie ein Beispiel für einen cURL-Anfragetext für eine einzelne Startroute mit einem einzelnen Ziel. Dabei werden Feldmasken zum Anfordern eines Routentokens zusammen mit der Routendauer, der Entfernung und der Polylinie der Route verwendet:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Weitere Informationen finden Sie in der Referenz zur Compute Routes API.