REST Resource: providers.trips

المرجع: رحلة

البيانات الوصفية للرحلة

تمثيل JSON 
{
  "name": string,
  "vehicleId": string,
  "tripStatus": enum (TripStatus),
  "tripType": enum (TripType),
  "pickupPoint": {
    object (TerminalLocation)
  },
  "actualPickupPoint": {
    object (StopLocation)
  },
  "actualPickupArrivalPoint": {
    object (StopLocation)
  },
  "pickupTime": string,
  "intermediateDestinations": [
    {
      object (TerminalLocation)
    }
  ],
  "intermediateDestinationsVersion": string,
  "intermediateDestinationIndex": integer,
  "actualIntermediateDestinationArrivalPoints": [
    {
      object (StopLocation)
    }
  ],
  "actualIntermediateDestinations": [
    {
      object (StopLocation)
    }
  ],
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "actualDropoffPoint": {
    object (StopLocation)
  },
  "dropoffTime": string,
  "remainingWaypoints": [
    {
      object (TripWaypoint)
    }
  ],
  "vehicleWaypoints": [
    {
      object (TripWaypoint)
    }
  ],
  "route": [
    {
      object (LatLng)
    }
  ],
  "currentRouteSegment": string,
  "currentRouteSegmentVersion": string,
  "currentRouteSegmentTraffic": {
    object (ConsumableTrafficPolyline)
  },
  "currentRouteSegmentTrafficVersion": string,
  "currentRouteSegmentEndPoint": {
    object (TripWaypoint)
  },
  "remainingDistanceMeters": integer,
  "etaToFirstWaypoint": string,
  "remainingTimeToFirstWaypoint": string,
  "remainingWaypointsVersion": string,
  "remainingWaypointsRouteVersion": string,
  "numberOfPassengers": integer,
  "lastLocation": {
    object (VehicleLocation)
  },
  "lastLocationSnappable": boolean,
  "view": enum (TripView)
}
الحقول
name

string

النتائج فقط. بالتنسيق "providers/{provider}/trips/{trip}"
vehicleId

string

رقم تعريف المركبة التي تجري هذه الرحلة
tripStatus

enum (TripStatus)

الحالة الحالية للرحلة
tripType

enum (TripType)

نوع الرحلة
pickupPoint

object (TerminalLocation)

تشير إلى الموقع الجغرافي الذي يشير فيه العميل إلى أنّه سيتم استلام الطلب.
actualPickupPoint

object (StopLocation)

الإدخال فقط. الموقع الجغرافي الفعلي وقت ومكان استلام العميل. هذا الحقل مخصّص لمقدّم الخدمة لتقديم ملاحظات حول معلومات الاستلام الفعلية.
actualPickupArrivalPoint

object (StopLocation)

الإدخال فقط. الوقت الفعلي والموقع الجغرافي لوصول السائق إلى نقطة الاستلام هذا الحقل مخصّص لمقدّم الخدمة ليقدّم ملاحظات حول معلومات الوصول الفعلية إلى نقطة الاستلام.
pickupTime

string (Timestamp format)

النتائج فقط. سواء الوقت المقدر في المستقبل الذي سيتم فيه نقل الركاب أو الوقت الفعلي الذي تم التقاطهم فيه.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
intermediateDestinations[]

object (TerminalLocation)

محطّات متوسطة للتوقّف من أجل طلب الرحلات (بالإضافة إلى الاستلام والتوصيل) في البداية، لن تكون هذه الميزة متوفّرة للرحلات المشتركة.
intermediateDestinationsVersion

string (Timestamp format)

يشير هذا الحقل إلى آخر مرة تم فيها تعديل intermediateDestinations. يجب أن يخزّن الخادم هذه القيمة مؤقتًا ويمررها في UpdateTripRequest عند تحديث intermediateDestinationIndex لضمان عدم تغيير قيمة intermediateDestinations.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
intermediateDestinationIndex

integer

عندما يكون TripStatus هو ENROUTE_TO_INTERMEDIATE_DESTINATION، يكون رقمًا بين [0..N-1] يشير إلى الوجهة الوسيطة التي ستعبرها المركبة بعد ذلك. عندما تكون قيمة TripStatus هي ARRIVED_AT_INTERMEDIATE_DESTINATION، يكون رقمًا بين [0..N-1] يشير إلى الوجهة الوسيطة التي وصلت إليها المركبة. يضبط الموفِّر هذه القيمة. في حال عدم توفّر intermediateDestinations، يتم تجاهل هذا الحقل.
actualIntermediateDestinationArrivalPoints[]

object (StopLocation)

