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

لبدء جلسة اتجاهات مفصّلة بشكل آمن للسائق، يجب أن تنشئ الخلفية رحلة وتحصل على رمز مميّز للرحلة تمت مصادقته من 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:

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

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

يحتاج السائقون إلى الإصدار 5.20.0.2 من تطبيق Waze أو إصدار أحدث على أجهزة Android، أو الإصدار 5.20.0.1 أو إصدار أحدث على أجهزة iOS، أو الإصدار 26.27 من تطبيق "خرائط Google" لأجهزة Android أو إصدار أحدث.

الإبلاغ عن الانحراف عن المسار (Waze فقط) boolean

لتتبُّع خروج السائق عن المسار، اضبط config.enableRouteDeviationReporting على true.

يجب أن يستخدم السائقون الإصدار 5.22 من Waze أو إصدارًا أحدث.

معدل التحديثات للرحلة 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