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

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

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

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

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

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

ومن الأمثلة على طلب خدمة الويب طلب البيانات الوصفية لميزة "التجوّل الافتراضي" والذي يكون بالشكل التالي:

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

ملاحظة: تتطلب جميع تطبيقات Map Tiles API المصادقة. مزيد من المعلومات عن بيانات اعتماد المصادقة

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

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

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

يمكن لعملاء واجهة برمجة التطبيقات ذوي التصميم السيئ وضع حمل أكبر من اللازم على كل من الإنترنت خوادم 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

يوضح مثال بايثون التالي كيفية تقديم الطلب باستخدام خوارزمية الرقود الأسي الثنائي:

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