راه‌اندازی Roads API

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

اگر نشانی صورت‌حساب شما در منطقه اقتصادی اروپا است، از ۸ ژوئیه ۲۰۲۵، شرایط خدمات «پلاتفرم Google Maps» در منطقه اقتصادی اروپا بر استفاده شما از «سرویس‌ها» اعمال خواهد شد. عملکرد بسته به منطقه متفاوت است. بیشتر بدانید.

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

پیش‌نیازها

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

1. بررسی صورت‌حساب و هزینه استفاده در Roads APIاستفاده و صورت‌حساب.

2. تأیید کنید که حساب Google Cloud دارید.

   به سیستم کنسول Google Cloud وارد شوید
   توجه: اگر کاربر جدید هستید و «حساب Google Cloud» ندارید، یعنی نمی‌توانید به سیستم کنسول وارد شوید، شروع به کار با Google Maps Platform را ببینید.

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

   رفتن به صفحه «صورت‌حساب»
   توجه: اگر کاربر جدید هستید و پروژه Google Cloud ندارید، شروع به کار با Google Maps Platform را ببینید.
1. پروژه‌تان را انتخاب کنید تا صفحه صورت‌حساب باز شود.

2. در صفحه صورت‌حساب:

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

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

قبل‌از اینکه بتوانید از Roads API استفاده کنید، باید از کنسول Google Cloud یا فرمان gcloud برای فعال کردن آن در پروژه Google Cloud خود استفاده کنید.

توجه: پس‌از فعال کردن API، ممکن است لازم باشد چند دقیقه صبر کنید تا بتوانید درخواستی به آن ارسال کنید.

برای فعال کردن میانای برنامه‌سازی کاربردی:

کنسول

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

   Roads API را فعال کنید

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

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

gcloud

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

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

• gcloud services enable
• gcloud services disable

دریافت کلید میانای برنامه‌سازی کاربردی برای استفاده با Roads API

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

کلید میانای برنامه‌سازی کاربردی رشته حرفی‌عددی منحصربه‌فردی است که حساب Cloud Billing و پروژه Google Cloud شما را با درخواستی که برنامه‌تان از میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار Google Maps Platform می‌کند مرتبط می‌کند. برای ایجاد کلید جدید یا افزودن میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار به کلید موجود، این دستورالعمل‌ها را دنبال کنید.

کنسول

1. به صفحه پلاتفرم Google Maps > کلیدها و اطلاعات کاربری بروید.

   به صفحه «کلیدها و اعتبارنامه‌ها» بروید

2. اگر درخواست شد، پروژه‌تان را انتخاب کنید.

3. یکی از موارد زیر را انجام دهید:

   • ایجاد کلید جدید:

     1. روی ایجاد اطلاعات کاربری > کلید میانای API کلیک کنید.
     2. در پانل ایجاد کلید میانای API، فهرست انتخاب محدودیت‌های میانای API را باز کنید.
     3. هر میانای برنامه‌سازی کاربردی را که این کلید به آن نیاز ندارد پاک کنید و مطمئن شوید Roads API انتخاب‌شده باقی بماند.
     4. روی ایجاد کردن کلیک کنید. پانل کلید میانای برنامه‌سازی کاربردی جدیدتان را نمایش می‌دهد.

   • استفاده از کلید موجود:

     1. روی نام کلید کلیک کنید.
     2. در فهرست انتخاب محدودیت‌های میانای برنامه‌سازی کاربردی، Roads API را انتخاب کنید.
     3. روی ذخیره کلیک کنید.

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

4. برای دیدن رشته کلید در آینده، به صفحه کلیدها و اطلاعات کاربری بروید و روی نمایش کلید برای کلید کلیک کنید.

اگر کنسول با این مراحل متفاوت است، ایجاد کلید میانای برنامه‌سازی کاربردی و افزودن محدودیت‌های کلید میانای برنامه‌سازی کاربردی را در اسناد Google Cloud ببینید.

gcloud

در فرمان‌های زیر، PROJECT_ID را با شناسه پروژه‌تان جایگزین کنید.

• ایجاد کلید جدید: فرمان زیر را اجرا کنید و DISPLAY_NAME را با نامی برای کلید جایگزین کنید.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=roads.googleapis.com

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

  • gcloud services api-keys create

