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

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

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

پیش‌نیازها

این راهنما نشان می‌دهد که چگونه «حساب Google Cloud» و پروژه Google Cloud خود را با فعال کردن صورت‌حساب راه‌اندازی کنید. همچنین باید با نحوه کسر هزینه برای استفاده از Navigation Connect API آشنا باشید.

  1. بررسی صورت‌حساب و هزینه استفاده در استفاده و صورت‌حساب Navigation Connect.
  2. تأیید کنید که حساب Google Cloud دارید.

    به سیستم کنسول Google Cloud وارد شوید
  3. تأیید کنید که پروژه Google Cloud با صورت‌حساب فعال دارید.

    رفتن به صفحه «صورت‌حساب»
    1. پروژه‌تان را انتخاب کنید تا صفحه صورت‌حساب باز شود.
    2. در صفحه صورت‌حساب:

      • اگر صورت‌حساب ازقبل برای پروژه انتخاب‌شده فعال شده باشد و فقط یک حساب صورت‌حساب داشته باشید، صفحه صورت‌حساب باز می‌شود.
      • اگر چند حساب صورت‌حساب دارید، رفتن به حساب صورت‌حساب پیوندشده را انتخاب کنید تا جزئیات حساب صورت‌حساب مرتبط با پروژه را ببینید.
      • اگر حساب صورت‌حساب وجود داشته باشد اما با پروژه مرتبط نباشد، از شما خواسته می‌شود حساب صورت‌حساب را به پروژه پیوند دهید.
      • اگر حساب صورت‌حسابی وجود ندارد، یا می‌خواهید حساب صورت‌حساب جدیدی ایجاد کنید، مدیریت حساب‌های صورت‌حساب را انتخاب کنید تا حساب صورت‌حساب جدیدی ایجاد کنید. برای اطلاعات بیشتر، ایجاد حساب Cloud Billing سلف سرویس جدید را ببینید.

فعال کردن میانای برنامه‌سازی کاربردی و به‌تأیید رساندن برنامه

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

۱. فعال کردن Navigation Connect API

از کنسول Google Cloud یا فرمان gcloud برای فعال کردن Navigation Connect API در پروژه Google Cloud خود استفاده کنید.

برای فعال کردن API، مراحل زیر را انجام دهید:

کنسول

  1. صفحه محصول را در کنسول Google Cloud باز کنید:

    فعال کردن Navigation Connect API
  2. روی دکمه فعال کردن کلیک کنید.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "navigationconnect.googleapis.com"

درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

۲. شروع فرایند درستی‌سنجی برنامه

پس‌از فعال کردن میانای برنامه‌سازی کاربردی، باید برنامه‌تان را به‌تأیید برسانید تا Navigation Connect API فعال شود. فعال کردن میانای برنامه‌سازی کاربردی به‌تنهایی دسترسی اعطا نمی‌کند؛ باید جزئیات کسب‌وکار و برنامه را برای بازبینی ارائه دهید تا بتوانید از Navigation Connect API استفاده کنید.

برای شروع فرایند درستی‌سنجی، از یکی از روش‌های زیر استفاده کنید:

  • API Marketplace:
    1. در API Marketplace، کارت Navigation Connect API را پیدا کنید.
    2. روی نماد آبی درستی‌سنجی لازم است کلیک کنید تا جریان درستی‌سنجی شروع شود.
  • کلیدها و اطلاعات اعتباری در کنسول Google Cloud:
    1. در کنسول Google Cloud، به صفحه کلیدها و اطلاعات کاربری بروید.
    2. روی کلیدها و اطلاعات کاربری Navigation Connect کلیک کنید.
    3. در برنما، روی شروع درستی‌سنجی کلیک کنید.

۳. ارائه جزئیات برنامه، جمع‌آوری داده، و حریم خصوصی

جدول زیر جزئیاتی را که باید برای درستی‌سنجی برنامه ارائه دهید شرح می‌دهد:

فیلد شرح
جزئیات برنامه

جزئیات زیر را ارائه دهید تا مطمئن شوید برنامه‌تان به‌درستی در Google Maps و Waze نمایش داده می‌شود.

نام کسب‌وکار یا برنامه نامی را وارد کنید که می‌خواهید به کاربران در Google Maps و Waze نمایش داده شود.
شناسه برنامه «نام بسته Android» یا «شناسه بسته iOS» خود را ارائه دهید.
پیوند جامع iOS پیوند جامع iOS را که به کاربران اجازه می‌دهد به برنامه‌تان برگردند ارائه دهید (فقط در Waze دردسترس است).
نشان‌واره برنامه (فقط Waze) (اختیاری) نشان‌واره‌ای با قالب PNG یا JPG (‏۳۲×۳۲ تا ۱۲۸×۱۲۸ پیکسل) بارگذاری کنید تا نشان‌واره برنامه‌تان درطول جلسه ناوبری در Waze نمایش داده شود.
جزئیات حریم خصوصی و جمع‌آوری داده‌ها

برای اطمینان از شفافیت، اعتماد راننده، و امنیت داده‌ها، جزئیات زیر را وارد کنید.

