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

مقدمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تحديد قناع حقل الردود لكلّ من Nearby Search (New) وText Search (New)

تعرض كلّ من "بحث في الجوار" (إصدار جديد) و"البحث النصي" (إصدار جديد) مصفوفة من عناصر Place في الحقل 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

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

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

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

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

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"
)

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

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

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