این محصول یا ویژگی آزمایشی (قبل از GA) است. محصولات و ویژگی‌های قبل از GA ممکن است پشتیبانی محدودی داشته باشند و تغییرات در محصولات و ویژگی‌های قبل از GA ممکن است با سایر نسخه‌های قبل از GA سازگار نباشد. پیشنهادات قبل از GA تحت پوشش شرایط خاص سرویس پلتفرم نقشه‌های گوگل هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه‌اندازی مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

راه اندازی اتصال ناوبری

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

این سند مراحل مورد نیاز برای شروع استفاده از Navigation Connect را شرح می‌دهد.

بررسی کنید که آیا پیش‌نیازها را رعایت می‌کنید یا خیر.

API را در پروژه Google Cloud خود فعال کنید.

OAuth را برای ارسال یک درخواست API احراز هویت شده پیکربندی کنید.

محصولات پلتفرم نقشه‌های گوگل برای جلوگیری از استفاده غیرمجاز، فراخوانی‌های API را ملزم به درج توکن OAuth می‌کنند.

یک توکن OAuth ایجاد کنید

Navigation Connect از OAuth 2.0 برای احراز هویت پشتیبانی می‌کند. گوگل از سناریوهای رایج OAuth 2.0، مانند سناریوهای مربوط به یک وب سرور، پشتیبانی می‌کند.

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

شما می‌توانید مستقیماً با ارسال درخواست‌های API به سرور، APIهای نقشه‌های گوگل را فراخوانی کنید، یا می‌توانید از کتابخانه‌های کلاینت برای ساده‌سازی کد خود استفاده کنید. نقشه‌های گوگل کتابخانه‌های کلاینت را برای Go، Java، Node.js و Python ارائه می‌دهد. برای اطلاعات بیشتر، به Navigation Connect client libraries مراجعه کنید.

مرور کلی OAuth

شما می‌توانید توکن‌های دسترسی را با OAuth به روش‌های مختلفی بسته به محیط استقرار خود ایجاد و مدیریت کنید.

شما می‌توانید از OAuth 2.0 برای تعاملات سرور به سرور بین برنامه خود و یک سرویس گوگل استفاده کنید. برای این سناریو، شما از یک حساب سرویس مرتبط با برنامه خود به جای یک کاربر خاص استفاده می‌کنید. می‌توانید درخواست‌های API را با استفاده از حساب سرویس و بدون دخالت مستقیم کاربران ارسال کنید. برای اطلاعات بیشتر در مورد روش‌های احراز هویت، به روش‌های احراز هویت در گوگل مراجعه کنید.

به عنوان یک روش جایگزین، می‌توانید Navigation Connect را در یک برنامه تلفن همراه اندروید یا iOS ادغام کنید. برای اطلاعات بیشتر در مورد استفاده از OAuth و مدیریت توکن‌های دسترسی برای محیط‌های مختلف استقرار، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.

دامنه‌های OAuth

برای استفاده از OAuth با Navigation Connect، باید به توکن OAuth، محدوده‌ی زیر را اختصاص دهید:

https://www.googleapis.com/auth/cloud-platform

مثال: فراخوانی‌های REST API را در محیط توسعه محلی خود امتحان کنید

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

این مثال نحوه استفاده از توکن OAuth ارائه شده توسط Application Default Credentials (ADC) را برای برقراری تماس شرح می‌دهد. برای اطلاعات بیشتر در مورد استفاده از ADC برای فراخوانی API های گوگل با کتابخانه‌های کلاینت، به بخش احراز هویت با استفاده از کتابخانه‌های کلاینت مراجعه کنید.

از رویه REST زیر فقط برای توسعه یا آزمایش استفاده کنید، نه برای تولید.

پیش‌نیازها

قبل از اینکه با استفاده از ADC یک درخواست REST ارسال کنید، از رابط خط فرمان gcloud برای ارائه اعتبارنامه به ADC استفاده کنید:

رابط خط فرمان gcloud را نصب و راه‌اندازی کنید. برای اطلاعات بیشتر، به «نصب رابط خط فرمان gcloud» مراجعه کنید.
با رابط خط فرمان gcloud احراز هویت کنید:
```
gcloud auth application-default login
```
مراحل ورود به سیستم را تکمیل کنید تا اعتبارنامه‌های شما در فایل اعتبارنامه محلی مورد استفاده ADC ذخیره شود.

برای اطلاعات بیشتر، به تنظیم ADC برای یک محیط توسعه محلی مراجعه کنید.

درخواست REST ارسال کنید

در این مثال، شما دو هدر درخواست ارسال می‌کنید:

با استفاده از دستور زیر، توکن OAuth را در هدر Authorization وارد کنید تا توکن تولید شود:
gcloud auth application-default print-access-token
توکن برگردانده شده دامنه‌ای به آدرس https://www.googleapis.com/auth/cloud-platform دارد.
شناسه یا نام پروژه گوگل کلود خود را که امکان پرداخت در آن فعال است، در سربرگ X-Goog-User-Project وارد کنید.

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

در نمونه کد زیر، مقادیر خود را جایگزین متغیرهای ورودی کنید:

PROJECT_ID : شناسه پروژه Google Cloud شما
ANDROID_APP_ID : نام بسته اندروید برنامه شما، در صورت وجود
IOS_APP_ID : شناسه بسته iOS برنامه شما، در صورت وجود

#!/bin/bash
trip_id="$(uuidgen)"
access_token="$(gcloud auth application-default print-access-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 '{
"androidAppId": "ANDROID_APP_ID",
"iosAppId": "IOS_APP_ID",
}'

برای کپی کردن دستور curl ، در نمونه کد روی Copy کلیک کنید.
دستور را در یک پنجره ترمینال پیست کنید و سپس آن را اجرا کنید.

پاسخ یک شیء JSON است:

{
  "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 : شناسه‌ی منحصر به فرد از نوع long-integer برای پروژه
TRIP_ID : شناسه سفر UUIDv4 که بک‌اند شما تولید می‌کند
BASE64_ENCODED_TRIP_TOKEN : توکن احراز هویت شده‌ای که متد createTrip برای شروع ناوبری گام به گام ردیابی شده در Google Maps یا Waze برمی‌گرداند.

عیب‌یابی

اگر درخواست شما پیام خطایی مبنی بر اینکه این API از اعتبارنامه‌های کاربر نهایی پشتیبانی نمی‌کند، برمی‌گرداند، به عیب‌یابی تنظیمات ADC خود مراجعه کنید.

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

در مرحله بعد، حساب‌های سرویس خود را برای Navigation Connect API پیکربندی کنید تا از ارتباط امن و سرور به سرور بین زیرساخت backend، Google Maps و Waze پشتیبانی شود.

حساب کاربری سرویس خود را تنظیم کنید