Wenn Sie die Methoden Place Details (neu), Nearby Search (neu) oder Text Search (neu) aufrufen, müssen Sie angeben, welche Felder in der Antwort zurückgegeben werden sollen. Es gibt keine Standardliste der zurückgegebenen Felder. Wenn Sie diese Liste weglassen, geben die Methoden einen Fehler zurück.
Eine vollständige Liste der unterstützten Datenfelder und ihrer entsprechenden SKUs finden Sie unter Place Data Fields (New) (Felder für Ortsdaten (neu)). Informationen zu den API-spezifischen Feldern finden Sie unter:
- FieldMask-Parameter für „Place Details (New)“
- FieldMask-Parameter für Nearby Search (New)
- FieldMask-Parameter für die Textsuche (neu)
Sie geben die Feldliste an, indem Sie eine Antwortfeldmaske erstellen. Sie übergeben die Antwortfeldmaske dann an eine der Methoden, indem Sie den Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask verwenden.
Das Maskieren von Feldern ist eine gute Designpraxis, um sicherzustellen, dass keine unnötigen Daten angefordert werden. Dadurch werden unnötige Verarbeitungszeiten und Abrechnungskosten vermieden.
Antwortfeldmaske definieren
Die Antwortfeldmaske ist eine durch Kommas getrennte Liste von Pfaden, wobei jeder Pfad ein eindeutiges Feld im Antworttext angibt. Der Pfad beginnt bei der Antwortnachricht der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.
So erstellen Sie einen Feldpfad:
topLevelField[.secondLevelField][.thirdLevelField][...]
Sie können alle Felder anfordern, indem Sie eine Feldmaske von * verwenden.
Weitere Informationen zum Erstellen von Feldmasken finden Sie unter field_mask.proto.
Feldmasken festlegen
So legen Sie fest, welche Feldmasken verwendet werden sollen:
- Fordere alle Felder mit einem Feldmaskenwert von
*an. - Sehen Sie sich die Hierarchie der Felder in der Antwort an und ermitteln Sie, welche Felder Sie benötigen.
- Erstellen Sie die Feldmaske anhand der Feldhierarchie.
Antwortfeldmaske für Nearby Search (neu) und Text Search (neu) definieren
Die Nearby Search (Neu) und die Text Search (Neu) geben im Feld places der Antwort ein Array von Ortsobjekten zurück. Bei diesen APIs ist places das Feld der obersten Ebene der Antwort.
So rufen Sie beispielsweise das vollständige Antwortobjekt einer Textsuche (neu) auf:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'Das vollständige Antwortobjekt eines „Text Search (New)“-Aufrufs hat folgendes Format:
{ "places": [ { "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0", "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0", "types": [ "vegetarian_restaurant", "vegan_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "nationalPhoneNumber": "0433 479 794", "internationalPhoneNumber": "+61 433 479 794", "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Spiced @ Barangaroo", "languageCode": "en" }, ... }, ... ] }
Daher geben Sie für diese APIs eine Feldmaske in folgendem Format an:
places[.secondLevelField][.thirdLevelField][...]
Wenn Sie nur die Felder formattedAddress und displayName zurückgeben möchten, legen Sie die Feldmaske so fest:
places.formattedAddress,places.displayName
Wenn Sie displayName angeben, werden sowohl die Felder text als auch language von displayName berücksichtigt. Wenn Sie nur das Feld text benötigen, legen Sie die Feldmaske so fest:
places.formattedAddress,places.displayName.text
Antwortfeldmaske für „Ortsdetails (neu)“ definieren
Place Details gibt ein einzelnes Ortsobjekt in der folgenden Form zurück:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "types": [ "locality", "political" ], "formattedAddress": "Trinidad, CA 95570, USA", "displayName": { "text": "Trinidad", "languageCode": "en" } ... }
Daher geben Sie für diese API eine Feldmaske an, indem Sie die Felder des Ortsobjekts angeben, die zurückgegeben werden sollen:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: formattedAddress,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
gRPC-Aufruf
Legen Sie für gRPC eine Variable mit der Antwortfeldmaske fest. Diese Variable können Sie dann an die Anfrage übergeben.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Hinweise zum Feldpfad
Fügen Sie der Antwort nur die Felder hinzu, die Sie benötigen. Gib nur die Felder zurück, die du benötigst:
- Reduziert die Verarbeitungszeiten, sodass die Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
- Sorgt für eine stabile Latenzleistung, wenn der API in Zukunft weitere Antwortfelder hinzugefügt werden und diese neuen Felder zusätzliche Rechenzeit erfordern. Wenn Sie alle Felder oder alle Felder der obersten Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn alle neuen Felder automatisch in die Antwort aufgenommen werden.
- Die Antwortgröße ist kleiner, was zu einem höheren Netzwerkdurchsatz führt.
- Sie sorgen dafür, dass Sie keine unnötigen Daten anfordern, was unnötige Verarbeitungszeiten und in Rechnung gestellte Kosten vermeidet.