واجهات برمجة التطبيقات الثابتة للويب على "منصة خرائط Google" هي مجموعة من واجهات HTTP لخدمات Google التي تنشئ الصور التي يمكنك تضمينها مباشرةً في صفحة الويب الخاصة بك.
يشرح هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد الصور ومعالجة الطلبات المتعلّقة بالردود على الخدمة. ارجع إلى دليل مطوّر البرامج للحصول على مستندات كاملة عن API للخرائط الثابتة.
ما المقصود بواجهة برمجة تطبيقات الويب الثابتة؟
تتيح لك واجهات برمجة التطبيقات الثابتة على "منصة خرائط Google" إمكانية تضمين صورة في "خرائط Google" على صفحة الويب، وذلك بدون طلب JavaScript أو أي تحميل ديناميكي للصفحة. تنشئ واجهات برمجة التطبيقات صورة استنادًا إلى معلَمات عناوين URL التي يتم إرسالها من خلال طلب HTTP عادي وتسمح لك بعرض النتيجة على صفحة الويب.بشكل عام، يكون طلب API الثابت للخرائط على النحو التالي:
https://maps.googleapis.com/maps/api/staticmap?parameters
ملاحظة: تتطلب جميع تطبيقات API الثابتة في "خرائط Google" المصادقة. تعرَّف على المزيد من المعلومات عن بيانات اعتماد المصادقة.
الوصول إلى طبقة المقابس الآمنة (SSL)/طبقة النقل الآمنة (TLS)
يجب استخدام HTTPS لكل طلبات "منصة خرائط Google" التي تستخدم مفاتيح واجهة برمجة التطبيقات أو تتضمّن بيانات المستخدمين. قد يتم رفض الطلبات المقدَّمة عبر HTTP والتي تحتوي على بيانات حساسة.
إنشاء عنوان URL صالح
قد تظن أنّ عنوان URL الخاص بـ " متوفّر; "واضح أنّه يجب أن يكون مفهومًا ذاتيًا, لكن
هذا ليس صحيحًا. على سبيل المثال، قد يحتوي عنوان URL الذي يتم إدخاله في شريط عناوين في أحد المتصفّحات على رموز خاصة (مثل "上海+中國")، على المتصفّح ترجمة هذه الأحرف داخليًا إلى ترميز مختلف قبل نقلها.
بالإضافة إلى ذلك، إنّ أي رمز ينشئ أو يقبل إدخال UTF-8
قد يتعامل مع عناوين URL التي تحتوي على أحرف UTF-8 على أنّها &&;;quot;valid" ولكن قد تحتاج أيضًا إلى ترجمة تلك الأحرف قبل إرسالها إلى خادم ويب.
وتسمى هذه العملية
ترميز عنوان 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 على النحو التالي: %3F+and+the+Mysterians أو %3F%20and%20the%20Mysterians.
الأحرف الشائعة التي تحتاج إلى ترميز
في ما يلي بعض الأحرف الشائعة التي يجب ترميزها:
| حرف غير آمن | القيمة المشفَّرة |
|---|---|
| مفتاح المسافة | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| الرقم | %23 |
| نسبة مئوية | %25 |
| | | %7C |
قد يصعب أحيانًا تحويل عنوان URL الذي تتلقّاه من المستخدم. على سبيل المثال، قد يُدخل المستخدم عنوانًا بالشكل التالي: "5&&&;&; الشارع الرئيسي&; وبشكل عام، يجب إنشاء عنوان URL من أجزاءه، مع التعامل مع أي إدخالات للمستخدمين على أنها أحرف حرفية.
بالإضافة إلى ذلك، تقتصر عناوين URL على 8192 حرفًا لجميع خدمات الويب على "منصة خرائط Google" وواجهات برمجة التطبيقات الثابتة للويب. نادرًا ما يقترب عدد الأحرف المسموح به في معظم الخدمات. ومع ذلك، تجدر الإشارة إلى أن بعض الخدمات تتضمّن عدة معلّمات قد تؤدي إلى عناوين URL طويلة.