بيانات الطرق في الوقت الفعلي

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

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

تم إيقافها نهائيًا: تم إيقاف الحقول speed_reading_intervals وtravel_duration وretrieval_time نهائيًا واستبدالها بالحقول speed_reading_offsets وduration_in_seconds وstatic_duration_in_seconds وretrieval_timestamp، والتي تتضمّنها الرسائل في الوقت الفعلي اعتبارًا من 8 أكتوبر 2026. اعتبارًا من 9 نوفمبر 2026، قد لا تتم تعبئة الحقول المتوقّفة نهائيًا. قبل ذلك، عليك إبلاغ المشتركين بقراءة الحقول الجديدة، وإضافة الأعمدة الجديدة إلى أي جدول BigQuery تنقل إليه هذه البيانات.

للوصول إلى بيانات الطرق في الوقت الفعلي، يجب أن يتضمّن عقدك حزمة Real-Time Operations.

إنشاء اشتراك في Pub/Sub لفواصل قراءة السرعة ومدة السفر

سيتم تزويدك بمواضيع مخصّصة في Google Cloud Pub/Sub، وهي المواضيع التي يمكنك الاشتراك فيها لتلقّي البيانات في الوقت الفعلي لجميع المسارات التي أنشأتها.

تعرض عينة تعليمات برمجية التالية تنسيق الموضوع باستخدام الترميز الثنائي:

projects/maps-platform-roads-management/topics/rmi-roadsinformation-PROJECT_NUMBER

نوفّر أيضًا موضوعًا آخر باستخدام ترميز JSON (يُضاف إليه اللاحقة -json). ويجب الاشتراك في موضوع Pub/Sub الذي نوفّره لك لتلقّي رسائل البيانات في الوقت الفعلي. راجِع مقالة الاشتراك في موضوع للحصول على نظرة عامة سريعة حول كيفية الاشتراك في موضوع Cloud Pub/Sub واستهلاك الرسائل منه.

مخطط "فترات سرعة القراءة ومدة السفر"

تتضمّن كل رسالة بيانات في الوقت الفعلي بيانات مثل:

• تفاصيل الطرق مثل duration_in_seconds وstatic_duration_in_seconds وspeed_reading_offsets (فواصل قراءة السرعة المستندة إلى الإزاحة) وretrieval_timestamp
• معرّفات المسارات، مثل selected_route_id وdisplay_name

يتم نشر كل رسالة وفقًا لتنسيق Protobuf التالي.

syntax = "proto3";

// Contains the road information like travel duration and speed reading
// intervals for a selected route.
message RoadsInformation {
  // Legacy message. May stop being populated on or after November 9, 2026.
  // Use top-level duration_in_seconds and static_duration_in_seconds instead.
  message TravelDuration {
    // The duration of travel through the route based on current road
    // conditions.
    float duration_in_seconds = 1;
    // The duration of travel through the route without taking road
    // conditions into consideration.
    float static_duration_in_seconds = 2;
  }
  message Timestamp {
    // Represents seconds of UTC time since Unix epoch
    // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
    // 9999-12-31T23:59:59Z inclusive.
    int64 seconds = 1;

    // Non-negative fractions of a second at nanosecond resolution. Negative
    // second values with fractions must still have non-negative nanos values
    // that count forward in time. Must be from 0 to 999,999,999
    // inclusive.
    int32 nanos = 2;
  }
  // Legacy message representing the latitude and longitude of a coordinate
  // within a coordinate-based speed reading interval.
  message LatLng {
    float latitude = 1;
    float longitude = 2;
  }
  // Legacy coordinate-based speed reading interval message. May stop being
  // populated on or after November 9, 2026. Use SpeedReadingOffset instead.
  message SpeedReadingInterval {
    // The coordinates on the polyline for the speed reading interval.
    repeated LatLng interval_coordinates = 1;

    // Describes the categorized current speed of road conditions.
    // Possible values are:
    // - "NORMAL": Road is flowing smoothly, no slowdown is detected.
    // - "SLOW": Slowdown detected, but no congestion formed.
    // - "TRAFFIC_JAM": Traffic jam detected. In this legacy field, heavy
    //   traffic jams (dark red) are also reported as "TRAFFIC_JAM";
    //   "TRAFFIC_JAM_HEAVY" is never used.
    string speed = 2;
  }
  // Offset-based speed reading interval along the route.
  message SpeedReadingOffset {
    // The distance offset from the start of the route in meters for the start
    // of the interval (inclusive).
    int32 start_offset = 1;

    // The distance offset from the start of the route in meters for the end of
    // the interval (exclusive; equals the start_offset of the subsequent
    // interval).
    int32 end_offset = 2;

    // Describes the categorized current speed of traffic, aligned with the
    // colors in the Google Maps traffic layer. Possible values are:
    // - "NORMAL" (green): Traffic is flowing smoothly, no slowdown is detected.
    // - "SLOW" (yellow): Slowdown detected, but no traffic jam formed.
    // - "TRAFFIC_JAM" (red): Traffic jam detected.
    // - "TRAFFIC_JAM_HEAVY" (dark red): Heavy traffic jam detected (available
    //   as of October 8, 2026).
    string speed = 3;
  }
  // Id for selected_route.
  string selected_route_id = 1;
  // User provided name for the route.
  string display_name = 2;
  // Legacy coordinate-based speed reading intervals. May stop being populated
  // on or after November 9, 2026. Use speed_reading_offsets instead.
  repeated SpeedReadingInterval speed_reading_intervals = 3;
  // Legacy travel time information. May stop being populated on or after
  // November 9, 2026. Use duration_in_seconds and static_duration_in_seconds
  // instead.
  TravelDuration travel_duration = 4;
  // Legacy timestamp when the road data was collected. May stop being populated
  // on or after November 9, 2026. Use retrieval_timestamp instead.
  Timestamp retrieval_time = 5;
  // Contains a geojson polyline representing the optimal route determined
  // based on user's input waypoints.
  string route_geometry = 6;
  // Road segment place IDs along the route. They follow topological order
  // and are always connected.
  repeated string road_segment_ids = 7;
  // Offset-based speed reading intervals representing traffic density across
  // the route; each interval is demarcated by the distance offset from the
  // start of the route.
  repeated SpeedReadingOffset speed_reading_offsets = 8;
  // The duration of travel through the route based on current traffic
  // conditions.
  float duration_in_seconds = 9;
  // The duration of travel through the route without taking traffic
  // conditions into consideration.
  float static_duration_in_seconds = 10;
  // The time the traffic data was collected, as an RFC 3339 UTC timestamp
  // string (for example, "2026-10-08T15:04:05+00:00").
  string retrieval_timestamp = 11;
}

