APIهای وب استاتیک پلتفرم Google Maps مجموعه‌ای از رابط‌های HTTP برای سرویس‌های Google هستند که تصاویری را تولید می‌کنند که می‌توانید مستقیماً در صفحه وب خود جاسازی کنید.
این راهنما برخی از روش‌های رایج مفید برای تنظیم درخواست‌های تصویر و پردازش پاسخ‌های سرویس را شرح می‌دهد. برای مستندات کامل Maps Static API به راهنمای توسعه‌دهنده مراجعه کنید.
Static Web API چیست؟
APIهای وب استاتیک پلتفرم Google Maps به شما امکان می دهند بدون نیاز به جاوا اسکریپت یا هر بارگذاری صفحه پویا، یک تصویر Google Maps را در صفحه وب خود جاسازی کنید. APIهای وب استاتیک یک تصویر را بر اساس پارامترهای URL ایجاد می کنند که با استفاده از یک درخواست استاندارد HTTPS ارسال می شوند.یک درخواست معمولی Maps Static API معمولاً به شکل زیر است:
https://www.googleapis.com/staticmap/z/x/y?parameters
توجه : همه برنامه‌های Maps Static API نیاز به احراز هویت دارند. اطلاعات بیشتری در مورد اعتبار احراز هویت دریافت کنید.
دسترسی SSL/TLS
HTTPS برای همه درخواست‌های پلتفرم Google Maps که از کلیدهای API استفاده می‌کنند یا حاوی داده‌های کاربر هستند، لازم است. درخواست‌های ارسال شده از طریق HTTP که حاوی داده‌های حساس هستند ممکن است رد شوند.
ساخت یک URL معتبر
ممکن است فکر کنید که URL "معتبر" بدیهی است، اما کاملاً اینطور نیست. برای مثال، URL وارد شده در یک نوار آدرس در مرورگر، ممکن است حاوی کاراکترهای خاصی باشد (به عنوان مثال "上海+中國" ). مرورگر باید آن کاراکترها را به صورت داخلی قبل از انتقال به رمزگذاری دیگری ترجمه کند. به همین ترتیب، هر کدی که ورودی UTF-8 را تولید یا قبول می کند، ممکن است URL های دارای کاراکترهای UTF-8 را به عنوان "معتبر" تلقی کند، اما همچنین باید آن کاراکترها را قبل از ارسال به سرور وب ترجمه کند. این فرآیند کدگذاری URL یا رمزگذاری درصد نامیده می شود.
شخصیت های خاص
ما باید کاراکترهای ویژه را ترجمه کنیم زیرا همه URL ها باید با نحو مشخص شده توسط مشخصات Uniform Resource Identifier (URI) مطابقت داشته باشند. در واقع، این بدان معنی است که URL ها باید فقط شامل یک زیرمجموعه خاص از کاراکترهای ASCII باشند: نمادهای الفبایی عددی آشنا، و برخی از کاراکترهای رزرو شده برای استفاده به عنوان کاراکترهای کنترل در URL. این جدول به طور خلاصه این شخصیت ها را نشان می دهد:
| تنظیم کنید | شخصیت ها | استفاده از URL |
|---|---|---|
| الفبایی | abcdefghijklm nopqrstuvwxyz ABCDEFGHIJKLM NOPQRSTUVWXYZ 0 1 2 3 4 5 6 7 8 9 | رشته های متنی، استفاده از طرح ( http )، پورت ( 8080 )، و غیره. |
| بدون رزرو | - _ . ~ | رشته های متنی |
| رزرو شده است | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | کاراکترها و/یا رشته های متنی را کنترل کنید |
هنگام ساختن یک URL معتبر، باید مطمئن شوید که فقط شامل کاراکترهای نشان داده شده در جدول باشد. تطبیق یک URL برای استفاده از این مجموعه از کاراکترها به طور کلی منجر به دو مشکل می شود، یکی حذف و دیگری جایگزینی:
- کاراکترهایی که می خواهید آنها را مدیریت کنید خارج از مجموعه فوق وجود دارند. برای مثال، کاراکترهای زبان‌های خارجی مانند
上海+中國باید با استفاده از کاراکترهای بالا کدگذاری شوند. طبق قرارداد رایج، فضاها (که در URL ها مجاز نیستند) اغلب با استفاده از کاراکتر'+'نیز نمایش داده می شوند. - کاراکترها در مجموعه فوق به عنوان کاراکترهای رزرو شده وجود دارند، اما باید به معنای واقعی کلمه استفاده شوند. به عنوان مثال
?در URL ها برای نشان دادن ابتدای رشته پرس و جو استفاده می شود. اگر می خواهید از رشته "? and the Mysterions" استفاده کنید، باید'?'را رمزگذاری کنید. شخصیت
همه کاراکترهایی که باید با URL رمزگذاری شوند با استفاده از یک کاراکتر '%' و یک مقدار هگز دو نویسه مطابق با نویسه UTF-8 کدگذاری می شوند. به عنوان مثال،上海+中國در UTF-8 به صورت %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B کدگذاری می‌شود. رشته ? and the Mysterians با URL به صورت %3F+and+the+Mysterians یا %3F%20and%20the%20Mysterians کدگذاری می شوند.
کاراکترهای رایج که نیاز به رمزگذاری دارند
برخی از کاراکترهای رایجی که باید کدگذاری شوند عبارتند از:
| شخصیت ناامن | مقدار رمزگذاری شده |
|---|---|
| فضا | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
تبدیل URL که از ورودی کاربر دریافت می کنید گاهی اوقات مشکل است. به عنوان مثال، کاربر ممکن است آدرسی را به عنوان "خیابان پنجم و اصلی" وارد کند. به طور کلی، شما باید URL خود را از قسمت های آن بسازید و هر ورودی کاربر را به عنوان کاراکتر تحت اللفظی در نظر بگیرید.
علاوه بر این، URLها برای همه سرویس‌های وب پلتفرم Google Maps و APIهای وب استاتیک به ۱۶۳۸۴ کاراکتر محدود می‌شوند. برای اکثر سرویس ها، به ندرت به این محدودیت شخصیت نزدیک می شود. با این حال، توجه داشته باشید که برخی از سرویس ها دارای چندین پارامتر هستند که ممکن است منجر به URL های طولانی شود.