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

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

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

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

تعمل واجهة برمجة التطبيقات الثابتة في "التجوّل الافتراضي" مثل واجهة برمجة تطبيقات ثابتة على الويب، في حين يمكن اعتبار خدمة البيانات الوصفية بمثابة خدمة ويب. للحصول على مزيد من المعلومات عن خدمة البيانات الوصفية، يمكنك الاطلاع على البيانات الوصفية لصور التجوّل الافتراضي.

ما المقصود بواجهة برمجة تطبيقات الويب الثابتة؟

تتيح لك واجهات برمجة التطبيقات الثابتة على "منصة خرائط Google" إمكانية تضمين صورة في "خرائط Google" على صفحة الويب، وذلك بدون طلب JavaScript أو أي تحميل ديناميكي للصفحة. تنشئ واجهات برمجة التطبيقات صورة استنادًا إلى معلَمات عناوين URL التي يتم إرسالها من خلال طلب HTTP عادي وتسمح لك بعرض النتيجة على صفحة الويب.

بشكل عام، يكون طلب واجهة برمجة التطبيقات الثابتة في ميزة "التجوّل الافتراضي" الشكل التالي:

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

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

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

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

يكون طلب البيانات الوصفية لواجهة برمجة التطبيقات لميزة "التجوّل الافتراضي" بالشكل التالي:

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

ملاحظة: تتطلب جميع تطبيقات واجهة برمجة التطبيقات الثابتة في "التجوّل الافتراضي" مصادقة. تعرَّف على المزيد من المعلومات عن بيانات اعتماد المصادقة.

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

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

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

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

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

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

تحديد	الأحرف	استخدام عنوان URL
أحرف أبجدية رقمية	أ ب	سلاسل نصية واستخدام المخطّط (http) والمنفذ (8080) وما إلى ذلك
غير محجوز	- _ . ~	سلاسل نصية
تم الحجز	! * ' ( ) ; : @ & = + $ , / ? نسبة # [ ]	التحكم في الأحرف و/أو السلاسل النصية

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

• الأحرف التي تريد التعامل معها تقع خارج المجموعة المذكورة أعلاه. على سبيل المثال، يجب ترميز الأحرف في اللغات الأجنبية مثل 上海+中國. وفقًا للتقاليد الشائعة، غالبًا ما يتم تمثيل المسافات (غير المسموح بها ضمن عناوين URL) باستخدام حرف '+' الإضافي أيضًا.
• هناك أحرف ضمن المجموعة أعلاه كأحرف محجوزة، ولكن يجب استخدامها حرفيًا. على سبيل المثال، يتم استخدام ? داخل عناوين URL للإشارة إلى بداية سلسلة طلب البحث، وإذا كنت تريد استخدام السلسلة &quot، والأسطورة&;;&، تحتاج إلى ترميز الحرف '?'.

ويتم ترميز جميع الأحرف التي يتم ترميزها باستخدام عنوان URL باستخدام حرف '%' وقيمة سداسية عشرية من حرفَين متوافقة مع حرف UTF-8. على سبيل المثال، يتم ترميز 上海+中國 في UTF-8 بعنوان URL على أنه %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. سيتم ترميز السلسلة ? and the Mysterians على النحو التالي: %3F+and+the+Mysterians أو %3F%20and%20the%20Mysterians.

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

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

حرف غير آمن	القيمة المشفَّرة
مفتاح المسافة	%20
"	%22
<	%3C
>	%3E
الرقم	%23
نسبة مئوية	%25
|	%7C

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

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

الاستخدام الإضافي لـ Google APIs

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

عودة أسية

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

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

على سبيل المثال، يمكنك تقديم تطبيق يريد إرسال هذا الطلب إلى واجهة برمجة التطبيقات الخاصة بمنطقة المنطقة الزمنية:

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، ويتم التعامل معها وفقًا لذلك. لتجنب حدوث ذلك، يجب التأكّد من عدم مزامنة طلبات البيانات من واجهة برمجة التطبيقات بين البرامج.

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

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

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

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

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

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

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

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