المطوّرون في المنطقة الاقتصادية الأوروبية (EEA)

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

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

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

يمكنك تحديد قائمة الحقول التي تحتاج إليها في قناع حقل الردّ. بعد ذلك، يمكنك تمرير قناع حقل الردّ إلى أي من الطريقتَين باستخدام مَعلمة عنوان 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 API أو Compute Route Matrix المرتبطة في القائمة التالية. حدِّد الحقول بتنسيق camel case كما هو موضّح في المرجع. على سبيل المثال، routePreference.

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

  • قناع حقل "حساب المسار"
    • REST: يحدّد حقول كائن المسار في الردّ المطلوب عرضه، مع إضافة البادئة routes.، على سبيل المثال، routes.distanceMeters.
    • gRPC: يحدّد حقول كائن المسار في الردّ المطلوب عرضه.
  • أقنعة حقول "حساب مصفوفة المسارات"
    • 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 إلى computeRoutes

بالنسبة إلى طريقة gRPC‏ computeRoutes المُستخدَمة لحساب مسار، اضبط مُتغيِّرًا يحتوي على قناع حقل الردّ لعرض حقول distanceMeters وduration وشكل متعدّد الخطوط المشفّر للمسار في الردّ. يمكنك بعد ذلك تمرير هذا المتغيّر إلى الطلب:

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

طلب gRPC إلى computeRouteMatrix

بالنسبة إلى طريقة gRPC‏ computeRouteMatrix المُستخدَمة لحساب مصفوفة مسارات، اضبط متغيّرًا يحتوي على قناع حقل الردّ لتحديد عرض originIndex وdestinationIndex وduration لكل مجموعة من نقطة الانطلاق والوجهة. يمكنك بعد ذلك تمرير هذا المتغيّر إلى الطلب:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

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

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

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

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