راه‌اندازی Places Aggregate API

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

پیش‌نیازها

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

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

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

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

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

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

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

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

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

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

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

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

کنسول

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

   فعال کردن Places Aggregate API

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

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

gcloud

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

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

• gcloud services enable
• gcloud services disable

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

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

محصولات 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 Aggregate API همچنان انتخاب شده باشد.
     4. روی ایجاد کردن کلیک کنید. پانل کلید میانای برنامه‌سازی کاربردی جدیدتان را نمایش می‌دهد.

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

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

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

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

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

gcloud

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

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

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=areainsights.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=areainsights.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" را اجرا کنید.

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

این نمونه درخواستی را برای برگرداندن تعداد رستوران‌های سان‌فرانسیسکو که قیمت متوسطی دارند نشان می‌دهد.

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

   curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
   --header 'X-Goog-Api-Key: API_KEY' \
   --header 'Content-Type: application/json' \
   --data '{
      "insights":[
         "INSIGHT_COUNT"
      ],
      "filter":{
         "locationFilter":{
            "region":{
               "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
            }
         },
         "typeFilter":{
            "includedTypes":[
               "restaurant"
            ]
         },
         "priceLevels":[
            "PRICE_LEVEL_INEXPENSIVE"
         ]
      }
   }'
   

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

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

{
  "count": "1025"
}

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

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

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

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

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

ایجاد کد OAuth

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

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

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

نمای کلی OAuth

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

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

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

دامنه‌های OAuth

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

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

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

اگر محیطی ندارید که کد تولید کند و می‌خواهید Places Aggregate 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 Aggregate API بااستفاده از یک نمانه OAuth، مراحل زیر را تکمیل کنید:

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

   این مثال درخواستی را برای برگرداندن تعداد رستوران‌های سان‌فرانسیسکو که قیمت متوسطی دارند نشان می‌دهد:

   curl -X POST 'https://areainsights.googleapis.com/v1:computeInsights' \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   --data '{
   "insights":[
     "INSIGHT_COUNT"
   ],
   "filter":{
     "location_filter":{
        "region":{
           "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
        }
     },
     "type_filter":{
        "included_types":[
           "restaurant"
        ]
     },
     "price_levels":[
        "PRICE_LEVEL_INEXPENSIVE"
     ]
   }
   }'

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

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

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

{
  "count": "1025"
}

عیب‌یابی

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

قدم بعدی چیست

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