اختيار الحقول المطلوب عرضها

المطوّرون في المنطقة الاقتصادية الأوروبية

عند تقديم طلب ترميز جغرافي، يمكنك استخدام قناع حقل لتحديد قائمة الحقول التي تريد عرضها في الاستجابة. تساعد أقنعة الحقول في تقليل وقت استجابة الطلب من خلال ضمان عدم طلب بيانات غير ضرورية.

بالنسبة إلى طرق الترميز الجغرافي الأساسية (الترميز الجغرافي لعنوان والترميز الجغرافي لموقع جغرافي والترميز الجغرافي لمكان)، يتم تلقائيًا عرض جميع الحقول في عنصر الاستجابة، على عكس البحث عن الوجهات حيث يجب تحديد قناع حقل. على الرغم من أنّ قناع الحقل ليس مطلوبًا للطرق الأساسية، ننصحك بشدة باستخدام قناع لتقليل وقت استجابة الردّ.

تحديد قناع حقل الاستجابة

قناع حقل الاستجابة هو قائمة قيم مفصولة بفاصلة بدون مسافات، حيث يحدّد كل مسار حقلاً فريدًا في كائن الاستجابة. يبدأ المسار من حقل الاستجابة ذي المستوى الأعلى ويستخدم مسارًا مفصولاً بنقاط إلى حقل محدّد.

يمكنك تمرير قناع حقل الاستجابة إلى طلب باستخدام مَعلمة عنوان 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][...]

البحث عن أقنعة حقول الوجهات

عند طلب 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.