راه‌اندازی میانای برنامه‌سازی کاربردی Places (جدید)

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

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

پیش‌نیازها

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

  1. صورت‌حساب و هزینه استفاده را در استفاده و صورت‌حساب Places API (جدید) مرور کنید.

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

    به سیستم کنسول Google Cloud وارد شوید

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

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

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

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

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

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

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

کنسول

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

    فعال کردن Places API (جدید)

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

gcloud

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

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

دریافت کلید میانای برنامه‌سازی کاربردی برای استفاده با Places API (جدید)

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

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

کنسول

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

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

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

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

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

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

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

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

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

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

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

gcloud

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

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

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

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

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

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

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

    شناسه کلید، رشته کلید یا نام نمایشی نیست. برای پیدا کردن آن، 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" را اجرا کنید.

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

درخواست Places API (جدید) ایجاد کنید تا پاسخ JSON برای «جستجوی نوشتار» در رشته «Spicy Vegetarian Food in Sydney, Australia» (غذای گیاهی تند در سیدنی، استرالیا) برگردانده شود. باید رشته الفبانمایی کلید میانای برنامه‌سازی کاربردی‌تان را در هر درخواست بگنجانید و برای درخواست‌هایی که شامل کلید میانای برنامه‌سازی کاربردی است از HTTPS استفاده کنید.

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

    curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'
  2. روی نماد کپی در نمونه کد، نماد کپی را انتخاب کنید.، کلیک کنید تا فرمان curl کپی شود.
  3. فرمان را در پنجره ترمینال جای‌گذاری کنید و فرمان را اجرا کنید.

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

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

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

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

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

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

ایجاد کد OAuth

‫Places API (جدید) از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. Google از سناریوهای رایج OAuth 2.0، مثل سناریوهای سرور وب، پشتیبانی می‌کند.

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

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

نمای کلی OAuth

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

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

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

دامنه‌های OAuth

برای استفاده از OAuth با Places API (جدید)، باید کد OAuth را به دامنه زیر اختصاص دهید:

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

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

اگر محیطی ندارید که توکن تولید کند و می‌خواهید Places 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 ارسال کنید.

برای فراخوانی Places API (جدید) بااستفاده از یک توکن OAuth، مراحل زیر را تکمیل کنید:

  1. در نمونه کد زیر، PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید:

    curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress" \
"https://places.googleapis.com/v1/places:searchText"

  2. برای کپی کردن فرمان curl، روی کپی کردن در نمونه کد کلیک کنید.

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

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

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

عیب‌یابی

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

قدم بعدی چیست

اکنون که Places API (New)‎ را فعال کرده‌اید و کلید میانای برنامه‌سازی کاربردی را پیکربندی کرده‌اید، درباره Places API (New)‎ را ببینید تا با نحوه استفاده از Places API (New)‎ بیشتر آشنا شوید.