Entwickler im Europäischen Wirtschaftsraum (EWR)

Felder auswählen, die zurückgegeben werden sollen

Wenn Sie eine Route oder 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 wird auch verhindert, dass unnötige Daten angefordert werden. Das wiederum hilft, die Antwortlatenz zu verringern und die Rückgabe von Informationen zu vermeiden, 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, indem Sie den URL-Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask verwenden.

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

Erstellen und geben Sie einen Feldpfad so an:

  1. Suchen Sie die Felder, die die benötigten Informationen enthalten. Weitere Informationen finden Sie unter Feldverweise.
  2. Pfade für die benötigten Felder ermitteln und Feldmasken dafür erstellen: Weitere Informationen finden Sie unter Feldmaske bestimmen, die Sie verwenden möchten.

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

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

  4. Feldmaske mit der API-Anfrage senden In einer curl-Anfrage würden Sie die Feldmaske beispielsweise mit -H und X-Goog-FieldMask angeben:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Beispiele und weitere Informationen finden Sie in den folgenden Abschnitten.

Feldverweise

Die Felder, die Sie in einer Antwort über Feldmasken anfordern können, finden Sie in den Referenzen zur Routes API für „Compute Routes“ oder „Compute Route Matrix“, die in der folgenden Liste verlinkt sind. Geben Sie 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 beachten, um den vollständigen Pfad der Feldmaske zu bestimmen. Weitere Informationen zum Abrufen der Hierarchie der Felder finden Sie unter Feldmaske bestimmen, die Sie verwenden möchten.

  • Feldmaske für „Route berechnen“
    • REST: Gibt die Felder des Route-Objekts in der Antwort an, die zurückgegeben werden sollen, mit dem Präfix routes., 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 RouteMatrixElement-Objekts in der Antwort an, die zurückgegeben werden sollen.

Zu verwendende Feldmasken bestimmen

So können Sie festlegen, welche Felder Sie verwenden möchten, und die Feldmasken dafür erstellen:

  1. Alle Felder anfordern mit der Feldmaske *.
  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, die im vorherigen Schritt gezeigt wurden, im folgenden Format:

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

Beispiel für eine Teilantwort von einer Route:

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

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

routes.legs.distanceMeters

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

routes.legs.steps.distanceMeters

Wenn Sie beide zurückgeben möchten, sieht die Feldmaske mit dem obigen Ergebnis so aus:

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

Beispielpfade für Feldmasken

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 an computeRoutes

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

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 originIndex, destinationIndex und duration für jede Kombination aus Start- und Zielort zurückgegeben werden sollen:

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC-Aufruf an computeRoutes

Legen Sie für die gRPC-Methode computeRoutes, die zum Berechnen einer Route verwendet wird, eine Variable mit der Antwortfeldmaske fest, damit die Felder distanceMeters, duration und die codierte Polylinie in der Antwort zurückgegeben werden. Sie können diese Variable dann an die Anfrage übergeben:

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

gRPC-Aufruf an computeRouteMatrix

Legen Sie für die gRPC-Methode computeRouteMatrix, die zum Berechnen einer Routenmatrix verwendet wird, eine Variable mit der Antwortfeldmaske fest, um anzugeben, dass originIndex, destinationIndex und duration für jede Kombination aus Start- und Zielort zurückgegeben werden sollen. Sie können diese Variable dann an die Anfrage übergeben:

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

Hinweise zu Feldpfaden

Geben Sie nur die Felder an, die Sie in der Antwort benötigen, damit nur diese Felder zurückgegeben werden:

  • Verkürzt die Verarbeitungszeiten, sodass die Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
  • Sorgt für eine stabile Latenzleistung. Wenn Sie alle Felder oder alle Felder auf der obersten Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn neue Felder hinzugefügt und dann automatisch in die Antwort aufgenommen werden.
  • Führt zu einer kleineren Antwortgröße, was zu einem höheren Netzwerkdurchsatz führt.
  • Sie verhindern, 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.