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

مقدمة

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

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

• تفاصيل المكان (جديد) 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 هو الحقل ذو المستوى الأعلى في الاستجابة.

على سبيل المثال، للاطّلاع على كائن الردّ المكتمل من البحث النصي (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'

يكون كائن الاستجابة الكامل من طلب Text Search (New) على النحو التالي:

{
  "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 Details (New) كائن 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"
)

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

لا تُدرِج في الاستجابة إلا الحقول التي تحتاج إليها. إنّ عرض الحقول التي تحتاج إليها فقط:

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