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á lista padrão de campos retornados. Se você omitir essa lista, os métodos retornarão 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 prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e faturamento desnecessários cargas.
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 no 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 construir máscaras de campo, consulte o field_mask.proto (link em inglês).
Determinar as máscaras de campo a serem usadas
Confira como determinar quais máscaras de campo você quer usar:
- Solicite todos os campos usando uma máscara de campo de "*".
- Observe a hierarquia dos campos na resposta e determine quais nos campos desejados.
- 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 um Text Search (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 um Text Search (novo) 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, você especifica uma máscara de campo para essas APIs no formato:
places[.secondLevelField][.thirdLevelField][...]
Se você quiser retornar apenas os campos formattedAddress e displayName, defina
sua máscara de campo para:
places.formattedAddress,places.displayName
Especificar displayName inclui os campos text e language do
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 de o 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 contendo a máscara do campo de resposta. Você pode transmitir 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. Retornar apenas necessários:
- Diminui o tempo de processamento, para que seus resultados sejam retornados com uma latência de rede.
- Garante um desempenho de latência estável se a API adicionar mais campos de resposta. no futuro, e esses novos campos vão exigir 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.
- Resultados em uma resposta menor, o que resulta em uma rede maior e aumentar a capacidade de processamento.
- Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças.