واجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط Google" هي مجموعة من واجهات HTTP لخدمات Google التي تنشئ صورًا يمكنك تضمينها مباشرةً في صفحة الويب.
يوضّح هذا الدليل بعض الممارسات الشائعة التي يمكنك اتّخاذها لإعداد طلبات الصور ومعالجة ردود الخدمة. لمزيد من المعلومات حول Maps Static API، يُرجى الاطّلاع على دليل المطوّرين.
ما هي واجهة برمجة تطبيقات الويب الثابتة؟
تتيح لك واجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط Google" تضمين صورة من "خرائط Google" في صفحة الويب بدون الحاجة إلى JavaScript أو أي تحميل ديناميكي للصفحة. تنشئ واجهات برمجة التطبيقات الثابتة على الويب صورة استنادًا إلى مَعلمات عنوان URL التي يتم إرسالها باستخدام طلب HTTPS عادي.
يتضمّن طلب Maps Static API النموذجي الشكل التالي:
https://www.googleapis.com/staticmap/z/x/y?parameters
ملاحظة: تتطلّب جميع تطبيقات Maps Static API المصادقة. لمزيد من المعلومات، يُرجى الاطّلاع على بيانات اعتماد المصادقة.
الوصول إلى بروتوكول أمان طبقة النقل (TLS)
يجب استخدام بروتوكول HTTPS في جميع الطلبات المرسَلة إلى "منصة خرائط Google" التي تستخدم مفاتيح واجهة برمجة التطبيقات أو تتضمّن بيانات المستخدمين. قد يتم رفض الطلبات التي يتم إجراؤها عبر HTTP والتي تتضمّن بيانات حساسة.
إنشاء عنوان URL صالح
قد يبدو لك أنّ عنوان URL "صالح" هو أمر بديهي، ولكن هذا ليس صحيحًا تمامًا. قد يحتوي عنوان URL تم إدخاله في شريط العناوين في متصفّح، على سبيل المثال، على رموز خاصة (مثل "上海+中國")، ويحتاج المتصفّح إلى ترجمة هذه الرموز داخليًا إلى ترميز مختلف قبل الإرسال.
وبالمثل، قد يتعامل أي رمز برمجي ينشئ أو يقبل إدخال 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 على شكل %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B في عنوان URL. سيتم ترميز السلسلة ? and the Mysterians باستخدام عنوان URL على النحو التالي: %3F+and+the+Mysterians أو %3F%20and%20the%20Mysterians.
الأحرف الشائعة التي يجب ترميزها
في ما يلي بعض الأحرف الشائعة التي يجب ترميزها:
| حرف غير آمن | القيمة المشفرة |
|---|---|
| مسافة | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
قد يكون تحويل عنوان URL الذي تتلقّاه من بيانات أدخلها المستخدم أمرًا صعبًا في بعض الأحيان. على سبيل المثال، قد يُدخل المستخدم عنوانًا على النحو التالي: "5th&Main St." بشكل عام، يجب إنشاء عنوان URL من أجزائه، مع التعامل مع أي بيانات أدخلها المستخدم كأحرف حرفية.
بالإضافة إلى ذلك، يقتصر عدد الأحرف في عناوين URL على 16384 حرفًا لجميع خدمات الويب الثابتة وواجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط Google". في معظم الخدمات، نادرًا ما يتم بلوغ الحد الأقصى لعدد الأحرف المسموح به. ومع ذلك، تجدر الإشارة إلى أنّ بعض الخدمات تتضمّن عدة مَعلمات قد تؤدي إلى إنشاء عناوين URL طويلة.