پیوند خط‌مشی رازداری نشانی وب خط‌مشی رازداری برنامه‌تان را ارائه دهید. این پیوند در صفحه رضایت نشان داده می‌شود.
کنترل‌کننده‌های داده اضافی (اختیاری) نام تجاری و پیوند خط‌مشی رازداری را برای همه مدیران داده شخص ثالث، مثل ISV، ارائه دهید. این جزئیات در صفحه رضایت نشان داده می‌شود.
رعایت مقررات داده‌ها اگر برنامه‌تان در ایالات متحده فعالیت می‌کند، چارگوش این برنامه برای سفرهایی که در ایالات متحده انجام می‌شود استفاده خواهد شد را انتخاب کنید تا از مطابقت با مقررات محلی مطمئن شوید.

۴. مرور و ارسال

پیش‌از ارسال برنامه برای درستی‌سنجی، خلاصه اطلاعات ارائه‌شده را مرور کنید.

  1. نام برنامه، پلاتفرم، شناسه‌ها، و پیوندها را به‌دقت بررسی کنید.

  2. چارگوش انتخاب همه اطلاعات دقیق است را انتخاب کنید.
  3. روی ارسال کلیک کنید.

پس‌از ارسال برنامه برای درستی‌سنجی، مرحله بازبینی آغاز می‌شود.

  • خط زمان: درستی‌سنجی معمولاً ۱ تا ۳ روز کاری طول می‌کشد.
  • اعلان: وقتی وضعیت درستی‌سنجی تغییر می‌کند، ایمیلی دریافت می‌کنید. همچنین ایمیلی دریافت می‌کنید که در آن شناسه نمایه پرداخت یا شناسه توسعه‌دهنده Android شما درخواست شده است. اگر به شناسه توسعه‌دهنده Android نیاز دارید، ایجاد حساب توسعه‌دهنده را ببینید.
  • پیگیری وضعیت: پیشرفت خود را در صفحه کلیدها و اطلاعات اعتباری در کنسول Google Cloud پایش کنید.
  • پشتیبانی: برای به‌روزرسانی پیکربندی پس‌از تأیید بدون تأثیر بر تولید، بلیت پشتیبانی ایجاد کنید.

پس‌از درستی‌سنجی، برنامه شما مجاز است از Navigation Connect API برای تولید کردن کدهای سفر استفاده کند که دسترسی به جلسه ناوبری را مجاز می‌کند و به شما امکان می‌دهد جزئیات سفر را از Google Maps و Waze دریافت کنید.

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

ایجاد کد OAuth

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

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

می‌توانید با ارسال درخواست‌های میانای برنامه‌سازی کاربردی به سرور، مستقیماً میاناهای برنامه‌سازی کاربردی Google Maps را فراخوانی کنید، یا می‌توانید از کتابخانه‌های کارخواه برای ساده کردن کدتان استفاده کنید. ‫Google Maps کتابخانه‌های کارخواه را برای Go،‏ Java،‏ Node.js، و Python ارائه می‌دهد. برای اطلاعات بیشتر، کتابخانه‌های کارخواه Navigation Connect را ببینید.

نمای کلی OAuth

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

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

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

دامنه‌های OAuth

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

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

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

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

این مثال نحوه استفاده از کد OAuth ارائه‌شده توسط اعتبارنامه‌های پیش‌فرض برنامه (ADC) را برای برقراری تماس شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از ADC برای فراخوانی Google APIs با کتابخانه‌های کارخواه، به اصالت‌سنجی بااستفاده از کتابخانه‌های کارخواه مراجعه کنید.

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

پیش‌نیازها

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

  1. gcloud CLI را نصب و مقداردهی اولیه کنید. برای اطلاعات بیشتر، به نصب gcloud CLI مراجعه کنید.

  2. با gcloud CLI اصالت‌سنجی کنید:

    gcloud auth application-default login
  3. فرایند ورود به سیستم را تکمیل کنید تا اطلاعات اعتباری‌تان در فایل اطلاعات اعتباری محلی مورداستفاده ADC ذخیره شود.

برای اطلاعات بیشتر، راه‌اندازی ADC برای محیط توسعه محلی را ببینید.

ایجاد درخواست REST

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

  • بااستفاده از فرمان زیر برای تولید کردن توکن، توکن OAuth را در سرصفحه Authorization ارسال کنید:

    gcloud auth application-default print-access-token

    کد برگردانده‌شده دارای دامنه https://www.googleapis.com/auth/cloud-platform است.

  • شناسه یا نام پروژه Google Cloud خود را که صورت‌حساب آن فعال است در سرایند X-Goog-User-Project ارسال کنید.

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

  1. در نمونه کد زیر، جای‌بان‌ها را با مقادیر خودتان جایگزین کنید:

    • PROJECT_ID: شناسه پروژه Google Cloud شما
    • ANDROID_APP_ID: نام بسته Android برنامه شما، درصورت وجود
    • 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",
    }'
  2. برای کپی کردن فرمان curl، روی کپی کردن در نمونه کد کلیک کنید.

  3. فرمان را در پنجره ترمینال جای‌گذاری کنید و سپس آن را اجرا کنید.

پاسخ در قالب 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: شناسه سفر UUIDv4 که باطن شما تولید می‌کند
  • BASE64_ENCODED_TRIP_TOKEN: نمودافزار اصالت‌سنجی‌شده‌ای که روش createTrip برای شروع ناوبری گام‌به‌گام ردیابی‌شده در Google Maps یا Waze برمی‌گرداند

عیب‌یابی

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

قدم بعدی چیست

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

راه‌اندازی حساب سرویس