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

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

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

برای روش‌های زمین‌کدیابی پایه (زمین‌کدیابی نشانی، زمین‌کدیابی مکان، و زمین‌کدیابی مکان)، همه فیلدها در شیء پاسخ به‌طور پیش‌فرض برگردانده می‌شوند، برخلاف جستجوی مقصدها که مشخص کردن ماسک فیلد الزامی است. اگرچه برای روش‌های پایه به ماسک فیلد نیازی نیست، قویاً توصیه می‌کنیم از آن برای کاهش تأخیر پاسخ استفاده کنید.

تعریف پوشش فیلد پاسخ

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

ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب $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][...]

جستجوی ماسک‌های فیلد مقصدها

هنگام فراخوانی SearchDestinations، مشخصه‌های دقیق مقصد موردنیازتان را مشخص کنید، مثل جزئیات مکان اصلی، ورودی‌ها، نقاط ناوبری، طرح کلی ساختمان (displayPolygon)، و نشان‌های مکان:

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

پوشش‌های فیلد زمین‌کدیابی اصلی

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

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 را ببینید.