روال‌های مطلوب برای استفاده از Street View Static API

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

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

این راهنما برخی‌از روال‌های مطلوب رایج را که برای راه‌اندازی درخواست‌های سرویس وب و تصویر و پردازش پاسخ‌های سرویس مفید است شرح می‌دهد. برای اطلاعات بیشتر درباره Street View Static API، راهنمای توسعه‌دهنده را ببینید.

‫Street View Static API مانند یک وب API ایستا عمل می‌کند، درحالی‌که خدمات فراداده به‌عنوان یک خدمات وب عمل می‌کند. برای اطلاعات بیشتر درباره سرویس فراداده، به فراداده تصویر «نمای خیابان» مراجعه کنید.

«میانای برنامه‌سازی کاربردی وب» ایستا چیست؟

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

درخواست معمول Street View Static API به‌صورت زیر است:

  https://www.googleapis.com/streetview/z/x/y?parameters

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

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

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

درخواست «فراداده Street View Static API» به شکل زیر است:

https://maps.googleapis.com/maps/api/streetview/parameters

دسترسی SSL و TLS

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

درحال ساختن نشانی وب معتبر

ممکن است فکر کنید که نشانی وب «معتبر» واضح است، اما این‌طور نیست. نشانی وبی که در نوار نشانی مرورگر وارد می‌شود، برای مثال، ممکن است نویسه‌های خاصی داشته باشد (مثلاً "上海+中國")؛ مرورگر باید قبل‌از انتقال، این نویسه‌ها را به‌صورت داخلی به کدبندی دیگری ترجمه کند. به‌همین ترتیب، هر کدی که ورودی UTF-8 تولید یا دریافت می‌کند ممکن است نشانی‌های وب دارای نویسه‌های UTF-8 را «معتبر» درنظر بگیرد، اما همچنین باید این نویسه‌ها را قبل‌از ارسال به سرور وب ترجمه کند. این فرایند کدبندی نشانی وب یا کدبندی درصدی نامیده می‌شود.

نویسه‌های خاص

باید نویسه‌های ویژه را ترجمه کنیم زیرا همه نشانی‌های وب باید از دستور زبان مشخص‌شده در مشخصات شناسه منبع یکنواخت (URI) پیروی کنند. در عمل، این یعنی نشانی‌های وب باید فقط شامل زیرمجموعه خاصی از نویسه‌های ASCII باشد: نمادهای آشنای الفبایی-عددی، و برخی‌از نویسه‌های رزروشده برای استفاده به‌عنوان نویسه‌های کنترلی در نشانی‌های وب. این جدول این نویسه‌ها را خلاصه می‌کند:

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

• نویسه‌هایی که می‌خواهید مدیریت کنید خارج از مجموعه بالا هستند. برای مثال، نویسه‌های زبان‌های خارجی مانند 上海+中國 باید بااستفاده از نویسه‌های بالا کدبندی شوند. طبق قرارداد رایج، فاصله‌ها (که در نشانی‌های وب مجاز نیستند) اغلب بااستفاده از نویسه به‌علاوه '+' نیز نشان داده می‌شوند.
• نویسه‌ها در مجموعه بالا به‌عنوان نویسه‌های رزروشده وجود دارند، اما باید به‌صورت واقعی استفاده شوند. برای مثال، ? در نشانی‌های وب برای نشان دادن شروع رشته پُرسمان استفاده می‌شود؛ اگر می‌خواهید از رشته «? and the Mysterions» استفاده کنید، باید نویسه '?' را کدبندی کنید.

همه نویسه‌هایی که باید کدبندی URL شوند بااستفاده از نویسه '%' و مقدار هگز دو نویسه‌ای متناظر با نویسه UTF-8 آن‌ها کدبندی می‌شوند. برای مثال، 上海+中國 در UTF-8 به‌صورت %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B کدبندی نشانی وب می‌شود. رشته ? and the Mysterians به‌صورت %3F+and+the+Mysterians یا %3F%20and%20the%20Mysterians کدبندی نشانی وب می‌شود.

نویسه‌های رایجی که نیاز به کدبندی دارند

برخی‌از نویسه‌های رایج که باید کدبندی شوند عبارت‌اند از:

تبدیل نشانی وبی که از درونداد کاربر دریافت می‌کنید گاهی اوقات دشوار است. برای مثال، کاربر ممکن است نشانی را به‌صورت «5th&Main St.» وارد کند. به‌طورکلی، باید نشانی وب خود را از بخش‌های آن بسازید و هر ورودی کاربر را به‌عنوان نویسه‌های تحت‌اللفظی درنظر بگیرید.

علاوه‌براین، نشانی‌های وب برای همه سرویس‌های وب «پلاتفرم Google Maps» و «میاناهای برنامه‌سازی کاربردی وب» ایستا به ۱۶۳۸۴ نویسه محدود شده است. برای اکثر سرویس‌ها، این حد نویسه به‌ندرت نزدیک می‌شود. بااین‌حال، توجه داشته باشید که برخی‌از سرویس‌ها چندین پارامتر دارند که ممکن است منجر به نشانی‌های وب طولانی شود.

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

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

پس‌گیری نمایی

در موارد نادر، ممکن است مشکلی در درخواست شما پیش بیاید؛ ممکن است کد پاسخ HTTP‏ ۴xx یا ۵xx دریافت کنید، یا اتصال TCP ممکن است در جایی بین کارخواه شما و سرور Google با مشکل مواجه شود. اغلب، تلاش مجدد برای درخواست ارزشمند است زیرا درخواست پیگیری ممکن است درحالی‌که درخواست اصلی ناموفق بوده است موفق شود. بااین‌حال، مهم است که به‌طور مکرر درخواست به سرورهای Google ارسال نکنید. این رفتار حلقه‌ای می‌تواند شبکه بین مشتری و Google را بیش‌ازحد بار کند و برای طرف‌های زیادی مشکل ایجاد کند.

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

برای مثال، برنامه‌ای را درنظر بگیرید که این درخواست را به میانای برنامه‌سازی کاربردی «منطقه زمانی» ارسال می‌کند:

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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


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

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

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

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

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

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

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

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

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

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

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

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

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