الإدخال فقط الوقت والموقع الجغرافي الفعليان لوصول السائق إلى وجهة وسيطة هذا الحقل مخصّص لمقدّم الخدمة لتقديم ملاحظات حول معلومات الوصول الفعلية إلى الوجهات الوسيطة.
actualIntermediateDestinations[]

object (StopLocation)

الإدخال فقط. الوقت والموقع الجغرافي الفعليان اللذان تم استلام العميل فيهما من وجهة وسيطة هذا الحقل مخصّص لموفّر الخدمة لتقديم ملاحظات حول معلومات الاستلام الفعلية في الوجهات المتوسطة.
dropoffPoint

object (TerminalLocation)

الموقع الجغرافي الذي يشير فيه العميل إلى أنّه سيتم تسليمه
actualDropoffPoint

object (StopLocation)

الإدخال فقط الوقت والموقع الجغرافي الفعليان اللذان تمّت فيها إعادة العميل إلى مكان إقامته. هذا الحقل مخصّص لمقدّم الخدمة لتقديم ملاحظات حول معلومات إعادة العميل الفعلية.
dropoffTime

string (Timestamp format)

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

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
remainingWaypoints[]

object (TripWaypoint)

النتائج فقط. المسار الكامل من الموقع الجغرافي الحالي إلى نقطة الاستلام، شاملاً يمكن أن يتضمن هذا المسار نقاط الطريق من الرحلات الأخرى.
vehicleWaypoints[]

object (TripWaypoint)

يتيح هذا الحقل ترتيب نقاط التوقف يدويًا للرحلة. يحتوي هذا الملف على جميع نقاط التوقف المتبقية للمركبة المحدّدة، بالإضافة إلى نقاط التوقف لتحميل الركاب وإيقافهم في هذه الرحلة. إذا لم يتمّ إسناد الرحلة إلى مركبة، سيتجاهل محرّك الأسطول هذا الحقل. لأسباب تتعلّق بالخصوصية، لا يملؤه الخادم إلا في المكالمات التي تتضمن trips.update وtrips.create، وليس في المكالمات التي تتضمن trips.get.
route[]

object (LatLng)

النتائج فقط. المسار المتوقّع لهذه الرحلة إلى أول إدخال في remainingWaypoints يُرجى العِلم أنّ نقطة الطريق الأولى قد تنتمي إلى رحلة مختلفة.
currentRouteSegment

string

النتائج فقط. مسار مشفَّر إلى نقطة الطريق التالية

ملاحظة: هذا الحقل مخصّص فقط لاستخدام حِزم Driver SDK وConsumer SDK. لا تتوفّر إمكانية فك الترميز بعد.
currentRouteSegmentVersion

string (Timestamp format)

النتائج فقط. يشير إلى آخر مرة تم فيها تعديل المسار.

ملاحظة: هذا الحقل مخصّص فقط لاستخدام حِزم Driver SDK وConsumer SDK.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
currentRouteSegmentTraffic

object (ConsumableTrafficPolyline)

النتائج فقط. تشير إلى حالة حركة المرور على طول currentRouteSegment عند توفّرها.

ملاحظة: هذا الحقل مخصّص فقط للاستخدام من خلال حزمة تطوير البرامج (SDK) لبرنامج التشغيل وحزمة تطوير البرامج (SDK) الخاصة بالمستهلك.
currentRouteSegmentTrafficVersion

string (Timestamp format)

النتائج فقط. يشير هذا الحقل إلى آخر مرة تم فيها تعديل currentRouteSegmentTraffic.

ملاحظة: هذا الحقل مخصّص فقط لاستخدام حِزم Driver SDK وConsumer SDK.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
currentRouteSegmentEndPoint

object (TripWaypoint)

النتائج فقط. نقطة الطريق التي تنتهي عندها currentRouteSegment
remainingDistanceMeters

integer

النتائج فقط. المسافة المتبقية للقيادة في الحقل currentRouteSegment لا يتم تحديد القيمة إذا لم تكن الرحلة مخصّصة لمركبة أو إذا اكتملت الرحلة أو تم إلغاؤها.
etaToFirstWaypoint

string (Timestamp format)

النتائج فقط. الوقت المقدر للوصول إلى نقطة الطريق التالية (الإدخال الأول في الحقل remainingWaypoints). لا يتم تحديد القيمة إذا لم تكن الرحلة مخصّصة لمركبة أو إذا كانت الرحلة غير نشطة (مكتملة أو ملغاة).

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
remainingTimeToFirstWaypoint

string (Duration format)

النتائج فقط. المدة التي تم فيها عرض بيانات الرحلة إلى الوقت المحدد في Trip.eta_to_first_waypoint تكون القيمة غير محدّدة إذا لم يتم إسناد الرحلة إلى مركبة أو إذا كانت الرحلة غير نشطة (مكتمَلة أو مُلغاة).

مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بـ "s" مثال: "3.5s"
remainingWaypointsVersion

string (Timestamp format)

النتائج فقط. تشير إلى آخر مرة تم فيها تغيير remainingWaypoints (تمت إضافة نقطة وسيطة أو إزالتها أو تغييرها).

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
remainingWaypointsRouteVersion

string (Timestamp format)

النتائج فقط. يشير إلى آخر مرة تم فيها تعديل remainingWaypoints.path_to_waypoint وremainingWaypoints.traffic_to_waypoint. يجب أن يخزِّن تطبيق العميل هذه القيمة ويمرّرها في GetTripRequest لضمان عدم عرض المسارات والزيارات إلى remainingWaypoints إلا في حال تعديلها.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
numberOfPassengers

integer

غير قابل للتغيير يشير إلى عدد الركاب في هذه الرحلة ولا يشمل السائق. يجب أن تتوفّر في المركبة السعة المتاحة ليتم إرجاعها في حالة استجابة vehicles.search.
lastLocation

object (VehicleLocation)

النتائج فقط. تشير إلى آخر موقع جغرافي تم الإبلاغ عنه للمركبة على طول المسار.
lastLocationSnappable

boolean

النتائج فقط. يشير هذا الحقل إلى ما إذا كان يمكن محاذاة lastLocation الخاصة بالمركبة إلى قطاع المسار الحالي. خطأ في حال عدم توفّر lastLocation أو currentRouteSegment. ويتم احتسابها من خلال Fleet Engine. سيتم تجاهل أي تعديل من العملاء.
view

enum (TripView)

المجموعة الفرعية لحقول الرحلة التي يتمّ تعبئتها وكيفية تفسيرها

TripStatus

حالة رحلة تشير إلى مستوى تقدّمها

عمليات التعداد
UNKNOWN_TRIP_STATUS تلقائي، يُستخدم لحالة الرحلة غير المحدّدة أو غير المعروفة.
NEW رحلة تم إنشاؤها حديثًا
ENROUTE_TO_PICKUP السائق في طريقه إلى نقطة الاستلام.
ARRIVED_AT_PICKUP لقد وصل السائق إلى نقطة الاستلام.
ARRIVED_AT_INTERMEDIATE_DESTINATION وصل السائق إلى وجهة متوسطة وينتظر الراكب.
ENROUTE_TO_INTERMEDIATE_DESTINATION السائق في طريقه إلى وجهة وسيطة (وليست نقطة الانطلاق).
ENROUTE_TO_DROPOFF استقلّ الراكب السيارة وهو في طريقه إلى الوجهة التالية.
COMPLETE تم إنزال الراكب وانتهت الرحلة.
CANCELED تم إلغاء الرحلة قبل استلامها من قِبل السائق أو الراكب أو مقدّم خدمة ركوب السيارات.

StopLocation

الموقع الجغرافي الفعلي الذي حدثت فيه محطة (المجموعة/الإيصال)

تمثيل JSON 
{
  "point": {
    object (LatLng)
  },
  "timestamp": string,
  "stopTime": string
}
الحقول
point

object (LatLng)

مطلوب. يشير إلى الموقع الجغرافي الفعلي.
timestamp

string (Timestamp format)

يشير إلى وقت حدوث التوقّف.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
stopTime
(deprecated)

string (Timestamp format)

الإدخال فقط تمّ الإيقاف. استخدِم حقل الطابع الزمني.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

TripView

أداة اختيار لمجموعات مختلفة من حقول الرحلة في استجابة trips.get راجع AIP-157 لمعرفة السياق. من المرجح أن تتم إضافة مشاهدات إضافية.

عمليات التعداد
TRIP_VIEW_UNSPECIFIED القيمة التلقائية بالنسبة إلى التوافق مع الأنظمة القديمة، سيتم ضبط واجهة برمجة التطبيقات تلقائيًا على طريقة عرض حزمة تطوير البرامج (SDK). لضمان الاستقرار والدعم، ننصح العملاء باختيار TripView بخلاف SDK.
SDK تتضمّن الحقول التي قد لا تكون قابلة للتفسير أو الدعم باستخدام المكتبات المتاحة للجميع.
JOURNEY_SHARING_V1S يتم تعبئة حقول الرحلة لحالة الاستخدام "مشاركة الرحلة". تم تصميم طريقة العرض هذه لاتصالات خادم إلى خادم.

الطُرق

create

 لإنشاء رحلة في Fleet Engine وإرجاع الرحلة الجديدة

get

 الحصول على معلومات عن رحلة واحدة
الحصول على جميع الرحلات لمركبة معيّنة

update

 تعديل بيانات الرحلة