تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

أفضل الممارسات باستخدام خدمات الويب API للطرق

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

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

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

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

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

ويكون طلب خدمة الويب عادةً من Roads API على النحو التالي بشكل عام:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

حيث يشير snapToRoads إلى الخدمة المطلوبة. وتشمل خدمات "الطرق الأخرى" nearestRoads وspeedLimits.

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

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

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

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

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

الأحرف الخاصة

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

ملخص أحرف عنوان URL الصالحة

تحديد	الشخصيات	استخدام عنوان URL
أحرف أبجدية رقمية	a 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 L M	سلاسل نصية واستخدام المخطّط (`http`) والمنفذ (`8080`) وما إلى ذلك
غير محجوز	- _ . ~	سلاسل نصية
تم الحجز	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	التحكّم في الأحرف و/أو السلاسل النصية

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

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

يتم ترميز كل الأحرف التي سيتم ترميزها باستخدام عنوان URL باستخدام حرف '%' وقيمة سداسية عشرية من حرفين مقابلة لترميز UTF-8. على سبيل المثال، سيتم ترميز 上海+中國 في UTF-8 على النحو التالي: %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 على 8192 حرفًا لجميع خدمات الويب من "منصة خرائط Google" وواجهات برمجة تطبيقات الويب الثابتة. ونادرًا ما يتم الوصول إلى هذا الحد الأقصى المسموح به في معظم الخدمات. ومع ذلك، تجدر الإشارة إلى أنّ بعض الخدمات تحتوي على عدة معلَمات قد تؤدي إلى إنشاء عناوين URL طويلة.

الاستخدام الإضافي لـ Google APIs

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

الرقود الأسي

في بعض الحالات النادرة، قد يحدث خطأ أثناء عرض طلبك، وقد تتلقّى رمز استجابة HTTP 4XX أو 5XX، أو قد يتعذّر الاتصال ببروتوكول TCP في مكان ما بين العميل وخادم Google. ومن المفيد عادةً إعادة محاولة معالجة الطلب لأنّ طلب المتابعة قد ينجح عندما يتعذّر تنفيذ الطلب الأصلي. ومع ذلك، من المهم عدم تكرار إرسال الطلبات إلى خوادم Google بشكل متكرر. وقد يؤدي هذا التكرار إلى زيادة الحمل على الشبكة بين العميل وGoogle، ما يسبب مشاكل للعديد من الجهات.

والطريقة الأفضل هي إعادة المحاولة مع زيادة حالات التأخير بين المحاولات. وعادةً ما يزداد التأخير بسبب عامل ضرب مع كل محاولة، وهو منهج يُعرف باسم السلُل الأُسي.

على سبيل المثال، يمكنك تقديم طلب لتقديم طلب إلى واجهة برمجة تطبيقات المنطقة الزمنية:

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 الأساسية ويتم التعامل معه وفقًا لذلك. ولتجنُّب ذلك، عليك التأكّد من عدم مزامنة طلبات البيانات من واجهة برمجة التطبيقات بين البرامج.

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

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

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

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

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

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

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

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