Entwickler im Europäischen Wirtschaftsraum (EWR)

Zurückzugebende Felder 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 der obersten 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
Beispiele und weitere Informationen finden Sie in den folgenden Abschnitten.

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 „Compute Route“
    • REST: Gibt die Felder des Route-Objekts in der Antwort an, die zurückgegeben werden sollen. Sie müssen das Präfix routes. voranstellen, 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.

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. Verwenden Sie dazu dieses 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 distanceMeters unter steps im vorherigen Beispiel, sieht Ihre Feldmaske so aus:

routes.legs.steps.distanceMeters

Wenn Sie beides mit dem oben genannten Ergebnis 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 das Präfix 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

Legen Sie für gRPC eine Variable fest, die die Antwortfeldmaske enthält. Anschließend können Sie diese Variable an die Anfrage übergeben.

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

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 der obersten 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.