أفضل الممارسات باستخدام خدمات الويب لواجهة برمجة تطبيقات إحصاءات الأماكن

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

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

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

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

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

يوضّح المثال التالي عنوان URL لطلب GET في REST:

AN ACTUAL API CALL INCLUDING THE API_KEY&key=API_KEY

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

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

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

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

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

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

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

ملخّص أحرف عنوان URL الصالحة
تعيينالأحرفاستخدام عنوان URL
أحرف أبجدية رقمية a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 سلاسل نصية واستخدام المخطط (http) والمنفذ (8080) وما إلى ذلك
غير محجوز - _ . ~ سلاسل النصوص
تم الحجز ! * ( ) ; : @ & = + $ , / ? % # [ ] أحرف التحكّم و/أو السلاسل النصية

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

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

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

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

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

حرف غير آمن قيمة مشفّرة
مسافة %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

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

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

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