Escolher campos para retornar

Desenvolvedores do Espaço Econômico Europeu (EEE)

Introdução

Ao chamar os métodos Place Details (novo), Nearby Search (novo) ou Text Search (novo), é necessário especificar quais campos você quer que sejam retornados na resposta. Não há uma lista padrão de campos retornados. Se você omitir essa lista, os métodos vão retornar um erro.

Uma lista completa dos campos de dados compatíveis e das SKUs correspondentes pode ser encontrada em Campos de dados de lugar (novo). Para informações sobre campos específicos de cada API, consulte o seguinte:

  • Parâmetros FieldMask do Place Details (novo)
  • Parâmetros FieldMask do Nearby Search (novo)
  • Parâmetros FieldMask da Text Search (novo)

Para especificar a lista de campos, crie uma máscara de campo de resposta. Em seguida, transmita a máscara de campo de resposta para qualquer um dos métodos usando o parâmetro $fields ou fields ou usando o cabeçalho HTTP ou gRPC X-Goog-FieldMask.

A máscara de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças desnecessárias.

Definir uma máscara de campo de resposta

A máscara de campo de resposta é uma lista de caminhos separados por vírgulas, em que cada caminho especifica um campo exclusivo no corpo da resposta. O caminho começa na mensagem de resposta de nível superior e usa um caminho separado por pontos para o campo especificado.

Construa um caminho de campo da seguinte maneira:

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

É possível solicitar todos os campos usando uma máscara de campo de *.

Para mais informações sobre como criar máscaras de campo, consulte o field_mask.proto.

Determinar quais máscaras de campo usar

Veja como determinar quais máscaras de campo você quer usar:

  1. Solicite todos os campos usando uma máscara de campo de *.
  2. Analise a hierarquia dos campos na resposta e determine quais campos você quer.
  3. Crie sua máscara de campo usando a hierarquia de campos.

Definir uma máscara de campo de resposta para Nearby Search (novo) e Text Search (novo)

O Nearby Search (novo) e o Text Search (novo) retornam uma matriz de objetos Place no campo places da resposta. Para essas APIs, places é o campo de nível superior da resposta.

Por exemplo, para ver o objeto de resposta completo de uma pesquisa de texto (novo):

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'

O objeto de resposta completo de uma chamada de Text Search (New) está no formato:

{
  "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"
      },      ...
    },
  ...
  ]
}

Portanto, especifique uma máscara de campo para essas APIs no formato:

places[.secondLevelField][.thirdLevelField][...]

Se você quiser retornar apenas os campos formattedAddress e displayName, defina a máscara de campo como:

places.formattedAddress,places.displayName

Especificar displayName inclui os campos text e language de displayName. Se você quiser apenas o campo text, defina a máscara de campo como:

places.formattedAddress,places.displayName.text

Definir uma máscara de campo de resposta para Place Details (novo)

O Place Details (New) retorna um único objeto Place no formato:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

Portanto, especifique uma máscara de campo para essa API informando os campos do objeto Place que você quer retornar:

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

Chamada gRPC

Para gRPC, defina uma variável que contenha a máscara de campo de resposta. Em seguida, transmita essa variável à solicitação.

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

Considerações sobre o caminho do campo

Inclua apenas os campos necessários na resposta. Retornando apenas os campos necessários:

  • Diminui os tempos de processamento, para que os resultados sejam retornados com uma latência menor.
  • Garante um desempenho de latência estável se a API adicionar mais campos de resposta no futuro e esses novos campos exigirem mais tempo de computação. Se você selecionar todos os campos ou todos os campos no nível superior, poderá notar uma degradação da performance quando todos os novos campos forem incluídos automaticamente na sua resposta.
  • Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de processamento da rede.
  • Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças desnecessárias.