أفضل الممارسات باستخدام خدمات ويب واجهة برمجة التطبيقات للمواقع الجغرافية

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

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

ما هي خدمة الويب؟

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

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

يتم إرسال طلبات الموقع الجغرافي باستخدام POST إلى عنوان URL التالي:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

ملاحظة: تتطلّب جميع تطبيقات Geolocation API المصادقة. اطّلِع على مزيد من المعلومات عن بيانات اعتماد المصادقة.

الوصول إلى طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل الآمنة

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

الاستخدام اللائق لواجهات برمجة تطبيقات Google

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

الرقود الأسي

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

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

على سبيل المثال، لنفترض أنّ هناك تطبيقًا يريد إرسال هذا الطلب إلى Time Zone API:

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

يوضّح مثال Python التالي كيفية تقديم الطلب باستخدام ميزة "التوقّف المؤقت للانتظار العشوائي":

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 نفسه على العميل.