روال‌های مطلوب استفاده از خدمات وب Map Tiles API

سرویس‌های وب «پلاتفرم Google Maps» مجموعه‌ای از میاناهای HTTP به سرویس‌های Google است که داده‌های جغرافیایی را برای برنامه‌های نقشه شما ارائه می‌دهد.

این راهنما برخی‌از روال‌های رایج را که برای راه‌اندازی درخواست‌های سرویس وب و پردازش پاسخ‌های سرویس مفید هستند شرح می‌دهد. برای دریافت مستندات کامل Map Tiles API، به راهنمای توسعه‌دهنده مراجعه کنید.

سرویس وب چیست؟

سرویس‌های وب «پلاتفرم Google Maps» میانایی برای درخواست داده‌های Maps API از سرویس‌های خارجی و استفاده از داده‌ها در برنامه‌های Maps شما است. این سرویس‌ها طراحی شده‌اند تا مطابق با محدودیت‌های پروانه در «شرایط خدمات پلاتفرم Google Maps»، همراه با نقشه استفاده شوند.

سرویس‌های وب Maps APIs از درخواست‌های HTTP(S) به نشانی‌های وب خاص استفاده می‌کنند و پارامترهای نشانی وب و/یا داده‌های POST با قالب JSON را به‌عنوان آرگومان به سرویس‌ها ارسال می‌کنند. به‌طور کلی، این سرویس‌ها داده‌ها را در بدنه پاسخ به‌صورت JSON برای تجزیه و/یا پردازش توسط برنامه شما برمی‌گردانند.

نمونه‌ای از درخواست سرویس وب درخواست فراداده «نمای خیابان» است که فرم زیر را دارد:

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

توجه: همه برنامه‌های Map Tiles API به اصالت‌سنجی نیاز دارند. اطلاعات بیشتری درباره اعتبارنامه‌های اصالت‌سنجی دریافت کنید.

دسترسی SSL/TLS

برای همه درخواست‌های «پلاتفرم Google Maps» که از کلیدهای API استفاده می‌کنند یا حاوی داده‌های کاربر هستند، HTTPS الزامی است. درخواست‌هایی که ازطریق HTTP ارسال می‌شوند و حاوی داده‌های حساس هستند ممکن است رد شوند.

استفاده مؤدبانه از Google APIs

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

عقب‌نشینی نمایی

در موارد نادر، ممکن است مشکلی در ارائه درخواست شما پیش بیاید؛ ممکن است کد پاسخ HTTP‏ 4XX یا 5XX دریافت کنید، یا اتصال TCP ممکن است به‌سادگی در جایی بین کلاینت شما و سرور Google قطع شود. اغلب ارزش دارد که درخواست را دوباره امتحان کنید زیرا درخواست پیگیری ممکن است موفق شود درحالی‌که درخواست اصلی ناموفق بوده است. بااین‌حال، مهم است که به‌طور مکرر درخواست‌های تکراری به سرورهای Google ارسال نکنید. این رفتار حلقه‌ای می‌تواند شبکه بین کارخواه شما و Google را بیش‌ازحد بارگذاری کند و برای بسیاری از طرفین مشکل ایجاد کند.

رویکرد بهتر این است که با افزایش تأخیر بین تلاش‌ها، دوباره امتحان کنید. معمولاً تأخیر با هر تلاش با یک عامل ضربی افزایش می‌یابد، رویکردی که به‌عنوان عقب‌گرد نمایی شناخته می‌شود.

برای مثال، برنامه‌ای را درنظر بگیرید که می‌خواهد این درخواست را به Time Zone API ارسال کند:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

مثال Python زیر نشان می‌دهد که چگونه درخواست را با عقب‌نشینی نمایی انجام دهید:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

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

درخواست‌های همگام‌سازی‌شده

تعداد زیاد درخواست‌های همگام‌سازی‌شده به میاناهای برنامه‌سازی کاربردی Google می‌تواند مانند حمله «جلوگیری از سرویس توزیع‌شده» (DDoS) به زیرساخت Google به‌نظر برسد و به همین ترتیب با آن برخورد شود. برای اجتناب از این امر، باید مطمئن شوید که درخواست‌های API بین کارخواه‌ها همگام‌سازی نمی‌شوند.

برای مثال، برنامه‌ای را درنظر بگیرید که زمان را در منطقه زمانی کنونی نمایش می‌دهد. این برنامه احتمالاً زنگ هشداری در سیستم‌عامل کارخواه تنظیم می‌کند که آن را در ابتدای دقیقه بیدار می‌کند تا زمان نمایش‌داده‌شده به‌روز شود. برنامه نباید هیچ تماسی با «میانای برنامه‌سازی کاربردی» به‌عنوان بخشی از پردازش مرتبط با آن هشدار برقرار کند.

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

درعوض، یک طراحی خوب احتمالی این است که زنگ هشدار دومی برای زمانی که به‌طور تصادفی انتخاب شده است تنظیم شود. وقتی این زنگ هشدار دوم به‌صدا درمی‌آید، برنامه هر API که نیاز دارد را فرا می‌خواند و نتایج را ذخیره می‌کند. وقتی برنامه می‌خواهد نمایش خود را در ابتدای دقیقه به‌روز کند، از نتایج ذخیره‌شده قبلی استفاده می‌کند و دوباره API را فراخوانی نمی‌کند. با این رویکرد، تماس‌های میانای برنامه‌سازی کاربردی به‌طور یکنواخت درطول زمان توزیع می‌شوند. علاوه‌براین، فراخوان‌های API هنگام به‌روزرسانی نمایشگر، پردازش را به‌تأخیر نمی‌اندازند.

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

درحال پردازش پاسخ‌ها

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

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

خدمات وب Google Maps پاسخ‌هایی ارائه می‌دهد که درک آن‌ها آسان است، اما دقیقاً کاربرپسند نیستند. هنگام اجرای پُرسمان، به‌جای نمایش مجموعه‌ای از داده‌ها، احتمالاً می‌خواهید چند مقدار خاص را استخراج کنید. به‌طورکلی، می‌خواهید پاسخ‌های سرویس وب را تجزیه کنید و فقط مقادیر موردعلاقه‌تان را استخراج کنید.

طرح تجزیه‌ای که استفاده می‌کنید به این بستگی دارد که آیا خروجی را در JSON برمی‌گردانید یا نه. پاسخ‌های JSON، که درحال‌حاضر به‌شکل اشیاء جاوا اسکریپت هستند، ممکن است در خود جاوا اسکریپت در سمت کارخواه پردازش شوند.