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

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

تعدّل ميزة "التنقل السلس" بيانات الرحلة تلقائيًا كل 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