فواصل القراءة السريعة المستندة إلى الإزاحة ونقل الحقول

اعتبارًا من 8 أكتوبر 2026، سيتم توفير فواصل القراءة السريعة في الحقل المستند إلى الإزاحة speed_reading_offsets، حيث يتم تحديد كل فاصل زمني من خلال start_offset (شامل) وend_offset (غير شامل) بالأمتار من بداية المسار، ويتضمّن فئة السرعة الرابعة TRAFFIC_JAM_HEAVY. للاطّلاع على تفاصيل حول فئات السرعة وتنسيقات الفواصل الزمنية، يُرجى مراجعة فواصل القراءة السريعة.

يوضّح الجدول التالي عملية ربط كل حقل قديم في Pub/Sub (الذي قد يتوقف عن التعبئة في 9 تشرين الثاني (نوفمبر) 2026 أو بعده) بالحقل البديل:

الحقل القديم	حقل الاستبدال	ملاحظات
speed_reading_intervals	speed_reading_offsets	تستخدم هذه السمة إزاحات العداد (start_offset وend_offset) بدلاً من إحداثيات الخط المتعدد، وتضيف فئة السرعة TRAFFIC_JAM_HEAVY.
travel_duration.duration_in_seconds	duration_in_seconds	تمت تسويته إلى حقل float على المستوى الأعلى.
travel_duration.static_duration_in_seconds	static_duration_in_seconds	تمت تسويته إلى حقل float على المستوى الأعلى.
retrieval_time	retrieval_timestamp	يتم تنسيقه كسلسلة RFC 3339، والتي تحوّلها اشتراكات BigQuery تلقائيًا إلى TIMESTAMP.

نقل بيانات المسار إلى BigQuery باستخدام Pub/Sub

يمكنك ضبط اشتراك Pub/Sub لبث بيانات الطرق مباشرةً إلى جدول BigQuery. ويتيح ذلك تخزين البيانات بشكل فعّال وإجراء تحليلات قوية على معلومات المسار المقدَّمة. قبل إعداد هذا النوع من الاشتراكات، عليك إنشاء مجموعة بيانات وجدول مناسبَين في مشروعك على BigQuery لكتابة البيانات فيهما.

للحصول على تعليمات تفصيلية حول كيفية إنشاء اشتراك في Pub/Sub يكتب إلى BigQuery، راجِع مقالة نقل البيانات المتدفقة إلى BigQuery. أنشئ اشتراك BigQuery في الموضوع بترميز JSON. عند ضبط الاشتراك، اختَر استخدام مخطط الجدول وفعِّل إزالة الحقول غير المعروفة لضمان استمرار تشغيل مسار النقل بسلاسة عند إضافة حقول جديدة. لتخزين حقول جديدة، مثل speed_reading_offsets، أضِف الأعمدة المناسبة إلى جدولك.

