ندعوك للانضمام إلينا في يوم منتدى مطوّري "منصة خرائط Google" القادم في سان فرانسيسكو في ديسمبر. قدِّم طلبك الآن لحضور الفعالية.

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

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

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

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

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

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

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

يمكنك التحقّق من صحة عنوان من خلال إرسال طلب HTTP POST إلى طريقة validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress

أرسِل نص JSON إلى الطلب الذي يحدّد العنوان المطلوب التحقّق منه

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

الوصول إلى 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 للإشارة إلى بداية سلسلة طلب البحث. إذا أردت استخدام السلسلة "? and the Mysterions"، عليك ترميز الحرف '?'.

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

بالإضافة إلى ذلك، يقتصر طول عناوين URL على 16, 384 حرفًا لجميع خدمات الويب وواجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط 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

يوضّح مثال 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 نفسها على العميل.

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