Place Details(新)、 Nearby Search(新)、 テキスト検索(新)のメソッドを呼び出すときは、レスポンスで返すフィールドを指定する必要があります。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。
レスポンス フィールド マスクを作成して、フィールド リストを指定します。次に、パラメータ $fields
または fields
を使用するか、HTTP ヘッダーまたは gRPC ヘッダー X-Goog-FieldMask
を使用して、いずれかのメソッドにレスポンス フィールド マスクを渡します。
フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計プラクティスです。これにより、不要な処理時間と課金を回避できます。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、パスのカンマ区切りのリストです。各パスは、レスポンス メッセージ内の一意のフィールドを指定します。パスは、最上位のレスポンス メッセージから始まり、指定されたフィールドへのドット区切りパスを使用します。
フィールドパスを次のように作成します。
topLevelField[.secondLevelField][.thirdLevelField][...]
すべてのフィールドをリクエストするには、*
のフィールド マスクを使用します。
フィールド マスクの作成方法の詳細については、field_mask.proto をご覧ください。
使用するフィールド マスクを決定する
使用するフィールド マスクを判断する方法は次のとおりです。
- 「*」のフィールド マスクを使用してすべてのフィールドをリクエストします。
- レスポンスに含まれるフィールドの階層を確認して、必要なフィールドを決定します。
- フィールド階層を使用してフィールド マスクを作成します。
Nearby Search(新版)とテキスト検索(新版)のレスポンス フィールド マスクを定義する
Nearby Search(新版)とテキスト検索(新版)は、レスポンスの places
フィールドに Place オブジェクトの配列を返します。これらの API の場合、places
はレスポンスの最上位フィールドです。
たとえば、テキスト検索(新版)からの完全なレスポンス オブジェクトを表示するには、次のようにします。
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'
テキスト検索(新版)の呼び出しに対する完全なレスポンス オブジェクトの形式は、以下のようになります。
{ "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" }, ... }, ... ] }
したがって、これらの API のフィールド マスクを次の形式で指定します。
places[.secondLevelField][.thirdLevelField][...]
formattedAddress
フィールドと displayName
フィールドのみを返す場合は、フィールド マスクを次のように設定します。
places.formattedAddress,places.displayName
displayName
を指定すると、displayName
の text
フィールドと language
フィールドの両方が含まれます。text
フィールドのみが必要な場合は、フィールド マスクを次のように設定します。
places.formattedAddress,places.displayName.text
Place Details のレスポンス フィールド マスクを定義する(新)
Place Details は、次の形式で 1 つのプレイス オブジェクトを返します。
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "types": [ "locality", "political" ], "formattedAddress": "Trinidad, CA 95570, USA", "displayName": { "text": "Trinidad", "languageCode": "en" } ... }
したがって、返したい Place オブジェクトのフィールドを指定して、この API のフィールド マスクを指定します。
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 呼び出し
gRPC の場合は、レスポンス フィールド マスクを含む変数を設定します。その変数をリクエストに渡すことができます。
const ( fieldMask = "places.formattedAddress,places.displayName" )
フィールドパスに関する考慮事項
レスポンスには必要なフィールドのみを含めます。必要なフィールドのみを返します。
- 処理時間が短縮されるため、低レイテンシで結果が返されます。
- 今後 API でレスポンス フィールドが追加され、それらの新しいフィールドで計算時間がさらに必要になる場合でも、安定したレイテンシ パフォーマンスを確保できます。すべてのフィールドを選択した場合、または最上位のフィールドをすべて選択すると、新しいフィールドがすべてレスポンスに自動的に含まれるときに、パフォーマンスが低下する可能性があります。
- レスポンス サイズが小さくなり、ネットワーク スループットが向上します。
- 不要なデータをリクエストしないようにします。これにより、不要な処理時間と料金を回避できます。