• استفاده از کلید موجود: فرمان زیر را اجرا کنید و KEY_ID را با شناسه کلید جایگزین کنید. پرچم --append میاناهای برنامه‌سازی کاربردی را که کلید ازقبل مجاز کرده است حفظ می‌کند. بدون آن، فرمان جایگزین آن‌ها می‌شود.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=roads.googleapis.com

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

  • gcloud services api-keys update
  • gcloud services api-keys list

  شناسه کلید، رشته کلید یا نام نمایشی نیست. برای پیدا کردن آن، gcloud services api-keys list --project="PROJECT_ID" را اجرا کنید. شناسه بخش آخر فیلد name است: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

برای دیدن رشته کلید، gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID" را اجرا کنید.

درخواست میانای برنامه‌سازی کاربردی

درخواست Roads API ایجاد کنید تا پاسخ JSON برگردانده شود که نقاط مشخص‌شده را به هندسه جاده می‌چسباند. باید رشته حرفی‌عددی کلید میانای برنامه‌سازی کاربردی را در هر درخواست بگنجانید و برای درخواست‌هایی که حاوی کلید میانای برنامه‌سازی کاربردی هستند از HTTPS استفاده کنید.

1. روی API_KEY در کد زیر کلیک کنید تا رشته الفبانمایی کلید را درج کنید:

   curl -L -X GET 'https://roads.googleapis.com/v1/snapToRoads?path=-35.27801%2C149.12958%7C-35.28032%2C149.12907%7C-35.28099%2C149.12929%7C-35.28144%2C149.12984%7C-35.28194%2C149.13003%7C-35.28282%2C149.12956%7C-35.28302%2C149.12881%7C-35.28473%2C149.12836&interpolate=true&key=YOUR_API_KEY'
   

2. روی نماد کپی در نمونه کد، ، کلیک کنید تا فرمان curl کپی شود.
3. فرمان را در پنجره ترمینال جای‌گذاری کنید و فرمان را اجرا کنید.

پاسخ در قالب JSON است:

{
  "snappedPoints": [
    {
      "location": {
        "latitude": -35.278004899930188,
        "longitude": 149.129531998742
      },
      "originalIndex": 0,
      "placeId": "ChIJr_xl0GdNFmsRsUtUbW7qABM"
    },
    {
      "location": {
        "latitude": -35.2784195,
        "longitude": 149.12946589999999
      },
      "placeId": "ChIJr_xl0GdNFmsRsUtUbW7qABM"
    },
    ...
    {
      "location": {
        "latitude": -35.284727644851415,
        "longitude": 149.12833853807396
      },
      "originalIndex": 7,
      "placeId": "ChIJtWxAZmpNFmsRlbUCkc6VtnA"
    }
  ]
}

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

احتیاط: از کلید میانای برنامه‌سازی کاربردی نامحدود می‌توان برای درخواست به هر سرویس Google Maps Platform، ازجمله Roads API، استفاده کرد. شما مسئولیت مالی هزینه‌های ناشی از سوءاستفاده از کلیدهای میانای API نامحدود را برعهده دارید.

Google اکیداً توصیه می‌کند که کلیدهای میانای API خود را با محدود کردن استفاده از آن‌ها فقط به میاناهای برنامه‌سازی کاربردی و برنامه‌هایی که به آن‌ها نیاز دارند، محدود کنید. محدود کردن کلیدهای میانای API با محافظت از برنامه شما دربرابر درخواست‌های غیرمجاز، امنیت آن را افزایش می‌دهد. کلیدهای میانای برنامه‌سازی کاربردی از دو نوع محدودیت پشتیبانی می‌کنند:

• محدودیت‌های میانای API مشخص می‌کند کدام کیت‌های توسعه نرم‌افزار و میاناهای API را می‌توان بااستفاده از کلید میانای API فراخوانی کرد. کنسول و gcloud CLI هنگام ایجاد کلید به حداقل یک محدودیت API نیاز دارند.
• محدودیت‌های برنامه مشخص می‌کند کدام وب‌سایت‌ها، نشانی‌های IP، یا برنامه‌ها می‌توانند از کلید میانای برنامه‌سازی کاربردی استفاده کنند.

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

قدم بعدی چیست

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