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

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

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

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

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

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

طلب جودة الهواء الحالية كل ساعة باستخدام currentConditions نقطة النهاية عن طريق إرسال طلب HTTP POST إلى:

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

تمرير نص JSON إلى الطلب الذي يحدد الموقع.

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

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

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

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

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

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

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

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

تعيين	الأحرف	استخدام عنوان URL
أحرف أبجدية رقمية	ج ج ج ح n o p q r s 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 نفسها. على العميل.