فیلدهایی را برای بازگشت انتخاب کنید

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

وقتی یک درخواست geocoding ارسال می‌کنید، می‌توانید از یک field mask برای مشخص کردن لیست فیلدهایی که باید در پاسخ برگردانده شوند استفاده کنید. field maskها با اطمینان از اینکه داده‌های غیرضروری درخواست نمی‌کنید، به کاهش تأخیر پاسخ کمک می‌کنند.

برای متدهای Geocode an address ، Geocode a location و Place geocoding ، تمام فیلدهای موجود در شیء پاسخ به طور پیش‌فرض برگردانده می‌شوند. اگرچه استفاده از ماسک فیلد الزامی نیست، اما اکیداً توصیه می‌کنیم برای کاهش تأخیر پاسخ از آنها استفاده کنید.

تعریف ماسک فیلد پاسخ

ماسک فیلد پاسخ، فهرستی از مسیرها است که با کاما از هم جدا شده‌اند و هیچ فاصله‌ای ندارند، که در آن هر مسیر، یک فیلد منحصر به فرد را در شیء پاسخ مشخص می‌کند. این مسیر از فیلد پاسخ سطح بالا شروع می‌شود و از یک مسیر جدا شده با نقطه به یک فیلد مشخص شده استفاده می‌کند.

ماسک فیلد پاسخ را با استفاده از پارامتر URL $fields یا fields یا با استفاده از هدر HTTP یا gRPC X-Goog-FieldMask به یک درخواست ارسال کنید.

مثال ماسک‌های میدانی

در زیر پاسخ کامل یک درخواست ژئوکدینگ رو به جلو نشان داده شده است:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

ماسک‌های فیلد خود را با استفاده از سلسله مراتب فیلدهای پاسخ، به شکل زیر بسازید:

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

برای مثال، برای برگرداندن فقط فیلد placeId در پاسخ، از یک field mask به شکل زیر استفاده کنید:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA

پاسخ اکنون این است:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

برای برگرداندن فیلد viewport ، ماسک فیلد شما به صورت زیر است:

-H 'X-Goog-FieldMask: results.viewport'

پاسخ اکنون این است:

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

برای برگرداندن هر دو:

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

پاسخ اکنون این است:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

ماسک‌های میدانی gRPC

برای gRPC، یک متغیر حاوی ماسک فیلد پاسخ تنظیم کنید. سپس می‌توانید آن متغیر را به درخواست ارسال کنید.

const (
  fieldMask = "results.placeId,results.viewport"
)

ملاحظات مسیر میدان

فقط فیلدهایی را که در پاسخ نیاز دارید، وارد کنید تا فقط فیلدهایی که نیاز دارید را برگردانید:

  • زمان پردازش را کاهش می‌دهد ، بنابراین نتایج شما با تأخیر کمتری بازگردانده می‌شوند.
  • عملکرد با تأخیر پایدار را تضمین می‌کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است هنگام اضافه شدن فیلدهای جدید و سپس قرار گرفتن خودکار آنها در پاسخ شما، با افت عملکرد مواجه شوید.
  • منجر به اندازه پاسخ کوچکتر می‌شود که به معنای افزایش توان عملیاتی شبکه است.

برای جزئیات بیشتر در مورد ساخت یک ماسک میدانی، به field_mask.proto مراجعه کنید.