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

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

وقتی یک درخواست geocoding ارسال می‌کنید، می‌توانید از یک ماسک فیلد برای مشخص کردن لیست فیلدهایی که باید در پاسخ برگردانده شوند استفاده کنید. برای Geocode an address ، Geocode a location و Place geocoding endpoints، تمام فیلدهای موجود در شیء پاسخ به طور پیش‌فرض برگردانده می‌شوند. برای Search for destinations endpoint، باید یک ماسک فیلد در درخواست API مشخص کنید.

از یک ماسک فیلد استفاده کنید تا مطمئن شوید که داده‌های غیرضروری درخواست نمی‌کنید، که به نوبه خود به کاهش تأخیر پاسخ کمک می‌کند.

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

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

ماسک فیلد پاسخ را با استفاده از پارامتر 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 در پاسخ، از یک ماسک فیلد به صورت زیر استفاده کنید:

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/v4beta/"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 مراجعه کنید.