أفضل الممارسات باستخدام خدمات ويب الطرق على الويب

خدمات الويب "منصة خرائط Google" هي مجموعة من واجهات HTTP لخدمات Google التي توفّر بيانات جغرافية لتطبيقات الخرائط.

يصف هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد طلبات خدمة الويب ومعالجة ردود الخدمات. راجِع دليل المطوّر للاطّلاع على المستندات الكاملة حول Roads API.

ما المقصود بخدمة الويب؟

خدمات "منصة خرائط Google" على الويب هي واجهة لطلب بيانات واجهة برمجة التطبيقات للخرائط من الخدمات الخارجية واستخدام البيانات داخل تطبيقات "خرائط Google". هذه الخدمات مصمَّمة لاستخدامها مع الخريطة، وفقًا لقيود الترخيص الواردة في بنود خدمة "منصة خرائط Google".

تستخدم خدمات الويب لـ Maps APIs طلبات HTTP(S) لعناوين URL محدَّدة، مع تمرير معلمات عناوين URL و/أو بيانات POST بتنسيق JSON كوسيطات للخدمات. بشكل عام، تعرض هذه الخدمات البيانات في نص الاستجابة JSON لتحليلها و/أو معالجتها بواسطة تطبيقك.

يكون طلب خدمة الويب النموذجي لواجهة برمجة تطبيقات الطرقات بشكل عام من النموذج التالي:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

حيث يشير snapToRoads إلى الخدمة المحددة المطلوبة. تشمل خدمات الطرق الأخرى nearestRoads وspeedLimits.

ملاحظة: تتطلب تطبيقات All Roads API المصادقة. يمكنك الحصول على مزيد من المعلومات حول بيانات اعتماد المصادقة.

الوصول عبر طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS)

يجب استخدام HTTPS لكل طلبات "منصة خرائط Google" التي تستخدم مفاتيح واجهة برمجة التطبيقات أو التي تحتوي على بيانات المستخدمين. قد يتم رفض الطلبات المقدّمة عبر HTTP والتي تحتوي على بيانات حسّاسة.

إنشاء عنوان URL صالح

قد تظنّ أنّ عنوان URL "الصالح" واضح بذاته، إلا أنّ الأمر ليس كذلك. عنوان URL الذي يتم إدخاله في شريط عناوين في أحد المتصفحات، على سبيل المثال، قد يحتوي على رموز خاصة (مثل "上海+中國")؛ يحتاج المتصفّح إلى ترجمة تلك الأحرف داخليًا إلى ترميز مختلف قبل النقل. وتجدر الإشارة إلى أنّ أي رمز ينشئ أو يقبل إدخال UTF-8 قد يتعامل مع عناوين URL التي تتضمن أحرف UTF-8 على أنها "صالحة"، ولكن قد يحتاج أيضًا إلى ترجمة تلك الأحرف قبل إرسالها إلى خادم ويب. يُطلَق على هذه العملية اسم ترميز عناوين URL أو الترميز المئوية.

الأحرف الخاصة

نحتاج إلى ترجمة الرموز الخاصة لأنّ جميع عناوين URL يجب أن تتوافق مع البنية المحدّدة في مواصفات معرّف الموارد المنتظم (URI). ويعني ذلك أنّ عناوين URL يجب أن تحتوي فقط على مجموعة فرعية خاصة من أحرف ASCII وهي: الرموز الأبجدية الرقمية المألوفة وبعض الأحرف المحجوزة لاستخدامها كأحرف تحكّم ضمن عناوين URL. يلخص هذا الجدول الأحرف التالية:

ملخّص أحرف عناوين 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 طويلة.

استخدام مهذب لواجهات Google APIs

يمكن لبرامج واجهة برمجة التطبيقات ذات التصميم السيئ تحميل حملاً أكثر من اللازم على كل من خوادم الإنترنت وخوادم Google. يحتوي هذا القسم على بعض أفضل الممارسات لعملاء واجهات برمجة التطبيقات. يمكن أن يساعدك اتّباع أفضل الممارسات هذه في تجنُّب حظر تطبيقك بسبب إساءة استخدام واجهات برمجة التطبيقات عن غير قصد.

تراجع أسي

