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

مقدمة

عند طلب البيانات باستخدام الطرق Place Details (New) أو Nearby Search (New) أو Text Search (New)، عليك تحديد الحقول التي تريد عرضها في الردّ. لا توجد قائمة تلقائية بالحقول التي يتم عرضها. في حال إغفال هذه القائمة، ستعرض الطرق خطأً.

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

• مَعلمات FieldMask الخاصة بـ "تفاصيل المكان" (جديد)
• مَعلمات Nearby Search (New) FieldMask
• ‫Text Search (جديد) 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 هو الحقل ذو المستوى الأعلى في الرد.

على سبيل المثال، للاطّلاع على عنصر الاستجابة الكامل من Text Search (New):

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

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

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

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