در روز انجمن توسعه‌دهندگان Google Maps Platform بعدی ما در ماه دسامبر در سانفرانسیسکو به ما بپیوندید! برای شرکت کردن، اکنون درخواست دهید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

خدمات وب «پلاتفرم 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 API از درخواست‌های HTTP یا HTTPS به نشانی‌های وب خاص استفاده می‌کنند و پارامترهای نشانی وب یا داده‌های POST با قالب JSON را به‌عنوان آرگومان به سرویس‌ها ارسال می‌کنند. به‌طور کلی، این سرویس‌ها داده‌ها را در بدنه پاسخ به‌صورت JSON برای تجزیه یا پردازش توسط برنامه شما برمی‌گردانند.

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

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

دسترسی SSL و TLS

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

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

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

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

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

خلاصه نویسه‌های معتبر نشانی وب

به‌صف	نویسه‌ها	استفاده از نشانی وب
الفباعددی	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	رشته‌های نوشتاری، استفاده از طرح (`http`)، درگاه (`8080`)، و غیره.
رزرو نشده است	- _ . ~	رشته‌های نوشتاری
رزروشده	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	نویسه‌های کنترلی و/یا رشته‌های نوشتاری

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

نویسه‌هایی که می‌خواهید مدیریت کنید خارج از مجموعه بالا قرار دارند. برای مثال، نویسه‌های زبان‌های خارجی مانند 上海+中國 باید بااستفاده از نویسه‌های بالا کدگذاری شوند. طبق قراردادهای رایج، فاصله‌ها (که در نشانی‌های وب مجاز نیستند) اغلب بااستفاده از نویسه به‌علاوه '+' نیز نشان داده می‌شوند.
نویسه‌هایی در مجموعه بالا به‌عنوان نویسه‌های رزروشده وجود دارد، اما باید به‌صورت تحت‌اللفظی استفاده شود. برای مثال، ? در نشانی‌های وب برای نشان دادن شروع رشته پُرسمان استفاده می‌شود؛ اگر بخواهید از رشته «? 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 کدبندی نشانی وب می‌شود.

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

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

شخصیت ناامن	مقدار کدبندی‌شده
فاصله	`%20`
»	`%22`
<	`%3C`
>	`%3E`
#	`%23`
٪	`%25`
\|	`%7C`

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

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

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

کارخواه‌های میانای برنامه‌سازی کاربردی که طراحی ضعیفی دارند می‌توانند بار سنگینی بر اینترنت و سرورها تحمیل کنند. این بخش حاوی روال‌های مطلوب برای کارخواه‌های API است. دنبال کردن این روال‌های مطلوب می‌تواند به جلوگیری از مسدود شدن برنامه‌تان به‌دلیل سوءاستفاده ناخواسته از 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 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 به‌طور یکنواخت درطول زمان توزیع می‌شوند. علاوه‌براین، فراخوان‌های میانای برنامه‌سازی کاربردی هنگام به‌روزرسانی نمایشگر، پردازش را به‌تأخیر نمی‌اندازند.

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

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

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

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

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

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