یک سفر ایجاد کنید و یک توکن سفر دریافت کنید

برای راه‌اندازی ایمن یک جلسه ناوبری گام به گام برای راننده، بخش مدیریت شما باید یک سفر ایجاد کند و یک توکن سفر احراز هویت شده را از API Navigation Connect دریافت کند.

در Navigation Connect، یک سفر (trip) نشان‌دهنده یک جلسه ناوبری به یک مقصد واحد است. برای ایجاد یک سفر و دریافت توکن سفر احراز هویت‌شده ( authToken ) که برای تأیید جلسه لازم است، یک پیام CreateTripRequest به متد CreateTrip ارسال کنید. توکن سفر را به برنامه تلفن همراه خود ارسال کنید تا در URL راه‌اندازی برای Google Maps یا Waze قرار گیرد.

این راهنما نحوه تکمیل این فرآیند را با ایجاد یک شناسه سفر منحصر به فرد و ارسال درخواست API شما شرح می‌دهد.

ساخت یک پیام CreateTripRequest

برای ایجاد یک سفر و دریافت توکن سفر، مراحل زیر را برای ساخت و ارسال پیام CreateTripRequest انجام دهید:

  1. احراز هویت : از اعتبارنامه‌های پیش‌فرض برنامه (ADC) برای دریافت یک توکن دسترسی جهت تأیید درخواست خود استفاده کنید. برای جزئیات بیشتر، به ایجاد یک توکن OAuth مراجعه کنید.
  2. ایجاد شناسه سفر : یک شناسه سفر منحصر به فرد ( tripId ) با فرمت UUIDv4 ایجاد کنید تا سفر روی سرور شما شناسایی شود.
  3. ساخت payload : یک payload با فرمت JSON ایجاد کنید که شامل شناسه‌های برنامه و تنظیمات پیکربندی شما باشد.
  4. فراخوانی متد CreateTrip : ارسال یک درخواست POST به API با توکن دسترسی در هدر و payload در بدنه.

مثال زیر نحوه ایجاد یک سفر با ارسال پیام 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 داده‌های سفر را هر ۶۰ ثانیه به‌روزرسانی می‌کند. برای فعال کردن به‌روزرسانی‌های با فرکانس بالا (هر ۵ ثانیه)، config.enableHighFrequencyUpdates را روی true تنظیم کنید.

تولید رویداد Pub/Sub در گوگل کلود boolean

برای فعال کردن تولید رویداد سفر با استفاده از Google Cloud Pub/Sub، مقدار config.enablePubsub را روی true تنظیم کنید. این ویژگی به طور پیش‌فرض غیرفعال است.

ماسک میخانه/زیرفیلد گوگل کلود FieldMask

برای مدیریت اندازه‌های بار مفید و کاهش بار پردازش backend یا هزینه‌های استفاده از 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 : شناسه سفر تولید شده توسط backend شما با فرمت UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN : توکن سفر احراز هویت شده ( authToken.token ) که توسط متد CreateTrip برگردانده می‌شود. این توکن را به برنامه تلفن همراه خود ارسال کنید تا ناوبری گام به گام ردیابی شده در Google Maps یا Waze آغاز شود.

قدم بعدی چیست؟

از توکن سفر برای اجرای نقشه‌های گوگل یا ویز استفاده کنید.

نقشه گوگل یا ویز را اجرا کنید