لبدء جلسة اتجاهات مفصّلة بشكل آمن للسائق، يجب أن تنشئ الخلفية رحلة وتحصل على رمز مميّز للرحلة تمت مصادقته من Navigation Connect API.
في Navigation Connect، تمثّل الرحلة جلسة تنقّل إلى وجهة واحدة. لإنشاء رحلة والحصول على الرمز المميّز المُصادَق عليه للرحلة
(authToken) المطلوب لمنح الإذن للجلسة، أرسِل رسالة CreateTripRequest
إلى طريقة CreateTrip. يُرجى تمرير الرمز المميّز للرحلة إلى تطبيقك على الأجهزة الجوّالة لتضمينه في عنوان URL الخاص بتشغيل "خرائط Google" أو Waze.
يوضّح هذا الدليل كيفية إكمال هذه العملية من خلال إنشاء معرّف رحلة فريد وإرسال طلب البيانات من واجهة برمجة التطبيقات.
إنشاء رسالة CreateTripRequest
لإنشاء رحلة والحصول على رمز مميّز للرحلة، اتّبِع الخطوات التالية لإنشاء رسالة CreateTripRequest وإرسالها:
- المصادقة: استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC) للحصول على رمز مميّز للوصول من أجل تفويض طلبك. لمزيد من التفاصيل، يُرجى الاطّلاع على إنشاء رمز OAuth مميّز.
- إنشاء معرّف رحلة: أنشِئ معرّف رحلة فريدًا (
tripId) بتنسيق UUIDv4 لتحديد الرحلة على خادمك. - إنشاء الحمولة: أنشئ حمولة JSON تتضمّن معرّفات تطبيقاتك وإعدادات الضبط.
- استدعاء طريقة
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 |
لتلقّي الخطوط المتعدّدة للمسار النشط وأحوال حركة المرور في الوقت الفعلي، اضبط يحتاج السائقون إلى الإصدار 5.20.0.2 من تطبيق Waze أو إصدار أحدث على أجهزة Android، أو الإصدار 5.20.0.1 أو إصدار أحدث على أجهزة iOS، أو الإصدار 26.27 من تطبيق "خرائط Google" لأجهزة Android أو إصدار أحدث. |
| الإبلاغ عن الانحراف عن المسار (Waze فقط) | boolean |
لتتبُّع خروج السائق عن المسار، اضبط يجب أن يستخدم السائقون الإصدار 5.22 من Waze أو إصدارًا أحدث. |
| معدل التحديثات للرحلة | boolean |
تعدّل ميزة Navigation Connect بيانات الرحلة تلقائيًا كل 60 ثانية. لتفعيل التحديثات العالية التكرار (كل 5 ثوانٍ)، اضبط |
| إنشاء أحداث Google Cloud Pub/Sub | boolean |
لتفعيل إنشاء أحداث الرحلات باستخدام Google Cloud Pub/Sub، اضبط |
| قناع حقل Google Cloud Pub/Sub | FieldMask |
لإدارة أحجام الحمولة وتقليل عبء المعالجة في الخلفية أو تكاليف استخدام Google Cloud Pub/Sub، استخدِم |
الحصول على الرمز المميّز للرحلة من الردّ
تعرض الطريقة 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.