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