Felder für die Rückgabe auswählen

Wenn Sie die Methoden Place Details (New), Nearby Search (New) oder Text Search (New) 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.

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

Die Maskierung von Feldern hat sich bewährt, um sicherzustellen, dass keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.

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.

Erstellen Sie einen Feldpfad:

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

Sie können alle Felder mit der Feldmaske * anfordern.

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

Bestimmen, welche Feldmasken verwendet werden sollen

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

  1. Fordert alle Felder mit einer Feldmaske von "*" an.
  2. Sehen Sie sich die Hierarchie der Felder in der Antwort an und legen Sie fest, welche Felder Sie verwenden möchten.
  3. Erstellen Sie Ihre Feldmaske mithilfe der Feldhierarchie.

Definieren Sie eine Antwortfeldmaske für Nearby Search (New) und Text Search (New)

„Nearby Search (New)“ und „Text Search (New)“ geben ein Array von „Place“-Objekten im Feld places der Antwort 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) ab:

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 das folgende 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 eine Feldmaske für diese APIs im folgenden 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, sind sowohl das Feld text als auch das Feld language von displayName enthalten. Wenn Sie nur das Feld text haben möchten, legen Sie die Feldmaske so fest:

places.formattedAddress,places.displayName.text

Antwortfeldmaske für „Place Details“ definieren (Neu)

„Place Details“ gibt ein einzelnes „Place“-Objekt im folgenden Format 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 eine Feldmaske für diese API an. Dazu geben Sie die Felder des Place-Objekts an, das Sie zurückgeben möchten:

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 fest, die die Antwortfeldmaske enthält. Sie können diese Variable dann an die Anfrage übergeben.

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

Überlegungen zu Feldpfaden

Nehmen Sie nur die erforderlichen Felder in die Antwort auf. Nur die benötigten Felder werden zurückgegeben:

  • Verringert die Verarbeitungszeiten, sodass Ihre Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
  • Sorgt für eine stabile Latenzleistung, falls die API künftig 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.
  • Ergibt eine kleinere Antwortgröße, was zu einem höheren Netzwerkdurchsatz führt.
  • Sorgt dafür, dass keine unnötigen Daten angefordert werden, sodass unnötige Verarbeitungszeiten und in Rechnung gestellte Kosten vermieden werden.