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

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