أفضل الممارسات لاستخدام Street View Static API

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

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

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

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

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

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

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

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

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

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

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

يكون طلب البيانات الوصفية في Street View Static API بالشكل التالي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الاستخدام المهذّب لواجهات Google API

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

الرقود الأسي الثنائي

في حالات نادرة، قد يحدث خطأ في طلبك، وقد تتلقّى رمز استجابة 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

تأكَّد من عدم وجود رمز إعادة محاولة أعلى في سلسلة طلبات التطبيق يؤدي إلى تكرار الطلبات بشكل متسلسل وسريع.

الطلبات المتزامنة

قد تبدو الأعداد الكبيرة من الطلبات المتزامنة إلى واجهات برمجة التطبيقات من Google وكأنّها هجوم حجب الخدمة الموزّع (DDoS) على البنية الأساسية من Google، وسيتم التعامل معها على هذا الأساس. لتجنُّب هذه المشكلة، تأكَّد من عدم مزامنة طلبات واجهة برمجة التطبيقات بين العملاء.

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

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

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

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

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

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

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

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

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