إنشاء رحلة والحصول على رمز مميّز للرحلة

لبدء جلسة اتجاهات مفصّلة بشكل آمن للسائق، يجب أن ينشئ نظام الخلفية رحلة ويحصل على رمز مميز مصادَق عليه للرحلة من Navigation Connect API.

في Navigation Connect، تمثّل الرحلة جلسة تنقّل إلى وجهة واحدة. لإنشاء رحلة والحصول على الرمز المميّز للرحلة الذي تمّت مصادقته (authToken) والمطلوب لتفويض الجلسة، أرسِل رسالة CreateTripRequest إلى طريقة CreateTrip. مرِّر رمز الرحلة المميز إلى تطبيقك على الأجهزة الجوّالة لتضمينه في عنوان URL الخاص بتشغيل "خرائط Google" أو Waze.

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

إنشاء رسالة CreateTripRequest

لإنشاء رحلة والحصول على رمز مميّز للرحلة، اتّبِع الخطوات التالية لإنشاء رسالة CreateTripRequest وإرسالها:

  1. المصادقة: استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC) للحصول على رمز مميّز للوصول من أجل تفويض طلبك. لمزيد من التفاصيل، يُرجى الاطّلاع على إنشاء رمز مميّز لبروتوكول OAuth.
  2. إنشاء معرّف رحلة: أنشئ معرّف رحلة فريدًا (tripId) بتنسيق UUIDv4 لتحديد الرحلة على خادمك.
  3. إنشاء الحمولة: أنشئ حمولة JSON تتضمّن معرّفات تطبيقاتك وإعدادات الضبط.
  4. استدعاء طريقة CreateTrip: أرسِل طلب POST إلى واجهة برمجة التطبيقات مع تضمين رمز الدخول في العنوان والحِمل في النص.

يوضّح المثال التالي كيفية إنشاء رحلة من خلال إرسال رسالة CreateTripRequest:

#!/bin/bash

# Authenticate with ADC
access_token="$(gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL)"

# Generate a unique Trip ID
trip_id="$(uuidgen)"

# Construct the payload
payload=$(cat <<EOF
{
  "androidAppId": "ANDROID_APP_ID",
  "iosAppId": "IOS_APP_ID",
  "config": {
    "enablePubsub": true
  }
}
EOF
)

# Call the CreateTrip method to request a trip token
curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
-H "Authorization: Bearer ${access_token}" \
-H "Content-Type: application/json" \
-d "${payload}"

الإعدادات الاختيارية

يمكنك تخصيص بيانات الرحلة من خلال تعديل الإعدادات التالية في الرسالة CreateTripRequest:

الميزة النوع الوصف
الإبلاغ عن المسار المتبقي (في Waze فقط) boolean

لتلقّي خطوط متعددة الأضلاع للمسار النشط وحالات حركة المرور في الوقت الفعلي، اضبط config.enableRemainingRouteReporting على true.
الإبلاغ عن الانحراف عن المسار (في Waze فقط) boolean

لتتبُّع الوقت الذي يخرج فيه السائق عن المسار، اضبط config.enableRouteDeviationReporting على true.
معدّل تكرار تعديل الرحلة boolean

تعدّل ميزة Navigation Connect تلقائيًا بيانات الرحلة كل 60 ثانية. لتفعيل التحديثات المتكرّرة (كل 5 ثوانٍ)، اضبط config.enableHighFrequencyUpdates على true.
إنشاء أحداث Google Cloud Pub/Sub boolean

لتفعيل إنشاء أحداث الرحلات باستخدام Google Cloud Pub/Sub، اضبط قيمة config.enablePubsub على true. تكون هذه الميزة غير مفعّلة تلقائيًا.
قناع حقل Google Cloud Pub/Sub FieldMask

لإدارة أحجام الحمولة وتقليل عبء المعالجة في الخلفية أو تكاليف استخدام Google Cloud Pub/Sub، استخدِم config.pubsubFieldMask لاستبعاد الحقول الكبيرة (مثل execution.remainingRoute) من بث الأحداث. لمزيد من المعلومات حول حجم الحمولة لبيانات المسار المتبقية، يُرجى الاطّلاع على مقالة التعامل مع بيانات المسار المتبقية.

الحصول على رمز الرحلة من الردّ

تعرض الطريقة CreateTrip ردًا يحتوي على الرمز المميز للرحلة التي تمت المصادقة عليها. للسماح بجلسة التنقّل، استخرِج الرمز المميّز من الردّ وأرسِله إلى تطبيقك على الأجهزة الجوّالة لتضمينه في عنوان URL الخاص بالإطلاق.

تعرض عيّنة الرمز البرمجي التالية مثالاً على الردّ:

{
    "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z"
}

يتضمّن هذا الرد القيم التالية:

  • ‫PROJECT_NUMBER: معرّف رقمي فريد لمشروعك. يختلف هذا الرقم عن رقم تعريف المشروع الأبجدي الرقمي، لكنّه يمثّل مشروع Google Cloud نفسه.
  • TRIP_ID: رقم تعريف الرحلة الذي تم إنشاؤه بواسطة الخلفية بتنسيق UUIDv4.
  • ‫BASE64_ENCODED_TRIP_TOKEN: الرمز المميّز للرحلة الذي تمت المصادقة عليه (authToken.token) والذي تعرضه الطريقة CreateTrip. مرِّر الرمز المميّز إلى تطبيقك على الأجهزة الجوّالة لبدء اتجاهات مفصّلة يتم تتبّعها في "خرائط Google" أو Waze.

الخطوات التالية

استخدِم رمز الرحلة لتشغيل "خرائط Google" أو Waze.

تشغيل "خرائط Google" أو Waze