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

مقدمة

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

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

• مَعلمات FieldMask في تفاصيل المكان (جديد)
• مَعلمات FieldMask في بحث في الجوار (جديد)
• مَعلمات FieldMask في ميزة "البحث النصي (الجديد)"

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل استجابة. بعد ذلك، يمكنك تمرير قناع حقل الاستجابة إلى أيّ من الطريقتَين باستخدام المَعلمة $fields أو fields، أو باستخدام عنوان HTTP أو gRPC‏ X-Goog-FieldMask.

يُعدّ إخفاء الحقول من الممارسات الجيدة في التصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة ورسوم الفوترة غير الضرورية.

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

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

أنشئ مسار حقل على النحو التالي:

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

يمكنك طلب جميع الحقول باستخدام قناع حقل *.

لمزيد من المعلومات حول كيفية إنشاء أقنعة الحقول، يُرجى الاطّلاع على field_mask.proto.

تحديد أقنعة الحقول المطلوب استخدامها

في ما يلي كيفية تحديد أقنعة الحقول التي تريد استخدامها:

1. اطلب جميع الحقول باستخدام قناع حقل *.
2. اطّلِع على التسلسل الهرمي للحقول في الاستجابة، وحدِّد الحقول التي تريدها.
3. أنشئ قناع الحقل باستخدام التدرج الهرمي للحقول.

تحديد قناع حقل الاستجابة لخدمتَي "البحث في الجوار (جديد)" و"البحث النصي (جديد)"

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

على سبيل المثال، للاطّلاع على عنصر الاستجابة الكامل من "البحث النصي (الجديد)":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'

يكون عنصر الاستجابة الكامل من طلب "البحث النصي (الجديد)" على النحو التالي:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Spiced @ Barangaroo",
        "languageCode": "en"
      },      ...
    },
  ...
  ]
}

لذلك، يمكنك تحديد قناع حقل لواجهات برمجة التطبيقات هذه في النموذج:

places[.secondLevelField][.thirdLevelField][...]

إذا أردت عرض الحقلَين formattedAddress وdisplayName فقط، اضبط قناع الحقل على:

places.formattedAddress,places.displayName

يؤدي تحديد displayName إلى تضمين الحقلَين text وlanguage في displayName. إذا كنت تريد حقل text فقط، اضبط قناع الحقل على النحو التالي:

places.formattedAddress,places.displayName.text

تحديد قناع حقل الاستجابة لخدمة "تفاصيل المكان (جديد)"

تعرض خدمة "تفاصيل المكان (جديدة)" عنصر "مكان" واحدًا بالشكل التالي:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

لذلك، يمكنك تحديد قناع حقل لواجهة برمجة التطبيقات هذه من خلال تحديد حقول عنصر "المكان" التي تريد عرضها:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: formattedAddress,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

مكالمة gRPC

بالنسبة إلى gRPC، اضبط متغيّرًا يحتوي على قناع حقل الاستجابة. يمكنك بعد ذلك تمرير هذا المتغير إلى الطلب.

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

اعتبارات مسار الحقل

أدرِج فقط الحقول التي تحتاجها في الردّ. عرض الحقول التي تحتاجها فقط:

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