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

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

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

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

تحديد قناع حقل الردّ

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

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