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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الردّ. بعد ذلك تجتاز قناع حقل الاستجابة لأي من الطريقتين باستخدام المعلمة $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

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

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

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

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

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

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