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

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

يضمن استخدام قناع الحقل أيضًا عدم طلب بيانات غير ضرورية، ما يساعد بدوره في تقليل وقت استجابة الطلب وتجنُّب عرض معلومات لا يحتاج إليها نظامك.

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

لمزيد من المعلومات عن مَعلمات عناوين URL، راجِع مقالة مَعلمات النظام.

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

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

أنشئ مسار حقل وحدِّده على النحو التالي:

1. ابحث عن الحقول التي تحتوي على المعلومات التي تحتاج إليها. لمعرفة التفاصيل، يُرجى الاطّلاع على مراجع الحقول.
2. تحديد مسارات الحقول التي تحتاج إليها وإنشاء أقنعة الحقول لها: لمزيد من التفاصيل، اطّلِع على تحديد قناع الحقل الذي تريد استخدامه.

3. اجمع بين أقنعة الحقول لجميع الحقول التي تحتاج إليها، مع الفصل بين أقنعة الحقول بفواصل. على سبيل المثال، لطلب distanceMeters لجزء المسار، بالإضافة إلى مدة كل خطوة من خطوات جزء المسار، أدخِل كليهما مفصولَين بفاصلة، بدون مسافات:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. إرسال قناع الحقل مع طلب البيانات من واجهة برمجة التطبيقات على سبيل المثال، في طلب curl، يمكنك تحديد قناع الحقل باستخدام -H وX-Goog-FieldMask:

   -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration

مراجع الحقول

للاطّلاع على الحقول التي يمكنك طلبها في ردّ من خلال أقنعة الحقول، يُرجى الرجوع إلى مراجع Compute Routes أو Compute Route Matrix في Routes API المرتبطة في القائمة التالية. حدِّد الحقول في حالة الأحرف المتسلسلة كما هو موضّح في المرجع. مثلاً: routePreference

تتضمّن هذه المراجع الحقول المتاحة، ولكن عليك الرجوع إلى التسلسل الهرمي للحقول لتحديد مسار قناع الحقل الكامل. للحصول على تفاصيل حول كيفية الحصول على التدرّج الهرمي للحقول، اطّلِع على تحديد قناع الحقل الذي تريد استخدامه.

• قناع حقل مسار Compute
  • REST: تحدّد هذه السمة حقول كائن المسار التي سيتم عرضها في الرد، مع إضافة البادئة routes.، مثلاً، routes.distanceMeters.
  • ‫gRPC: تحدّد هذه السمة حقول كائن Route في الاستجابة التي سيتم عرضها.
• أقنعة حقول مصفوفة Compute Route
  • REST: تحدّد هذه السمة حقول نص الاستجابة التي سيتم عرضها.
  • ‫gRPC: تحدّد هذه السمة الحقول الخاصة بكائن RouteMatrixElement في الردّ الذي سيتم عرضه.

تحديد حقول الأقنعة التي يجب استخدامها

في ما يلي كيفية تحديد الحقول التي تريد استخدامها وإنشاء أقنعة الحقول لها:

1. اطلب جميع الحقول باستخدام قناع الحقل *.
2. اطّلِع على التسلسل الهرمي للحقول في الردّ للحصول على الحقول التي تريدها.

3. أنشئ أقنعة الحقول باستخدام التسلسل الهرمي للحقول المعروضة في الخطوة السابقة، وذلك باستخدام هذا التنسيق:

   topLevelField[.secondLevelField][.thirdLevelField][...]

على سبيل المثال، بالنسبة إلى هذا الردّ الجزئي من مسار:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

إذا كنت تريد عرض الحقل distanceMeters فقط لجزء الرحلة، أي آخر distanceMeters في العيّنة السابقة، سيكون قناع الحقل على النحو التالي:

routes.legs.distanceMeters

إذا كنت تريد بدلاً من ذلك عرض الحقل distanceMeters لكل خطوة من خطوات جزء المسار، أي distanceMeters ضمن steps في النموذج السابق، سيكون قناع الحقل على النحو التالي:

routes.legs.steps.distanceMeters

إذا أردت عرض كليهما، مع النتيجة أعلاه، سيكون قناع الحقل على النحو التالي:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

أمثلة على مسارات قناع الحقل

يحتوي هذا القسم على المزيد من الأمثلة حول كيفية تحديد مسار حقل كجزء من قناع حقل الرد في طلبات REST وgRPC.

طلب REST إلى computeRoutes

في المثال الأول، يمكنك استخدام طلب REST إلى الطريقة computeRoutes لحساب مسار. في هذا المثال، يمكنك تحديد أقنعة الحقول في العنوان لعرض الحقلَين distanceMeters وduration الخاصَين بالمسار في الردّ. تذكَّر إضافة البادئة routes إلى اسم الحقل.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

طلب REST إلى computeRouteMatrix

بالنسبة إلى طريقة REST computeRouteMatrix المستخدَمة لاحتساب مصفوفة المسارات، حدِّد في العنوان عرض originIndex وdestinationIndex وduration لكل تركيبة من نقطة الانطلاق والوجهة:

X-Goog-FieldMask: originIndex,destinationIndex,duration

مكالمة gRPC

بالنسبة إلى gRPC، اضبط متغيّرًا يحتوي على قناع حقل الاستجابة. يمكنك بعد ذلك تمرير هذا المتغيّر إلى الطلب.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

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

أدرِج فقط الحقول التي تحتاج إليها في الردّ لعرض الحقول التي تحتاج إليها فقط:

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

لمزيد من التفاصيل حول إنشاء قناع الحقل، يُرجى الاطّلاع على field_mask.proto.