واجهات برمجة تطبيقات الويب الثابتة في "منصة خرائط Google" هي مجموعة من واجهات HTTP لخدمات Google التي تنشئ صورًا يمكنك تضمينها مباشرةً في صفحتك على الويب.
يصف هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد طلبات الصور ومعالجة الردود عليها. يُرجى الرجوع إلى دليل المطوّر للاطّلاع على المستندات الكاملة حول Maps Static API.
ما المقصود بواجهة برمجة تطبيقات الويب الثابتة؟
تتيح لك واجهات برمجة تطبيقات الويب الثابتة في "منصة خرائط Google" تضمين صورة من "خرائط Google" في صفحتك على الويب بدون الحاجة إلى JavaScript أو أي تحميل ديناميكي للصفحة. تنشئ واجهات برمجة تطبيقات الويب الثابتة صورة استنادًا إلى معلَمات عناوين URL التي يتم إرسالها باستخدام طلب HTTPS عادي.يكون الطلب النموذجي لواجهة برمجة تطبيقات الخرائط الثابتة بشكل عام على النحو التالي:
https://www.googleapis.com/staticmap/z/x/y?parameters
ملاحظة: تتطلب جميع تطبيقات واجهة برمجة التطبيقات الثابتة لتطبيق "خرائط Google" مصادقة. يمكنك الحصول على مزيد من المعلومات حول بيانات اعتماد المصادقة.
الوصول عبر طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (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 للإشارة إلى بداية سلسلة طلب البحث. وإذا كنت تريد استخدام السلسلة "? and 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 شارع جامعة الدول العربية". بشكل عام، يجب إنشاء عنوان URL من أجزائه، مع التعامل مع أي إدخال للمستخدم كأحرف حرفية.
بالإضافة إلى ذلك، تقتصر عناوين URL على 16384 حرفًا لجميع خدمات الويب في "منصة خرائط Google" وواجهات برمجة تطبيقات الويب الثابتة. نادرًا ما يتم تطبيق هذا العدد المسموح به في معظم الخدمات، مع ذلك، يُرجى العلم أنّ بعض الخدمات تتضمّن عدة معلَمات قد تؤدي إلى إنشاء عناوين URL طويلة.