Felder für die Rückgabe auswählen

Wenn Sie eine Route oder eine Routenmatrix anfordern, müssen Sie eine Feldmaske verwenden, um anzugeben, welche Informationen in der Antwort zurückgegeben werden sollen. Es gibt keine Standardliste der zurückgegebenen Felder. Wenn Sie keine Feldmaske angeben, geben die Methoden einen Fehler zurück.

Mit einer Feldmaske lässt sich auch verhindern, dass unnötige Daten angefordert werden , was wiederum die Antwortlatenz verbessert und vermeidet, dass Informationen zurückgegeben werden, die Ihr System nicht benötigt.

Sie geben die Liste der benötigten Felder in einer Antwortfeldmaske an. Anschließend übergeben Sie die Antwortfeldmaske an eine der beiden Methoden. Verwenden Sie dazu den URL-Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask.

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 mit der Antwortnachricht auf oberster Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.

So erstellen und geben Sie einen Feldpfad an:

1. Suchen Sie die Felder, die die benötigten Informationen enthalten. Weitere Informationen finden Sie unter Feldverweise.
2. Bestimmen Sie die Pfade für die benötigten Felder und erstellen Sie die Feldmasken dafür. Weitere Informationen finden Sie unter Feldmaske auswählen.

3. Kombinieren Sie die Feldmasken für alle benötigten Felder und trennen Sie sie durch Kommas. Wenn Sie beispielsweise distanceMeters für die Routenstrecke und die Dauer für jeden Schritt der Routenstrecke anfordern möchten, geben Sie beide durch ein Komma getrennt ohne Leerzeichen ein:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. Senden Sie die Feldmaske mit Ihrer API-Anfrage. In einer Curl-Anfrage geben Sie die Feldmaske beispielsweise mit -H und X-Goog-FieldMask an:

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

Feldverweise

In den Referenzen zur Routes API Compute Routes oder Compute Route Matrix, die in der folgenden Liste verlinkt sind, finden Sie die Felder, die Sie in einer Antwort über Feldmasken anfordern können. Geben Sie die Felder in Camel-Case-Schreibweise an, wie in der Referenz gezeigt. Beispiel: routePreference.

Diese Referenzen enthalten die verfügbaren Felder. Sie müssen jedoch die Hierarchie der Felder berücksichtigen, um den vollständigen Feldmaskenpfad zu bestimmen. Weitere Informationen zum Abrufen der Hierarchie der Felder finden Sie unter Feldmaske auswählen.

• Feldmaske für die Routenberechnung
  • REST: Gibt die Felder des Route-Objekts in der Antwort an, die zurückgegeben werden sollen. Sie werden mit routes. vorangestellt, z. B. routes.distanceMeters.
  • gRPC: Gibt die Felder des Route-Objekts in der Antwort an, die zurückgegeben werden sollen.
• Feldmasken für die Routenmatrixberechnung
  • REST: Gibt die Felder des Antworttexts an, die zurückgegeben werden sollen.
  • gRPC: Gibt die Felder des RouteMatrixElement Objekts in der Antwort an, die zurückgegeben werden sollen.

Feldmasken auswählen

So können Sie die gewünschten Felder bestimmen und die Feldmasken dafür erstellen:

1. Fordern Sie alle Felder an , indem Sie die Feldmaske * verwenden.
2. Sehen Sie sich die Hierarchie der Felder in der Antwort für die gewünschten Felder an.

3. Erstellen Sie Ihre Feldmasken anhand der Hierarchie der Felder aus dem vorherigen Schritt im folgenden Format:

   topLevelField[.secondLevelField][.thirdLevelField][...]

Beispiel für eine Teilausgabe einer Route:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Wenn Sie nur das Feld distanceMeters für die Routenstrecke zurückgeben möchten, also das letzte distanceMeters im vorherigen Beispiel, sieht Ihre Feldmaske so aus:

routes.legs.distanceMeters

Wenn Sie stattdessen das Feld distanceMeters für jeden Schritt der Routenstrecke zurückgeben möchten, also das distanceMeters unter steps im vorherigen Beispiel, sieht Ihre Feldmaske so aus:

routes.legs.steps.distanceMeters

Wenn Sie beides mit dem Ergebnis oben zurückgeben möchten, sieht Ihre Feldmaske so aus:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Beispiele für Feldmaskenpfade

In diesem Abschnitt finden Sie weitere Beispiele dafür, wie Sie einen Feldpfad als Teil einer Antwortfeldmaske in REST- und gRPC-Aufrufen angeben.

REST-Aufruf von computeRoutes

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

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

REST-Aufruf von computeRouteMatrix

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC-Aufruf von computeRoutes

Für die gRPC-Methode computeRoutes, die zum Berechnen einer Route verwendet wird, legen Sie eine Variable fest, die die Antwortfeldmaske enthält, um die Felder distanceMeters, duration und die codierte Polylinie der Route in der Antwort zurückzugeben. Anschließend können Sie diese Variable an die Anfrage übergeben:

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

gRPC-Aufruf von computeRouteMatrix

Für die gRPC-Methode computeRouteMatrix, die zum Berechnen einer Routenmatrix verwendet wird, legen Sie eine Variable fest, die die Antwortfeldmaske enthält, um anzugeben, dass originIndex, destinationIndex und duration für jede Kombination aus Start- und Zielort zurückgegeben werden sollen. Anschließend können Sie diese Variable an die Anfrage übergeben:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Hinweise zu Feldpfaden

Schließen Sie nur die Felder ein, die Sie in der Antwort benötigen, um nur die Felder zurückzugeben, die Sie benötigen:

• Verkürzt die Verarbeitungszeiten, sodass Ihre Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
• Sorgt für eine stabile Latenzleistung. Wenn Sie alle Felder oder alle Felder auf oberster Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn neue Felder hinzugefügt werden und dann automatisch in Ihre Antwort aufgenommen werden.
• Führt zu einer kleineren Antwortgröße, was einen höheren Netzwerkdurchsatz bedeutet.
• Verhindert, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.

Weitere Informationen zum Erstellen einer Feldmaske finden Sie unter field_mask.proto.