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),
  "attributes": [
    {
      object (TripAttribute)
    }
  ]
}
الحقول
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)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
intermediateDestinations[]

object (TerminalLocation)

محطات التوقف المؤقتة التي يطلبها المسار (بالإضافة إلى محطات التحميل والتفريغ) لن تكون هذه الميزة متاحة في البداية للرحلات المشترَكة.
intermediateDestinationsVersion

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
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)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
remainingWaypoints[]

object (TripWaypoint)

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

object (TripWaypoint)

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

object (LatLng)

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

string

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

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

string (Timestamp format)

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

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
currentRouteSegmentTraffic

object (ConsumableTrafficPolyline)

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

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

string (Timestamp format)

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

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
currentRouteSegmentEndPoint

object (TripWaypoint)

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

integer

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

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
remainingTimeToFirstWaypoint

string (Duration format)

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

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

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
remainingWaypointsRouteVersion

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
numberOfPassengers

integer

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

object (VehicleLocation)

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

boolean

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

enum (TripView)

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

object (TripAttribute)

قائمة بسمات الرحلة المخصّصة يجب أن يكون لكل سمة مفتاح فريد.

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)

يشير إلى وقت التوقف.

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
stopTime
(deprecated)

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر التي لا تُعدّ "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"

TripView

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

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

TripAttribute

يصف سمة رحلة كزوج مفتاح/قيمة. لا يمكن أن يتجاوز طول سلسلة "المفتاح:القيمة" 256 حرفًا.

تمثيل JSON 
{
  "key": string,

  // Union field trip_attribute_value can be only one of the following:
  "stringValue": string,
  "boolValue": boolean,
  "numberValue": number
  // End of list of possible types for union field trip_attribute_value.
}
الحقول
key

string

مفتاح السمة لا يجوز أن تحتوي المفاتيح على رمز النقطتَين (:).
حقل الربط trip_attribute_value يمكن أن تكون قيمة السمة من النوع string أو bool أو double. يمكن أن يكون trip_attribute_value واحدًا فقط مما يلي:
stringValue

string

قيمة السمة من النوع سلسلة
boolValue

boolean

قيمة سمة من النوع المنطقي
numberValue

number

قيمة سمة ذات نوعَين

الطُرق

create

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

delete

 لحذف رحلة واحدة

get

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

update

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