API Geocoding را تنظیم کنید

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

اگر آدرس صورتحساب شما در منطقه اقتصادی اروپا باشد، که از ۸ ژوئیه ۲۰۲۵ لازم‌الاجرا است، شرایط خدمات پلتفرم نقشه‌های گوگل (EEA) برای استفاده شما از خدمات اعمال خواهد شد. عملکرد آن بر اساس منطقه متفاوت است. اطلاعات بیشتر .

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

۱. حساب و صورتحساب مطمئن شوید که پیش‌نیازها را رعایت می‌کنید.

۲. فعال کردن API API را در پروژه Google Cloud خود فعال کنید.

۳. اولین درخواست خود را مطرح کنید یک کلید API یا OAuth را برای ارسال یک درخواست API احراز هویت شده پیکربندی کنید.

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

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

کلید API، توکن OAuth

یک توکن OAuth ایجاد کنید

API ژئوکدینگ از استفاده از OAuth 2.0 برای احراز هویت پشتیبانی می‌کند. گوگل از سناریوهای رایج OAuth 2.0 مانند سناریوهای مربوط به یک وب سرور پشتیبانی می‌کند.

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

توجه:

در حالی که می‌توانید با ارسال درخواست‌های API به سرور، مستقیماً از APIهای نقشه‌های گوگل استفاده کنید، کتابخانه‌های کلاینت، ساده‌سازی‌هایی را ارائه می‌دهند که به طور قابل توجهی میزان کدی را که باید بنویسید کاهش می‌دهد. نقشه‌های گوگل کتابخانه‌های کلاینت را برای بسیاری از زبان‌های برنامه‌نویسی، از جمله Go، Java، Node.js و Python فراهم می‌کند.

برای مستندات و مثال‌ها ، به کتابخانه‌های کلاینت API مربوط به Geocoding مراجعه کنید.

درباره OAuth

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

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

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

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

برای استفاده از OAuth با Geocoding API، باید به توکن OAuth دامنه صحیح اختصاص داده شود. Geocoding API از دامنه‌های زیر پشتیبانی می‌کند:

• https://www.googleapis.com/auth/maps-platform.geocode — قابل استفاده با تمام نقاط پایانی API مربوط به Geocoding.
• https://www.googleapis.com/auth/maps-platform.geocode.address — فقط با GeocodeAddress برای ژئوکدینگ رو به جلو استفاده شود.
• https://www.googleapis.com/auth/maps-platform.geocode.location — فقط با GeocodeLocation برای ژئوکدینگ معکوس استفاده شود.
• https://www.googleapis.com/auth/maps-platform.geocode.place — فقط با GeocodePlace برای ژئوکدینگ مکان استفاده شود.

همچنین، می‌توانید از دامنه عمومی https://www.googleapis.com/auth/cloud-platform برای همه نقاط پایانی API ژئوکدینگ استفاده کنید. این دامنه در طول توسعه مفید است زیرا دامنه پیش‌فرض مورد استفاده هنگام ایجاد توکن‌ها با استفاده از gcloud است.

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

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

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

توجه : روش زیر برای فراخوانی REST برای استفاده در محیط عملیاتی در نظر گرفته نشده است. از این روش فقط برای محیط توسعه یا آزمایش استفاده کنید.

پیش‌نیازها

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

1. رابط خط فرمان gcloud را نصب و راه‌اندازی کنید .

2. دستور gcloud زیر را روی دستگاه محلی خود اجرا کنید تا فایل اعتبارنامه شما ایجاد شود:

   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.

• شناسه یا نام پروژه گوگل کلود خود را که امکان پرداخت در آن فعال است، در سربرگ X-Goog-User-Project وارد کنید.

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

1. فیلد PROJECT_ID را ویرایش کنید تا شناسه پروژه Google Cloud خود را وارد کنید.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. روی نماد کپی در نمونه کد کلیک کنید، ، برای کپی کردن دستور curl .
3. دستور را در یک پنجره ترمینال پیست کنید و دستور را اجرا کنید.

پاسخ یک شیء JSON است:

عیب‌یابی

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