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

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

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

• مَعلمات 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'

يتوفّر عنصر الاستجابة الكامل من طلب 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": "[phone]",
      "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"
)

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

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

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

ملاحظة: عند تحليل رسالة ردّ، إذا كان أحد الحقول في رسالة الردّ يحتوي على قيمته التلقائية، قد يتم حذف الحقل من الردّ حتى إذا سبق لك تحديده في قناع حقل الردّ. لمزيد من المعلومات، يُرجى الاطّلاع على دليل اللغات (proto3).