أفضل الممارسات باستخدام خدمات Pollen API على الويب

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

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

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

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

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

يوضّح المثال التالي عنوان URL لطلب GET REST إلى طريقة forecast:lookup:

https://pollen.googleapis.com/v1/forecast:lookup?&key=API_KEY

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

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

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

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

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

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

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

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