اختيار المعلومات التي تريد عرضها

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

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

يعد استخدام قناع الحقل ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، مما يساعد بدوره على تجنب وقت المعالجة غير الضروري والرسوم الواردة في الفاتورة.

لمزيد من المعلومات حول مَعلمات عناوين URL، يُرجى الاطّلاع على مَعلمات النظام.

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

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

يمكنك إنشاء مسار حقل وتحديده على النحو التالي:

1. ابحث عن الحقول التي تحتوي على المعلومات التي تحتاجها من Routes API. لمعرفة التفاصيل، يُرجى الاطّلاع على مراجع الحقول.
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 المرتبطة في القائمة التالية. حدِّد الحقول في حالة الجمل كما هو موضّح في المرجع. مثلاً: routePreference

وفي المقابل، يجب إدخال قيم المعلمات كما هو موضّح. على سبيل المثال، بالنسبة إلى routingPreference، يجب إدخال TRAFFIC_AWARE.

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

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

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

قم بتضمين الحقول التي تحتاجها فقط في الرد لعرض الحقول التي تحتاجها فقط:

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

ملاحظة: عند تحليل رسالة الرد وتضمين أحد الحقول التلقائية لرسالة الردّ، قد يتم حذف الحقل من الردّ حتى إذا حدَّدته في قناع حقل الردّ. لمزيد من المعلومات، يمكنك الاطّلاع على دليل اللغة (proto3). على سبيل المثال، عند احتساب مصفوفة مسار، يمكن أن يشتمل الحقل distanceMeters في الاستجابة على القيمة 0، وهي قيمتها التلقائية. ولأن 0 هي القيمة التلقائية لـ distanceMeters، يتم حذفها من الاستجابة.

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

طلب رمز مميز للمسار

لطلب إرجاع Routes API الرموز المميّزة للمسارات التي تمّ إنشاؤها، اتّبِع الخطوات التالية:

1. اضبط المَعلمات التالية المطلوبة لعرض رمز مميّز للمسار:
   • اضبط السمة travelMode على DRIVE.
   • اضبط السمة routingPreference على TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.
2. تأكَّد من أنّ جميع نقاط الطريق ليست ضمن via نقطة.
3. حدِّد قناع الحقل routes.routeToken لعرض الرمز المميّز للمسار:

   X-Goog-FieldMask: routes.routeToken

ملاحظة: بسبب ظروف الطريق الديناميكية، قد تختلف المسارات التي تم إنشاؤها باستخدام رمز مميّز معيّن عن المسار المخطط له. لتقليل الاختلافات، استخدِم الرمز المميّز خلال دقائق من إنشاء الرموز المميّزة.

ويمكنك استخدام الرمز المميّز للمسار لمسارك المُخطَّط له في حزمة تطوير البرامج للتنقل. لمزيد من التفاصيل، يُرجى الاطّلاع على التخطيط لمسار (Android) أو التخطيط لمسار (نظام التشغيل iOS).

مثال على الرمز المميّز للمسار

في ما يلي مثال على نص طلب cURL لأصل واحد، ومسار وجهة واحدة، باستخدام أقنعة الحقول لطلب رمز مميز للمسار، بالإضافة إلى مدة المسار والمسافة والخطوط المتعددة للمسار:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

لمزيد من التفاصيل، يُرجى الاطّلاع على مرجع Compute Routes API.