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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الردّ. يمكنك بعد ذلك تمرير قناع حقل الاستجابة إلى أيّ من الطريقتين باستخدام المَعلمة $fields أو fields أو عنوان X-Goog-FieldMask هو HTTP أو gRPC.

يُعد إخفاء الحقل ممارسة جيدة في التصميم لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة ورسوم الفوترة غير الضرورية.

تحديد قناع حقل الردّ

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

ويمكنك إنشاء مسار حقل على النحو التالي:

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

تحديد قناع حقل الاستجابة لتفاصيل المكان (جديد)

تعرض "Place Details" عنصر "مكان" واحدًا بالشكل:

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