في حالات نادرة، قد يحدث خطأ ما أثناء تنفيذ طلبك، وقد تتلقى رمز استجابة HTTP 4XX أو 5XX، أو قد يفشل اتصال بروتوكول التحكم بالنقل في مكان ما بين العميل وخادم Google. وغالبًا ما يكون من المفيد إعادة محاولة الطلب، لأن طلب المتابعة قد ينجح في حال فشل الطلب الأصلي. ومع ذلك، من المهم عدم تكرار إجراء الطلبات إلى خوادم Google بشكل متكرر. ويمكن أن يؤدي سلوك التكرار هذا إلى تحميل زائد على الشبكة بين العميل وGoogle، مما يتسبب في حدوث مشكلات للعديد من الأطراف.

تتمثل الطريقة الأفضل في إعادة المحاولة مع زيادة التأخيرات بين المحاولات. عادةً ما يزداد التأخير بعامل ضرب مع كل محاولة، وهو أسلوب يُعرف باسم التراجع الأُسيّ.

على سبيل المثال، جرّب أحد التطبيقات التي تريد إرسال هذا الطلب إلى واجهة برمجة التطبيقات Time Zone:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

يوضح مثال بايثون التالي كيفية إجراء الطلب باستخدام تراجع أسي:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

يجب أيضًا توخي الحذر لعدم وجود رمز لإعادة محاولة إدخال رمز أعلى في سلسلة استدعاءات التطبيق يؤدي إلى تكرار الطلبات في تتابع سريع.

الطلبات المتزامنة

قد تبدو الأعداد الكبيرة من الطلبات المتزامنة إلى واجهات برمجة تطبيقات Google كهجوم لحجب الخدمة الموزعة (DDoS) على البنية الأساسية لـ Google، وسيتم التعامل معه وفقًا لذلك. ولتجنّب ذلك، عليك التأكّد من عدم مزامنة طلبات واجهة برمجة التطبيقات بين العملاء.

على سبيل المثال، جرِّب تطبيقًا يعرض الوقت في المنطقة الزمنية الحالية. من المحتمل أن يضبط هذا التطبيق منبهًا في نظام تشغيل العميل لإيقاظه في بداية الدقيقة حتى يتم تحديث الوقت المعروض. يجب ألا يُجري التطبيق أي طلبات بيانات من واجهة برمجة التطبيقات كجزء من المعالجة المرتبطة بهذا المنبّه.

يُعدّ إجراء طلبات بيانات من واجهة برمجة التطبيقات استجابةً لأحد المنبّهات الثابتة إجراءً سيئًا لأنّه يؤدي إلى مزامنة طلبات البيانات من واجهة برمجة التطبيقات مع بداية الدقيقة، حتى بين الأجهزة المختلفة، بدلاً من توزيعها بالتساوي على مدار الوقت. فالتطبيق المصمم بشكل سيئ للقيام بذلك سينتج عنه زيادة في حركة المرور بستين ضعف المستويات العادية في بداية كل دقيقة.

بدلاً من ذلك، فإن أحد التصميمات الجيدة المحتملة هو ضبط منبه ثانٍ على وقت يتم اختياره عشوائيًا. عندما ينشط هذا التنبيه الثاني، يستدعي التطبيق أي واجهات برمجة تطبيقات يحتاجها ويخزِّن النتائج. عندما يريد التطبيق تحديث عرضه في بداية الدقيقة، فإنه يستخدم النتائج المخزنة مسبقًا بدلاً من استدعاء واجهة برمجة التطبيقات مرة أخرى. من خلال هذا النهج، يتم توزيع طلبات البيانات من واجهة برمجة التطبيقات بالتساوي على مدار الوقت. علاوة على ذلك، لا تؤخّر طلبات البيانات من واجهة برمجة التطبيقات العرض عند تحديث الشاشة.

بغض النظر عن بداية الدقيقة، يجب أن تحرص على عدم استهدافها في بداية الساعة، كما أنّ وقت بدء كل يوم في منتصف الليل.

جارٍ معالجة الردود

يناقش هذا القسم كيفية استخراج هذه القيم ديناميكيًا من ردود خدمة الويب.

تقدّم خدمات "خرائط Google" على الويب ردودًا سهلة الفهم، ولكنّها ليست سهلة الاستخدام. عند إجراء استعلام، بدلاً من عرض مجموعة من البيانات، ربما تريد استخراج بعض القيم المحددة. بشكل عام، ستحتاج إلى تحليل الردود من خدمة الويب واستخراج القيم التي تهمك فقط.

يعتمد نظام التحليل الذي تستخدمه على ما إذا كنت تعرض الإخراج بتنسيق JSON أم لا. يمكن أن تتم معالجة استجابات JSON، التي تكون في شكل كائنات JavaScript، ضمن JavaScript نفسها على العميل.