Escolher campos para retornar

Quando você chama a função Place Details (Novo), Nearby Search (novo) ou Pesquisa de texto (New), é necessário especificar quais campos quer retornar 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.

Para especificar a lista de campos, crie uma máscara de campo de resposta. Depois, você transmite máscara do 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.

O mascaramento 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ça desnecessários.

Definir uma máscara de campo de resposta

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

Crie 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 as máscaras de campo a serem usadas

Confira 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. Criar sua máscara de campo usando a hierarquia de campos.

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

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

Por exemplo, para ver o objeto de resposta completo de uma Text Search (nova):

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 Text Search (New) é do tipo:

{
  "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

A especificação de 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 retorna um único objeto Place no formulário:

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

Portanto, você especifica uma máscara de campo para essa API especificando os campos do objeto Place que 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 contendo a máscara do campo de resposta. Em seguida, é possível transmitir essa variável para a solicitação.

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

Considerações sobre o caminho do campo

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

• Diminui os tempos de processamento, para que os resultados sejam retornados com uma latência menor.
• Garante desempenho de latência estável se a API adicionar mais campos de resposta no futuro e esses novos campos exigirem tempo de computação extra. Se você selecione todos os campos ou se você selecionar todos os campos no nível superior, poderá degradação do desempenho quando todos os campos novos são incluído automaticamente em 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 desnecessário e cobranças.