مطوّرو المنطقة الاقتصادية الأوروبية (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
لمعرفة الأمثلة والمزيد من التفاصيل، يُرجى الاطّلاع على الأقسام التالية.

مراجع الحقول

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

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

  • قناع حقول المسار المحسوب
    • REST: يحدّد حقول كائن المسار في الاستجابة المطلوب عرضها، مع إضافة البادئة routes.، على سبيل المثال، routes.distanceMeters.
    • gRPC: يحدّد حقول كائن المسار في الاستجابة المطلوب عرضها.
  • أقنعة حقول مصفوفة المسارات المحسوبة

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

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

  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 وخطوط polyline المرمّزة للمسار في الاستجابة. يمكنك بعد ذلك تمرير هذا المتغيّر إلى الطلب:

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

طلب gRPC إلى computeRouteMatrix

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

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

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

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

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

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