واجهات برمجة التطبيقات الثابتة للويب في Google Maps Platform هي مجموعة من واجهات HTTP لخدمات Google التي تُنشئ صورًا يمكنك تضمينها مباشرةً في صفحة الويب.
يصف هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد طلبات صورك ومعالجة ردود الخدمة. يُرجى الرجوع إلى دليل المطوّر للاطّلاع على المستندات الكاملة لواجهة برمجة التطبيقات "الخرائط الثابتة".
ما هي Static Web API؟
تتيح لك واجهات برمجة التطبيقات الثابتة للويب في "منصّة خرائط Google" تضمين صورة من "خرائط Google" في صفحة الويب بدون الحاجة إلى JavaScript أو أيّ تحميل ديناميكي للصفحات. تنشئ واجهات برمجة التطبيقات الثابتة للويب صورة استنادًا إلى مَعلمات عناوين URL التي يتم إرسالها باستخدام طلب HTTPS عادي.يكون طلب البيانات من واجهة برمجة التطبيقات Maps Static API بشكل عام على النحو التالي:
https://www.googleapis.com/staticmap/z/x/y?parameters
ملاحظة: تتطلّب جميع تطبيقات Maps Static API المصادقة. اطّلِع على مزيد من المعلومات عن بيانات اعتماد المصادقة.
الوصول إلى طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل الآمنة
يجب استخدام بروتوكول HTTPS مع جميع طلبات "منصّة خرائط Google" التي تستخدِم مفاتيح واجهة برمجة التطبيقات أو تحتوي على data المستخدم. قد يتم رفض الطلبات التي يتم إجراؤها عبر HTTP والتي تحتوي على بيانات حسّاسة.
إنشاء عنوان URL صالح
قد تعتقد أنّ عنوان URL "صالح" هو أمر واضح، ولكن
هذا ليس صحيحًا تمامًا. على سبيل المثال، قد يحتوي عنوان URL الذي يتم إدخاله في شريط العناوين في browser على أحرف خاصة (مثل
"上海+中國")، ويجب أن يترجم المتصفّح تلك الأحرف داخليًا
إلى ترميز مختلف قبل الإرسال.
وبالمثل، أي رمز ينشئ إدخال UTF-8 أو يقبله
قد يتعامل مع عناوين URL التي تحتوي على أحرف UTF-8 على أنّها "صالحة"، ولكنّه سيحتاج أيضًا إلى
ترجمة هذه الأحرف قبل إرسالها إلى خادم ويب.
تُعرف هذه العملية باسم
ترميز عنوان URL أو ترميز النسبة المئوية.
الرموز الخاصة
نحتاج إلى ترجمة الأحرف الخاصة لأنّه يجب أن تتوافق جميع عناوين URL مع البنية المحدّدة في مواصفات معرِّف الموارد المنتظم (URI). وهذا يعني أنّ عناوين URL повинна تتضمّن فقط مجموعة فرعية خاصة من أحرف ASCII: الرموز الأبجدية الرقمية المألوفة، وبعض الأحرف المحجوزة لاستخدامها كرموز التحكّم في عناوين URL. ويلخّص هذا الجدول هذه الأحرف:
| تأهّب | الأحرف | استخدام عنوان URL |
|---|---|---|
| أحرف أبجدية رقمية | 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) وما إلى ذلك |
| غير محجوز | - _ . ~ | سلاسل النصوص |
| تم الحجز | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | أحرف التحكّم و/أو السلاسل النصية |
عند إنشاء عنوان URL صالح، يجب التأكّد من أنّه يحتوي على الأحرف المعروضة في جدول فقط. يؤدي جعل عنوان URL متوافقًا مع هذه المجموعة من الأحرف بشكل عام إلى حدوث مشكلتَين، إحداهما متعلقة بالإغفال والأخرى متعلقة بالاستبدال:
- الأحرف التي تريد استخدامها غير متوفّرة في المجموعة
أعلاه. على سبيل المثال، يجب ترميز الأحرف المكتوبة بلغات أجنبية
مثل
上海+中國باستخدام الأحرف أعلاه. وفقًا للعرف الشائع، غالبًا ما يتم تمثيل المسافات (التي لا يُسمح بها ضمن عناوين URL) باستخدام الحرف'+'بدلاً من الرمز (+). - تظهر الأحرف ضمن المجموعة أعلاه كأحرف محجوزة،
ولكن يجب استخدامها حرفيًا.
على سبيل المثال، يتم استخدام الرمز
?ضمن عناوين URL للإشارة إلى بداية سلسلة طلب البحث. إذا كنت تريد استخدام السلسلة "? and the Mysterions"، عليك ترميز الحرف'?'.
يتم ترميز جميع الأحرف التي سيتم ترميزها باستخدام عنوان URL
باستخدام الحرف '%' وقيمة سداسية تشكل حرفين
تتوافق مع حرف UTF-8. على سبيل المثال، سيتم ترميز
上海+中國 بترميز UTF-8 في عنوان URL على النحو التالي:
%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 الذي تتلقّاه من إدخال المستخدمين في بعض الأحيان صعبًا. على سبيل المثال، قد يُدخل المستخدم عنوانًا على النحو التالي: "شارع 5&Main". بشكل عام، يجب إنشاء عنوان URL من أجزائه، مع التعامل مع أي إدخال من المستخدِم كأحرف حرفية.
بالإضافة إلى ذلك، تقتصر عناوين URL على 16384 حرفًا لجميع خدمات ويب Google Maps Platform وواجهات برمجة تطبيقات الويب الثابتة. في معظم الخدمات، نادرًا ما يتم الاقتراب من هذا الحدّ الأقصى لعدد الأحرف. ومع ذلك، يُرجى العِلم أنّ بعض الخدمات تتضمّن عدة مَعلمات قد تؤدي إلى ظهور عناوين URL طويلة.