أفضل الممارسات باستخدام واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي"

واجهات برمجة التطبيقات الثابتة للويب في Google Maps Platform هي مجموعة من واجهات HTTP لخدمات Google التي تُنشئ صورًا يمكنك تضمينها مباشرةً في صفحة الويب.

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

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

ما هي Static Web API؟

يكون طلب البيانات من Street View Static API بشكل عام على النحو التالي:

  https://www.googleapis.com/streetview/z/x/y?parameters

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

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

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

https://maps.googleapis.com/maps/api/streetview/parameters

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

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

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

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

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

الرموز الخاصة

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

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

• الأحرف التي تريد استخدامها غير متوفّرة في المجموعة أعلاه. على سبيل المثال، يجب ترميز الأحرف المكتوبة بلغات أجنبية مثل 上海+中國 باستخدام الأحرف أعلاه. وفقًا للعرف الشائع، غالبًا ما يتم تمثيل المسافات (التي لا يُسمح بها ضمن عناوين URL) باستخدام الحرف '+' بدلاً من الرمز (+).
• تظهر الأحرف ضمن المجموعة أعلاه كأحرف محجوزة، ولكن يجب استخدامها حرفيًا. على سبيل المثال، يتم استخدام الرمز ? ضمن عناوين URL للإشارة إلى بداية سلسلة طلب البحث. إذا كنت تريد استخدام السلسلة "? and the 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.

الأحرف الشائعة التي تحتاج إلى ترميز

في ما يلي بعض الأحرف الشائعة التي يجب ترميزها:

قد يكون أحيانًا تحويل عنوان URL الذي تتلقّاه من إدخال المستخدمين معقدًا. على سبيل المثال، قد يُدخل المستخدم عنوانًا على النحو التالي: "شارع 5&Main". بشكل عام، يجب إنشاء عنوان URL من أجزائه، مع التعامل مع أي إدخال من المستخدِم كأحرف حرفية.

بالإضافة إلى ذلك، تقتصر عناوين URL على 16384 حرفًا لجميع خدمات ويب Google Maps Platform وواجهات برمجة تطبيقات الويب الثابتة. في معظم الخدمات، نادرًا ما يتم الاقتراب من هذا الحدّ الأقصى لعدد الأحرف. ومع ذلك، يُرجى العِلم أنّ بعض الخدمات تتضمّن عدة مَعلمات قد تؤدي إلى ظهور عناوين URL طويلة.

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