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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الاستجابة. ثم تمرِّر قناع حقل الاستجابة إلى أي من الطريقتَين باستخدام المَعلمة $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": "[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

تحديد قناع حقل الردّ لتفاصيل المكان (جديد)

تعرض تفاصيل المكان كائن مكان واحدًا في النموذج:

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

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

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