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

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

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

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

پیام CreateTripRequest بساز

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

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

مثال زیر نشان می‌دهد که چگونه می‌توان با ارسال پیام 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 تنظیم کنید.

رانندگان به Waze نسخه ۵.۲۰.۰.۲ یا جدیدتر در Android، نسخه ۵.۲۰.۰.۱ یا جدیدتر در iOS، یا Google Maps برای Android نسخه ۲۶.۲۷ یا جدیدتر نیاز دارند.

گزارش انحراف از مسیر (فقط Waze) boolean

برای ردیابی زمانی که راننده از مسیر خارج می‌شود، config.enableRouteDeviationReporting را روی true تنظیم کنید.

رانندگان به Waze نسخه ۵.۲۲ یا بالاتر نیاز دارند.

بسامد به‌روزرسانی سفر boolean

به‌طور پیش‌فرض، Navigation Connect داده‌های سفر را هر ۶۰ ثانیه یک‌بار به‌روز می‌کند. برای فعال کردن به‌روزرسانی‌های با بسامد بالا (هر ۵ ثانیه)، 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 پاسخی حاوی کد سفر اصالت‌سنجی‌شده برمی‌گرداند. برای مجاز کردن جلسه ناوبری، این توکن را از پاسخ استخراج کنید و آن را به برنامه تلفن همراهتان ارسال کنید تا در نشانی وب راه‌اندازی گنجانده شود.

نمونه کد زیر یک پاسخ نمونه را نشان می‌دهد:

{
    "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 Maps یا Waze شروع شود.

قدم بعدی چیست

از کد سفر برای راه‌اندازی Google Maps یا Waze استفاده کنید.

راه‌اندازی Google Maps یا Waze