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

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

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

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

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

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

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

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

ملاحظة: جميع تطبيقات واجهة برمجة التطبيقات للمواقع الجغرافية تتطلب المصادقة. يمكنك الحصول على مزيد من المعلومات حول بيانات اعتماد المصادقة.

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

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

استخدام مهذب لواجهات 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 نفسها على العميل.