این محصول یا ویژگی آزمایشی (قبل از 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 در یک محیط عملیاتی ، به روش‌های احراز هویت در گوگل مراجعه کنید.

درباره OAuth

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

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

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

درباره دامنه‌های OAuth

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

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

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

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

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

پیش‌نیازها

قبل از اینکه بتوانید با استفاده از ADC درخواست REST ارسال کنید، از رابط خط فرمان گوگل کلود (Google Cloud CLI) برای ارائه اعتبارنامه به ADC استفاده کنید:

رابط خط فرمان 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 وارد کنید.

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

فیلد 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 .
دستور را در یک پنجره ترمینال پیست کنید و دستور را اجرا کنید.

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

عیب‌یابی

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

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

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

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