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

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

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

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

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

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

  • قناع حقل حساب المسار
    • ‫REST: تحدّد هذه السمة حقول عنصر Route في الردّ الذي سيتم عرضه، وتكون مسبوقة بـ routes.، على سبيل المثال، routes.distanceMeters.
    • ‫gRPC: تحدّد حقول عنصر Route في الردّ المطلوب عرضه.
  • أقنعة حقول Compute Route Matrix

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

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

  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.