مخطط جدول BigQuery

تتّبع الرسائل المنشورة في موضوع Pub/Sub، والتي يمكن أيضًا كتابتها في جدول BigQuery، المخطّط التالي. يجب استخدام هذا المخطط عند إنشاء جدول BigQuery المستهدَف لضمان التوافق.

[
  {
    "mode": "NULLABLE",
    "name": "selected_route_id",
    "type": "STRING",
    "description": "Id for selected_route."
  },
  {
    "mode": "NULLABLE",
    "name": "display_name",
    "type": "STRING",
    "description": "User provided name for the route."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "speed",
        "type": "STRING",
        "description": "Describes the categorized current speed of traffic. Possible values are: \"NORMAL\": Traffic is flowing smoothly, no slowdown is detected. \"SLOW\": Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\": Traffic jam detected (groups red and dark red segments; does not include \"TRAFFIC_JAM_HEAVY\")."
      },
      {
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "latitude",
            "type": "NUMERIC"
          },
          {
            "mode": "NULLABLE",
            "name": "longitude",
            "type": "NUMERIC"
          }
        ],
        "mode": "REPEATED",
        "name": "interval_coordinates",
        "type": "RECORD",
        "description": "The geometry for this interval"
      }
    ],
    "mode": "REPEATED",
    "name": "speed_reading_intervals",
    "type": "RECORD",
    "description": "Legacy coordinate-based speed reading intervals. May stop being populated on or after November 9, 2026. Use speed_reading_offsets instead."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "duration_in_seconds",
        "type": "FLOAT",
        "description": "The duration of travel through the route based on\ncurrent traffic conditions."
      },
      {
        "mode": "NULLABLE",
        "name": "static_duration_in_seconds",
        "type": "FLOAT",
        "description": "The duration of travel through the route without\ntaking traffic conditions into consideration."
      }
    ],
    "mode": "NULLABLE",
    "name": "travel_duration",
    "type": "RECORD",
    "description": "Legacy travel time information. May stop being populated on or after November 9, 2026. Use top-level duration_in_seconds and static_duration_in_seconds instead."
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "seconds",
        "type": "INTEGER",
        "description": "Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive."
      },
      {
        "mode": "NULLABLE",
        "name": "nanos",
        "type": "INTEGER",
        "description": "Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive."
      }
    ],
    "mode": "NULLABLE",
    "name": "retrieval_time",
    "type": "RECORD",
    "description": "Legacy timestamp when the traffic data was collected. May stop being populated on or after November 9, 2026. Use retrieval_timestamp instead."
  },
  {
    "mode": "NULLABLE",
    "name": "route_geometry",
    "type": "STRING",
    "description": "Contains a geojson polyline representing the optimal route determined based on user's input waypoints"
  },
  {
    "mode": "REPEATED",
    "name": "road_segment_ids",
    "type": "STRING",
    "description": "Road segment place IDs along the route. They follow topological order and are always connected"
  },
  {
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "start_offset",
        "type": "INTEGER",
        "description": "The distance offset from the start of the route in meters for the start of the interval (inclusive)."
      },
      {
        "mode": "NULLABLE",
        "name": "end_offset",
        "type": "INTEGER",
        "description": "The distance offset from the start of the route in meters for the end of the interval (exclusive; equals the start_offset of the subsequent interval)."
      },
      {
        "mode": "NULLABLE",
        "name": "speed",
        "type": "STRING",
        "description": "Describes the categorized current speed of traffic, aligned with the colors in the Google Maps traffic layer. Possible values are: \"NORMAL\" (green): Traffic is flowing smoothly, no slowdown is detected. \"SLOW\" (yellow): Slowdown detected, but no traffic jam formed. \"TRAFFIC_JAM\" (red): Traffic jam detected. \"TRAFFIC_JAM_HEAVY\" (dark red): Heavy traffic jam detected (available as of October 8, 2026)."
      }
    ],
    "mode": "REPEATED",
    "name": "speed_reading_offsets",
    "type": "RECORD",
    "description": "Offset-based speed reading intervals representing traffic density across the route; each interval is demarcated by the distance offset from the start of the route."
  },
  {
    "mode": "NULLABLE",
    "name": "duration_in_seconds",
    "type": "FLOAT",
    "description": "The duration of travel through the route based on current traffic conditions."
  },
  {
    "mode": "NULLABLE",
    "name": "static_duration_in_seconds",
    "type": "FLOAT",
    "description": "The duration of travel through the route without taking traffic conditions into consideration."
  },
  {
    "mode": "NULLABLE",
    "name": "retrieval_timestamp",
    "type": "TIMESTAMP",
    "description": "The time the traffic data was collected."
  }
]