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

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

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

  • مَعلمات 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"
  }
  ...
}

لذلك، يمكنك تحديد قناع حقل لواجهة برمجة التطبيقات هذه من خلال تحديد حقول ملف تعريف 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"
)

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

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

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